Azure AD B2C: Requesting access tokens

An access token (denoted as access_token in the responses from Azure AD B2C) is a form of security token that a client can use to access resources that are secured by an authorization server, such as a web API. Access tokens are represented as JWTs and contain information about the intended resource server and the granted permissions to the server. When calling the resource server, the access token must be present in the HTTP request.

This article discusses how to configure a client application and web API in order to obtain an access_token.

Note

Web API chains (On-Behalf-Of) is not supported by Azure AD B2C.

Many architectures include a web API that needs to call another downstream web API, both secured by Azure AD B2C. This scenario is common in native clients that have a web API back end, which in turn calls a Microsoft online service such as the Azure AD Graph API.

This chained web API scenario can be supported by using the OAuth 2.0 JWT Bearer Credential grant, otherwise known as the On-Behalf-Of flow. However, the On-Behalf-Of flow is not currently implemented in Azure AD B2C.

Register a web API and publish permissions

Before requesting an access token, you first need to register a web API and publish permissions (scopes) that can be granted to the client application.

Register a web API

  1. On the Azure AD B2C features menu on the Azure portal, click Applications.
  2. Click +Add at the top of the menu.
  3. Enter a Name for the application that will describe your application to consumers. For example, you could enter "Contoso API".
  4. Toggle the Include web app / web API switch to Yes.
  5. Enter an arbitrary value for the Reply URLs. For example, enter https://localhost:44316/. The value does not matter since an API should not be receiving the token directly from Azure AD B2C.
  6. Enter an App ID URI. This is the identifier used for your web API. For example, enter 'notes' in the box. The App ID URI would then be https://{tenantName}.onmicrosoft.com/notes.
  7. Click Create to register your application.
  8. Click the application that you just created and copy down the globally unique Application Client ID that you'll use later in your code.

Publishing permissions

Scopes, which are analogous to permissions, are necessary when your app is calling an API. Some examples of scopes are "read" or "write". Suppose you want your web or native app to "read" from an API. Your app would call Azure AD B2C and request an access token that gives access to the scope "read". In order for Azure AD B2C to emit such an access token, the app needs to be granted permission to "read" from the specific API. To do this, your API first needs to publish the "read" scope.

  1. Within the Azure AD B2C Applications menu, open the web API application ("Contoso API").
  2. Click on Published scopes. This is where you define the permissions (scopes) that can be granted to other applications.
  3. Add Scope Values as necessary (for example, "read"). By default, the "user_impersonation" scope will be defined. You can ignore this if you wish. Enter a description of the scope in the Scope Name column.
  4. Click Save.
Important

The Scope Name is the description of the Scope Value. When using the scope, make sure to use the Scope Value.

Grant a native or web app permissions to a web API

Once an API is configured to publish scopes, the client application needs to be granted those scopes via the Azure portal.

  1. Navigate to the Applications menu in the Azure AD B2C features menu.
  2. Register a client application (web app or native client) if you don’t have one already. If you are following this guide as your starting point, you'll need to register a client application.
  3. Click on API access.
  4. Click on Add.
  5. Select your web API and the scopes (permissions) you would like to grant.
  6. Click OK.
Note

Azure AD B2C does not ask your client application users for their consent. Instead, all consent is provided by the admin, based on the permissions configured between the applications described above. If a permission grant for an application is revoked, all users who were previously able to acquire that permission will no longer be able to do so.

Requesting a token

When requesting an access token, the client application needs to specify the desired permissions in the scope parameter of the request. For example, to specify the Scope Value “read” for the API that has the App ID URI of https://contoso.onmicrosoft.com/notes, the scope would be https://contoso.onmicrosoft.com/notes/read. Below is an example of an authorization code request to the /authorize endpoint.

Note

Currently, custom domains are not supported along with access tokens. You must use your tenantName.onmicrosoft.com domain in the request URL.

https://login.microsoftonline.com/<tenantName>.onmicrosoft.com/oauth2/v2.0/authorize?p=<yourPolicyId>&client_id=<appID_of_your_client_application>&nonce=anyRandomValue&redirect_uri=<redirect_uri_of_your_client_application>&scope=https%3A%2F%2Fcontoso.onmicrosoft.com%2Fnotes%2Fread&response_type=code 

To acquire multiple permissions in the same request, you can add multiple entries in the single scope parameter, separated by spaces. For example:

URL decoded:

scope=https://contoso.onmicrosoft.com/notes/read openid offline_access

URL encoded:

scope=https%3A%2F%2Fcontoso.onmicrosoft.com%2Fnotes%2Fread%20openid%20offline_access

You may request more scopes (permissions) for a resource than what is granted for your client application. When this is the case, the call will succeed if at least one permission is granted. The resulting access_token will have its “scp” claim populated with only the permissions that were successfully granted.

Note

We do not support requesting permissions against two different web resources in the same request. This kind of request will fail.

Special cases

The OpenID Connect standard specifies several special “scope” values. The following special scopes represent the permission to “access the user’s profile”:

  • openid: This requests an ID token
  • offline_access: This requests a refresh token (using Auth Code flows).

If the response_type parameter in a /authorize request includes token, the scope parameter must include at least one resource scope (other than openid and offline_access) that will be granted. Otherwise, the /authorize request will terminate with a failure.

The returned token

In a successfully minted access_token (from either the /authorize or /token endpoint), the following claims will be present:

Name Claim Description
Audience aud The application ID of the single resource that the token grants access to.
Scope scp The permissions granted to the resource. Multiple granted permissions will be separated by space.
Authorized Party azp The application ID of the client application that initiated the request.

When your API receives the access_token, it must validate the token to prove that the token is authentic and has the correct claims.

We are always open to feedback and suggestions! If you have any difficulties with this topic, please post on Stack Overflow using the tag 'azure-ad-b2c'. For feature requests, add them to UserVoice.

Next steps