Acquire tokens

Acquiring a token depending on the type of application

There are many ways of acquiring a token. Some require user interactions while others don't. In general the way to acquire a token is different based on if the application is a public client application (Desktop / Mobile) or a confidential client application (Web App, Web API, daemon application).

Public client applications:

• Acquire tokens by authorization code after letting the user sign-in through the authorization request URL.
• It's also possible (but not recommended) to get a token with a username and password
• Finally, for applications running on devices which don't have a web browser, it's possible to acquire a token through the device code mechanism, which provides the user with a URL and a code. The user goes to a web browser on another device, enters the code and signs-in, and then Azure AD returns back a token to the browser-less device.

Confidential client applications:

• Acquire token as the application itself using client credentials, and not for a user. For example, in apps which process users in batches and not a particular user such as in synching tools.
• In the case of Web Apps or Web APIs calling another downstream Web API in the name of the user, use the On Behalf Of flow to acquire a token based on some User assertion (SAML for instance, or a JWT token).
• For Web apps in the name of a user, acquire tokens by authorization code after letting the user sign-in through the authorization request URL. This is typically the mechanism used by an application which lets the user sign-in using Open ID Connect, but then wants to access Web APIs for this particular user.

ADAL4J APIs for corresponding flows

Public Client flows:

Authorization Code Flow

Returns	Method
Future<AuthenticationResult>	acquireTokenByAuthorizationCode(String authorizationCode, String resource, String clientId, URI redirectUri, AuthenticationCallback callback)

Note: Your app will need to obtain an authorizationCode to be passed into the above method by making the request to the AAD service.

Device Code flow

Returns	Method
Future<DeviceCode>	acquireDeviceCode(String clientId, String resource, AuthenticationCallback<DeviceCode> callback)
Future<AuthenticationResult>	acquireTokenByDeviceCode(DeviceCode deviceCode, AuthenticationCallback callback)

UserName Password flow

Returns	Method
Future<AuthenticationResult>	acquireToken(String resource, String clientId, String username, String password, AuthenticationCallback callback)

Windows Integrated Auth flow

You can perform the Windows Integrated Auth flow by using the above acquireToken method with password set to NULL as follows: acquireToken(resource, clientId, username, null, callback)

Make sure to run the Kinit tool to set up the TGT cache before running the Windows Integrated Auth flow.

Confidential Client flows:

Authorization Code Flow

Returns	Method
Future<AuthenticationResult>	acquireTokenByAuthorizationCode(String authorizationCode, URI redirectUri, AsymmetricKeyCredential credential, AuthenticationCallback callback)
Future<AuthenticationResult>	acquireTokenByAuthorizationCode(String authorizationCode, URI redirectUri, AsymmetricKeyCredential credential, String resource, AuthenticationCallback callback)
Future<AuthenticationResult>	acquireTokenByAuthorizationCode(String authorizationCode, URI redirectUri, ClientAssertion clientAssertion, AuthenticationCallback callback)
Future<AuthenticationResult>	acquireTokenByAuthorizationCode(String authorizationCode, URI redirectUri, ClientAssertion clientAssertion, String resource, AuthenticationCallback callback)
Future<AuthenticationResult>	acquireTokenByAuthorizationCode(String authorizationCode, URI redirectUri, ClientCredential credential, AuthenticationCallback callback)
Future<AuthenticationResult>	acquireTokenByAuthorizationCode(String authorizationCode, URI redirectUri, ClientCredential credential, String resource, AuthenticationCallback callback)

Note: Your app will need to obtain an authorizationCode to be passed into the above method by making the request to the AAD service. Here is a sample showing this flow: https://github.com/Azure-Samples/active-directory-java-webapp-openidconnect.

Client Credential flow

Returns	Method
Future<AuthenticationResult>	acquireToken(String resource, AsymmetricKeyCredential credential, AuthenticationCallback callback)
Future<AuthenticationResult>	acquireToken(String resource, ClientAssertion clientAssertion, AuthenticationCallback callback)
Future<AuthenticationResult>	acquireToken(String resource, ClientCredential credential, AuthenticationCallback callback)

On-Behalf-Of flow

Returns	Method
Future<AuthenticationResult>	acquireToken(String resource, UserAssertion userAssertion, ClientCredential credential, AuthenticationCallback callback)

Token Renewal

Acquire Token using Refresh Tokens

For confidential clients:

Returns	Method
Future<AuthenticationResult>	acquireTokenByRefreshToken(String refreshToken, AsymmetricKeyCredential credential, AuthenticationCallback callback)
Future<AuthenticationResult>	acquireTokenByRefreshToken(String refreshToken, AsymmetricKeyCredential credential, String resource,AuthenticationCallback callback)
Future<AuthenticationResult>	acquireTokenByRefreshToken(String refreshToken, ClientCredential credential, AuthenticationCallback callback)
Future<AuthenticationResult>	acquireTokenByRefreshToken(String refreshToken, ClientCredential credential, String resource, AuthenticationCallback callback)
Future<AuthenticationResult>	acquireTokenByRefreshToken(String refreshToken, String clientId, ClientAssertion clientAssertion, AuthenticationCallback callback)
Future<AuthenticationResult>	acquireTokenByRefreshToken(String refreshToken, String clientId, ClientAssertion clientAssertion, String resource, AuthenticationCallback callback)

For public clients:

Returns	Method
Future<AuthenticationResult>	acquireTokenByRefreshToken(String refreshToken, String clientId, String resource, AuthenticationCallback callback)
Future<AuthenticationResult>	acquireTokenByRefreshToken(String refreshToken, String clientId, AuthenticationCallback callback)

ADAL4J acquireToken parameters

The acquire token methods for the different flows might require any of the following parameters:

• The resource for which you want an access token. Here you can pass either the Resource URI of a Web API, or the clientId of the target Web API. Both work, but it's important to realize that the token will contain the resource as requested (audience), and therefore the form to use is the one accepted by the Web API.

• The clientId parameter is the clientId/applicationId of the application requesting tokens.

• The redirectUri is the redirect URI of the client application. This is the address to return to upon receiving a response with the token from Azure AD.

• The authorizationCode returned after user sign-in from the authorization code endpoint of Azure AD. This is part of the first step in any of the authorization code flows.

• The refreshToken is the token used to refresh the AAD session and exchange for a renewed access token.

• The userAssertion is a JWT assertion representing the user's identity in the absence of user interaction used to acquire token for a downstream API, when doing the On-Behalf-of flow.

• ​The DeviceCode

• The asymmetricKeyCredential

• The clientAssertion