Azure Active Directory v2.0 tokens reference

From: https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-v2-tokens

Claims in ID tokens

Access tokens

The v2.0 endpoint allows third party apps that are registered with Azure AD to issue access tokens for secured resources such as Web APIs. For more information about setting up an application to issue access tokens, please see How to register an app with the v2.0 endpoint. Upon registering the application with the v2.0 endpoint, the developer can specify levels of access, called scopes, for which access tokens may be issued. For example, the calendars.read scope defined in the Microsoft Graph API grants permission to read the user’s calendar. When your application receives an access token from the v2.0 endpoint, you must validate the token’s signature, issuer, audience, expiration time and any other claims depending on your scenario.

When you request an access token from the v2.0 endpoint, the v2.0 endpoint also returns metadata about the access token for your app to use. This information includes the expiry time of the access token and the scopes for which it is valid. Your app uses this metadata to perform intelligent caching of access tokens without having to parse open the access token itself.

Refresh tokens

Refresh tokens are security tokens that your app can use to get new access tokens in an OAuth 2.0 flow. Your app can use refresh tokens to achieve long-term access to resources on behalf of a user without requiring interaction with the user.

Refresh tokens are multi-resource. A refresh token received during a token request for one resource can be redeemed for access tokens to a completely different resource.

To receive a refresh in a token response, your app must request and be granted the offline_access scope. To learn more about the offline_access scope, see the consent and scopes article.

Refresh tokens are, and always will be, completely opaque to your app. They are issued by the Azure AD v2.0 endpoint and can only be inspected and interpreted by the v2.0 endpoint. They are long-lived, but your app should not be written to expect that a refresh token will last for any period of time. Refresh tokens can be invalidated at any moment for various reasons – for details, see token revocation. The only way for your app to know if a refresh token is valid is to attempt to redeem it by making a token request to the v2.0 endpoint.

When you redeem a refresh token for a new access token (and if your app had been granted the offline_access scope), you receive a new refresh token in the token response. Save the newly issued refresh token, to replace the one you used in the request. This guarantees that your refresh tokens remain valid for as long as possible.

Validating tokens

Currently, the only token validation your apps should need to perform is validating ID tokens. To validate an ID token, your app should validate both the ID token’s signature and the claims in the ID token.

Microsoft provides libraries and code samples that show you how to easily handle token validation. In the next sections, we describe the underlying process. Several third-party open-source libraries also are available for JWT validation. There’s at least one library option for almost every platform and language.

Validate the signature

A JWT contains three segments, which are separated by the . character. The first segment is known as the header, the second segment is the body, and the third segment is the signature. The signature segment can be used to validate the authenticity of the ID token so that it can be trusted by your app.

ID tokens are signed by using industry-standard asymmetric encryption algorithms, such as RSA 256. The header of the ID token has information about the key and encryption method used to sign the token. For example:

{
  "typ": "JWT",
  "alg": "RS256",
  "kid": "MnC_VZcATfM5pOYiJHMba9goEKY"
}

The alg claim indicates the algorithm that was used to sign the token. The kid claim indicates the public key that was used to sign the token.

At any time, the v2.0 endpoint might sign an ID token by using any one of a specific set of public-private key pairs. The v2.0 endpoint periodically rotates the possible set of keys, so your app should be written to handle those key changes automatically. A reasonable frequency to check for updates to the public keys used by the v2.0 endpoint is every 24 hours.

You can acquire the signing key data that you need to validate the signature by using the OpenID Connect metadata document located at:

https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration

This metadata document is a JSON object that has several useful pieces of information, such as the location of the various endpoints required for OpenID Connect authentication. The document also includes a jwks_uri, which gives the location of the set of public keys used to sign tokens. The JSON document located at the jwks_uri has all the public key information that is currently in use. Your app can use the kid claim in the JWT header to select which public key in this document has been used to sign a token. It then performs signature validation by using the correct public key and the indicated algorithm.

Performing signature validation is outside the scope of this document. Many open-source libraries are available to help you with this.

Validate the claims

When your app receives an ID token upon user sign-in, it should also perform a few checks against the claims in the ID token. These include but are not limited to:

• audience claim, to verify that the ID token was intended to be given to your app
• not before and expiration time claims, to verify that the ID token has not expired
• issuer claim, to verify that the token was issued to your app by the v2.0 endpoint
• nonce, as a token replay attack mitigation

For a full list of claim validations that your app should perform, see the OpenID Connect specification.

Details of the expected values for these claims are included in the ID tokens section.

Token lifetimes

We provide the following token lifetimes for your information only. The information might help you as you develop and debug apps. Your apps should not be written to expect any of these lifetimes to remain constant. Token lifetimes can and will change at any time.