Acquire tokens

ADAL JS allows applications to get tokens on behalf of users for making authenticated calls to web APIs. The pattern followed in ADAL is to use the authenticated user context to attempt getting tokens silently without prompting user and raise events in case of failures to be handled as appropriate. The methods provided for this are described below:

AcquireToken

When an authenticated user session exists with Azure AD, this method allows the application to obtain tokens silently without prompting the user again. ADAL JS uses a hidden Iframe to make the token request to Azure AD.

authContext.acquireToken(resource, callback)

• resource - The App ID or URI of the resource API for which to get token. The OAuth 2.0 implicit flow in Azure AD is designed to return an ID token when the resource for which the token is being requested is the same as the client application. In other words, when the JS client uses ADAL JS to request a token for its own backend web API registered with same App ID as the client, an ID token is returned and cached by the library. Note that in this case the resource should be set to the App ID of the client (App ID URI will not work). This ID token can then be used as a bearer token in the calls to your application's backend API.

• callback - The user defined function to handle the token response or use the returned token. It will be called with token or error.

If the silent token request fails for some reason such as invalid session, an interactive token request needs to be made. For this, ADAL JS provides the following methods:

AcquiretokenRedirect

This method allows you to acquire tokens for the resource by prompting user authentication with a full page redirect to Azure AD.

authContext.acquireTokenRedirect(resource, extraQueryParameters, claims);

• resource - The App ID or URI of the resource API for which to get token. The OAuth 2.0 implicit flow in Azure AD is designed to return an ID token when the resource for which the token is being requested is the same as the client application. In other words, when the JS client uses ADAL JS to request a token for its own backend web API registered with same App ID as the client, an ID token is returned and cached by the library. Note that in this case the resource should be set to the App ID of the client (App ID URI will not work). This ID token can then be used as a bearer token in the calls to your application's backend API.

• extraQueryParameter - This config allows you to pass additional query string parameters in the authorization requests to Azure AD. For example, you can pass a login hint to Azure AD to use an select a specific user session as {extraQueryParameter: 'login_hint=<upn>'}.

• claims - In cases where the silent token request fails due to a Conditional Access claims challenge, the interactive request requires the claims to be passed to Azure AD so that the user can be prompted appropriately to comply with the CA policy. See this sample for how to handle CA policy.

To process requests made by acquireTokenRedirect, invoke authContext.handleWindowCallback() on the page used for the redirect URI.

AcquireTokenPopup

This method allows you to acquire tokens for the resource by prompting user authentication in a pop-up window.

authContext.acquireTokenPopup(resource, extraQueryParameters, claims, callback);

• resource - The App ID or URI of the resource API for which to get token. The OAuth 2.0 implicit flow in Azure AD is designed to return an ID token when the resource for which the token is being requested is the same as the client application. In other words, when the JS client uses ADAL JS to request a token for its own backend web API registered with same App ID as the client, an ID token is returned and cached by the library. Note that in this case the resource should be set to the App ID of the client (App ID URI will not work). This ID token can then be used as a bearer token in the calls to your application's backend API.

• extraQueryParameter - This config allows you to pass additional query string parameters in the authorization requests to Azure AD. For example, you can pass a login hint to Azure AD to use an select a specific user session as {extraQueryParameter: 'login_hint=<upn>'}.

• claims - In cases where the silent token request fails due to a Conditional Access claims challenge, the interactive request requires the claims to be passed to Azure AD so that the user can be prompted appropriately to comply with the CA policy. See this sample for how to handle CA policy.

• callback - The user defined function to handle the token response or use the returned token. It will be called with token or error.

Using the token to call API

The token acquired for a web service can be used as a bearer token to make authorized API calls as follows:

authContext.acquireToken(resource, function (error, token) {

            // Handle ADAL Error
            if (error || !token) {
                printErrorMessage('ADAL Error Occurred: ' + error);
                return;
            }

            // Get TodoList Data
            $.ajax({
                type: "GET",
                url: "/api/TodoList",
                headers: {
                    'Authorization': 'Bearer ' + token,
                },
            });

Token renewal

ADAL JS uses the OAuth 2.0 implicit flow which does not return refresh tokens for security reasons(refresh tokens have longer lifetime than access tokens and are therefore more dangerous in the hands of malicious actors). Hence, ADAL JS performs token renewal using the hidden Iframe approach mentioned above so that the user is not repeatedly prompted to authenticate.