16 Mar, 2020

User Experiences for IAM on the Web

  • Johann Nallathamby
  • Director - Solutions Architecture - WSO2


When evaluating Identity and Access Management (IAM) vendors, one of the key aspects that organizations look for is the user experience. This aspect is stronger in Customer IAM (CIAM) compared to workforce IAM. There are two primary requirements organizations must evaluate IAM vendors on when they focus on user experience. One is the amount of disruption the IAM system may cause users when redirecting them from the service provider to other applications. The other is the ability to customize the look and feel of the end-user facing user interfaces (UI) to ensure consistency with the organizational branding.

The following is a typical list of end-user functions that can be found in an IAM system (this is by no means an exhaustive list):

  • Login
  • Logout
  • Requested consent approval/denial
  • Username recovery
  • Password recovery
  • User self-registration
  • Self-service management
    • Password management
    • Profile management
    • Security management
    • Linked accounts management
    • Consent management
    • Session management
    • Application Store

In this article, I will mainly focus on the user experiences for IAM on the web. In order to cater to organizational requirements, most IAM vendors largely provide two types of user experiences for the web in IAM:

  1. Redirect experience
  2. Embedded experience

Redirect Experience

Redirect experience refers to when an end-user is redirected via the browser from the service provider domain to another domain in order to perform IAM functions. These include:

  1. White Labeled Applications
  2. External Applications
  3. JavaScript Parent/Child Windows or Modals
  4. Preemptive Authentication
  5. Passive Home Realm Discovery

White Labeled Applications

Many IAM vendors provide white labeled applications for end-user interactions that are meant to be customized by the organization.

White labeled applications in WSO2 Identity Server come in two forms. The applications for login, logout, requested consent approval/denial, username recovery, password recovery, and user self-registration come as Java web applications that are written using servlets and JSPs, and the user portal application which contains functionality for self-service management comes in the form of a Jaggery application. From WSO2 Identity Server version 5.10.0 onwards, this Jaggery application will be replaced with a Single Page Application (SPA) written in ReactJS.

If you’re using older versions of WSO2 Identity Server, patching works as follows:

  • For the Java web application, the web application archive (WAR) is entirely replaced by the patched web application archive. When patching this application, any customizations related to branding or otherwise will be overwritten. You will have to reapply the customizations on the patched WAR file. To minimize the frequency of this happening, WSO2 follows a proper MVC architecture and avoids any business logic (Model) in the WAR files. The only logic you can find in the WAR files is for rendering the UI (View).
  • For the Jaggery application, WSO2 Update Manager (WUM) 3.0 supports in place updates. If conflicts are discovered during the patching process, the tool itself notifies the user to resolve conflicts in order to continue the process.

Another practice followed by some organizations is to host all end-user accessible web applications in a dedicated web application container technology or under a dedicated domain name. The built-in web applications in WSO2 Identity Server can be moved outside of the product’s process and hosted in another Java web application container of your choice such as JBoss, Tomcat, etc. under a different domain name.

External Applications

Another option widely provided by IAM vendors is to use external applications for end-user interactions. This works by making a contract between the user interfaces and the IAM service. Usually, IAM vendors would specify the following in this contract:

  1. HTTP level parameters that are sent to the external applications when the IAM service needs to render some user interface to the end-user.
  2. HTTP level parameters that have to be posted back to the callback URI of the IAM service in order to continue the processing from where it left off.

For example, in the username/password authenticator of WSO2 Identity Server, the post body parameters “username” and “password” are part of the contract. For consent flows, the consent purpose names and PII category names are dynamic parameters that are part of the contract. The query parameter “sessionDataKey” is a special parameter used by the IAM system in many of the flows to load back the request context once the external application has submitted the user input.

The main benefit of using externalized applications is that it is technology agnostic. External applications can be developed in the technology of choice by the organization and don’t necessarily have to use the technology that was used to build the IAM service.

In some cases, the organization would be using an external application for user interactions which they will like to continue using with the IAM service as well - for reasons such as users being accustomed to the user experience or the lack of resources to create a new experience. In such cases, the existing external application can be made to work with the IAM service with minor modifications.

You also have a variety of choices for hosting these applications. For example, you may host these applications in their dedicated web application cluster, as part of other web application clusters, within the WSO2 Identity Server cluster if it is written in Java, or sometimes even with the service provider application which could be the case if there is only one service provider.

JavaScript Parent/Child Windows or Modals

A redirect based user experience is not the ideal experience users may want to have due to the following reasons:

  • Can be slow and sluggish
  • Applications need to restore a special state when loading after the redirect
  • A redirection-based user interface isn’t portable to all form factors

An enhanced experience to the above two experiences provided by IAM vendors is the parent/child windows [1] or modal form experience [2]. These experiences are mainly provided for the login functionality. With parent/child windows feature in JavaScript, the users’ main window remains in the service provider domain, while the child window is redirected to the IAM domain for login. This is made possible using communication between parent-child windows in HTML5 with postMessage() function, or alternative technology such as modals. Although this is similar to a redirect experience, disruptions to the user experience are minimal.

Preemptive Authentication

Preemptive authentication occurs when the credentials that are required for the authentication are preemptively posted to the identity provider by pairing it with the identity federation request, which bypasses the challenge-response phase in the identity provider. This is also known as “Request Path Authentication” in WSO2 Identity Server.

Some scenarios where you will find preemptive authentication useful are:

  1. Preemptive Authentication with Resident Identity

    In this scenario the end user’s credentials are collected preemptively from the end-user at the service provider end and posted to the identity provider by pairing it with the identity federation request. In a situation where the login application for the resident identities have already been designed as part of the service provider’s landing page, and the organization prefers using the same with the IAM service in order to minimize changes and/or impact on UX, preemptive authentication can help. This scenario is commonly found in organizations where IAM systems are being introduced for the first time and previous service providers have maintained their own login processes. E.g. username/password paired to the SAML2 AuthnRequest.

  2. Preemptive Authentication with Federated Identity
  3. In most IAM requirements we see today there are multiple identity providers that need to coexist and work together [3,4]. Among these is the resident identity provider [3], the resident authorization server [3], and multiple other federated identity providers. The identity broker [3] pattern helps us to simplify these relationships and interactions. Typically we may be able to solve this kind of problem by setting up the most common identity brokering pattern which is the front-channel identity federation between your identity service and the partner’s identity provider.

However, in certain rare scenarios we may encounter one of the following problems which prevent us from using the above pattern:

  • Incompatible identity federation protocols between the identity service and federated identity provider.
  • Uni-directional trust relationship from the identity service to the federated identity provider. In other words, the identity service trusts the federated identity provider but not vice versa. This can be a possibility if the 3 entities - the service provider, the identity service, and the federated identity provider - belong to 3 independent trust domains.

Alternately, in both the scenarios above, if the use case necessitates a service provider initiated identity federation, the service provider can preemptively send the previously issued assertion by the federated identity provider along with the identity federation request; which will then skip sending the identity federation request initiated from the identity service to the federated identity provider and preemptively authenticate the assertion.

In scenario (a) above, if the use case necessitates an identity provider initiated login where the identity federation request is initiated from the federated identity provider, an assertion can be attached to the identity federation request and posted to the identity service’s identity provider initiated login endpoint to preemptively authenticate the assertion and login to the service provider.

Passive Home Realm Discovery

In Passive Home Realm Discovery (HRD) [3] the inputs required from the user to discover the correct home realm are collected at the service provider end. It is then preemptively posted to the identity provider by pairing it with the identity federation request in order to bypass the home realm discovery input function being prompted to the user.

This feature may be useful in situations where the selection of the home realm has been already built into the service provider as part of its landing page. And organizations prefer using the same with the IAM service in order to minimize changes and/or impact on UX. This scenario is commonly found in organizations where IAM systems are being introduced for the first time.

Embedded Experience

An embedded experience occurs where the end-user is served with an interactive widget for IAM functionality from the service provider domain itself, without having to redirect from the service provider domain to another domain.

It is a never ending debate on whether security trumps user experience or vice versa. One of the hottest topics in this debate that has emerged in recent times is the use of embedded authentication flows, specifically in web applications. This has gained even more attention following its recognition as one of the 3 main methods of strong customer authentication (SCA) flows in the revised Payment Services Directive (PSD2). There continues to be a camp of folks who are still determined that embedded authentication experience is an important aspect for first party applications especially given the substantially lower security risk of password phishing attacks.

As with passive home realm discovery, another very common situation we encounter where embedded experiences are applicable is where the UIs for login, self-registration, password recovery, etc. are already built into the service provider as part of its landing page; and organizations may want to continue using the same.

In such a scenario, to support embedded experience, most IAM vendors provide Restful backend APIs for their end-user facing actions, so that the service providers are able to consume these Restful backend APIs and build the corresponding UIs on top of them. Most IAM vendors also provide client-side SDKs for consuming their backend APIs to make this integration easier for the service providers.

For instance, one of the Restful APIs that many OpenID Connect (OIDC) vendors try to standardize is the OAuth2 password grant flow with the “openid” scope which returns an “id_token” in its response. Although it is not explicit in the OIDC specification, OIDC does support all OAuth 2.0 flows since it is an extension of OAuth 2.0. The OIDC specification only talks about the flows that involve browser redirection as they are more common, more secure, and less brittle. Given that the resource owner password grant flow only supports the username/password credential pair, and it is present in the OAuth 2 specification only for the purpose of backward compatibility, you will not see much use of the password grant flow in OIDC( with the exception perhaps for first party applications).

If the service provider is a browser application where the Restful APIs are invoked directly from the browser, then these Restful API requests are cross-origin requests. This means that you need to enable cross-origin resource sharing (CORS) in the IAM service.

CORS is inherently more dangerous. Collecting user credentials in an application served from one origin and then sending them to another origin can present certain security vulnerabilities. Phishing attacks are more likely, as are man-in-the-middle attacks. Redirect experiences are more secure than embedded experiences because they don’t require cross-origin requests. However, if the situation requires it, you may use it with caution.

To minimize the security impact due to CORS you may use custom domains. If you have not used custom domains then you may use third-party cookies to allow secure authentication transactions across different origins. The end user must have a browser that supports third-party cookies. Otherwise, in some browsers, cross-origin authentication will fail. In certain browsers, this can be unreliable if you do not set up a Custom Domain and host your app on the same domain.

Embedded approaches are being discontinued by many well known cloud service providers. For example, Google no longer supports an embedded approach when implementing OAuth [5].

Native applications may provide an embedded experience via the standard OAuth 2.0 token endpoint. This, however, doesn’t use cross-origin authentication.

Another way of providing an embedded experience with OIDC redirect flows such as authorization_code, implicit and hybrid, is by the Ajax client simulating the HTTP behavior of a browser by following 302 redirects and dynamically loading the IAM vendors login application within the document object model (DOM) of the service provider application. This way the client application would be able to extract the authorization code and then exchange it for an access token. JavaScript has many methods to dynamically change the DOM. What I've explained here is just one simple approach. For a detailed explanation of the various methods take a look at [6].


This article discusses various user experiences for IAM on the web that are typically provided by IAM vendors. I used relevant examples from WSO2 Identity Server to illustrate certain scenarios. Learn more about WSO2 Identity Server here.


[1] https://usefulangle.com/post/4/javascript-communication-parent-child-window

[2] https://www.w3schools.com/howto/howto_css_login_form.asp


[4] https://wso2.com/library/articles/2018/02/api-security-for-distributed-authorization-realms/

[5] https://auth0.com/blog/google-blocks-oauth-requests-from-embedded-browsers/

[6] https://thoughtbot.com/blog/rendering-views-in-javascript


About Author

  • Johann Nallathamby
  • Director - Solutions Architecture
  • WSO2