Azure/Office 365 Graph API developer: RefreshToken, AccessToken, IdentityToken

  • Article

These are 3 common terms (Refresh Token, Access Token, Identity Token) in Azure/Office 365 Graph API Cloud developer world and we get tons of queries on this. So let me try to explain them in simple terms …

Access Token:
- The access token is attached to every REST API request in the authorization header.
- It grants your application access to the REST API according to the scope claim in the token.
- It is relatively short lived (for example, 1 hour) and your application needs to use the refresh token to acquire new access tokens periodically.

For example, it would be like this:

Le Café Central de DeVa - Deva Blogs

Identity Token:

- The identity token authenticates the user to your application.
- It is only present if you include the "openid" scope in your authorization and token requests.
- Please note that if you want to have additional details on the user for display, you should use the Azure AD Graph APIs to query for those rather than using any claims in the identity token.
- For example,

Le Café Central de DeVa - Deva Blogs

Refresh Token:

- The refresh token is used in your application to request additional access tokens after the initial token request using the authorization code.
- It is only present if you include the "offline_access" scope in your authorization and token requests.
- You are responsible to securely cache this refresh token as part of building the application.
- Client libraries such as Azure Active Directory Authentication Library (ADAL) provide functionality that help your application to securely maintain refresh tokens.
- Refresh tokens are long-lived, and can be used to retain access to resources for extended periods of time.
- However, in some cases, refresh tokens expire, are revoked, or lack sufficient privileges for the desired action. Your application needs to expect and handle errors returned by the token issuance endpoint correctly.

Related documentation:
- For more information about JSON web tokens, see the JWT IETF draft specification.
- For token types and claims, read Supported Token and Claim Types
- For Authorize access to Azure Active Directory web applications using the OAuth 2.0 code grant flow, read https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-protocols-oauth-code 

Hope this helps.