Sso

Single sign on

Single Sign-On(SSO) enables a user to enter their credentials once to sign in and establish a session which can be reused across multiple applications without requiring to authenticate again. This provides a seamless experience to the user and reduces the repeated prompts for credentials.

Azure AD provides SSO capabilities to applications by setting a session cookie in the browser when the user authenticates the first time. The ADAL.js library allows applications to leverage this in a few ways.

SSO for an app between browser tabs

When your application is open in multiple tabs and you first sign in the user on one tab, the user is also signed in on the other tabs without being prompted. ADAL.js caches the ID token for the user in the browser localStorage and will sign the user into the application on the other open tabs.

By default, ADAL.js uses sessionStorage which does not allow the session to be shared between tabs. In order to get SSO between tabs, make sure to set the cacheLocation in ADAL.js to localStorage as shown below.

window.config = {
    clientId: '[Enter your client_id here, e.g. g075edef-0efa-453b-997b-de1337c29185]',
    cacheLocation: 'localStorage'
};

var authContext = new AuthenticationContext(config);

SSO between apps

Azure AD sets the session cookie in the browser for a user when they authenticate. ADAL.js relies on this session cookie to provide SSO for the user between different applications. ADAL.js also caches the id_tokens and access_tokens of the user in the browser storage for each application domain. As a result, the SSO behavior varies for different cases:

Applications on the same domain

When applications are hosted on the same domain, the user can sign into an app once and then get authenticated to the other apps without a prompt. ADAL.js leverages the tokens cached for the user on the domain to provide SSO.

Applications on different domain

When applications are hosted on different domains, the tokens cached on domain A cannot be accessed by ADAL.js in domain B.

This means that when users signed in on domain A navigate to an application on domain B, they will be redirected to the AAD page. Since Azure AD still has the user session cookie, the user will not have to re-enter the credentials. If the same user has multiple user accounts in session with Azure AD, the user will have a chance to pick the relevant account to login with.

Automatically select account on Azure AD

In certain cases, the application has access to the user's context and wants to avoid the AAD account selection prompt. This can be done a few different ways:

Using Session ID (SID)

Session ID is an optional claim that can be configured for the ID tokens. This claim allows the application to identify the user’s Azure AD session independent of the user’s account name or username. You can pass the SID as extraQueryParameters in the ADAL.js config. This will allow Azure AD to bypass the account selection. SID is bound to the session cookie and will not cross browser contexts.

Note: SID can be used only with silent authentication requests i.e acquireToken call in ADAL.js. You can find the steps to configure optional claims in your application manifest here.

Using Login Hint

If you do not have SID claim configured or need to bypass the account selection prompt on interactive auth calls, you can do so by providing a login_hint and optionally a domain_hint as extraQueryParameters in the ADAL.js config or interactive methods (acquireTokenPopup and acquireTokenRedirect). For example:

authContext.acquireTokenRedirect(resourceId, "&login_hint=<upn>");

You can get the values for login_hint and domain_hint by reading the claims returned in the ID token for the user.

• login_hint should be set to the upn claim in the ID token.

• domain_hint The value of the domain_hint is a registered domain for the tenant.

Note that you cannot pass SID and login_hint at the same time.

SSO to an app without ADAL.js login

By design, ADAL.js requires that the login method is called to establish a user context before getting tokens for APIs.

There are certain cases in which applications have access to the authenticated user's context through another application and want to leverage SSO to acquire tokens without first logging in through ADAL.js.

An example is: A user is signed into a web application which hosts another JS application running as an add-in or plugin.

With ADAL.js 1.0.16, The SSO experience in this scenario can be achieved as follows:

Set the sid if available (or login_hint and optionally domain_hint) as extraQueryParameters in the ADAL.js config and then call acquireToken method directly.

window.config = {
    clientId: '[Enter your client_id here, e.g. g075edef-0efa-453b-997b-de1337c29185]',
    cacheLocation: 'localStorage',
    extraQueryParameters: 'login_hint=<upn>'
};

var authContext = new AuthenticationContext(config);
authContext.acquireToken(resourceId);