Security tokens

A centralized identity provider is especially useful for apps that have users located around the globe that don't necessarily sign in from the enterprise's network. Microsoft identity platform authenticates users and provides security tokens, such as access token, refresh token, and ID token, that allow a client application to access protected resources on a resource server.

An access token is a security token that is issued by an authorization server as part of an OAuth 2.0 flow. It contains information about the user and the app for which the token is intended; which can be used to access web APIs and other protected resources. To learn more about how Microsoft identity platform issues access tokens, see Access tokens.

Access tokens are only valid for a short period of time, so authorization servers will sometimes issue a refresh token at the same time the access token is issued. The client application can then exchange this refresh token for a new access token when needed. To learn more about how Microsoft identity platform uses refresh tokens to revoke permissions, see Token revocation.

ID tokens are sent to the client application as part of an OpenID Connect flow. They can be sent along side or instead of an access token, and are used by the client to authenticate the user. To learn more about how Microsoft identity platform issues ID tokens, see ID tokens.

Note

This article discusses security tokens used by the OAuth2 and OpenID Connect protocols. Many enterprise applications use SAML to authenticate users. See Azure AD SAML token reference for information on SAML assertions.

Validating security tokens

It's up to the app for which the token was generated, the web app that signed-in the user, or the web API being called, to validate the token. The token is signed by the Security Token Server (STS) with a private key. The STS publishes the corresponding public key. To validate a token, the app verifies the signature by using the STS public key to validate that the signature was created using the private key.

Tokens are only valid for a limited amount of time. Usually the STS provides a pair of tokens:

  • An access token to access the application or protected resource, and
  • A refresh token used to refresh the access token when the access token is close to expiring.

Access tokens are passed to a web API as the bearer token in the Authorization header. An app can provide a refresh token to the STS, and if the user access to the app wasn't revoked, it will get back a new access token and a new refresh token. This is how the scenario of someone leaving the enterprise is handled. When the STS receives the refresh token, it won't issue another valid access token if the user is no longer authorized.

JSON Web Tokens (JWTs) and claims

Microsoft identity platform implements security tokens as JSON Web Tokens (JWTs) that contain claims. Since JWTs are used as security tokens, this form of authentication is sometimes called JWT authentication.

A claim provides assertions about one entity, such as a client application or resource owner, to another entity, such as a resource server. A claim may also be referred to as a JWT claim or JSON Web Token claim.

Claims are name/value pairs that relay facts about the token subject. For example, a claim may contain facts about the security principal that was authenticated by the authorization server. The claims present in a given token depend on many things, including the type of token, the type of credential used to authenticate the subject, the application configuration, and so on.

Applications can use claims for various tasks such as:

  • Validating the token
  • Identifying the token subject's tenant
  • Displaying user information
  • Determining the subject's authorization

A claim consists of key-value pairs that provide information such as the:

  • Security Token Server that generated the token
  • Date when the token was generated
  • Subject (such as the user--except for daemons)
  • Audience, which is the app for which the token was generated
  • App (the client) that asked for the token. In the case of web apps, this may be the same as the audience

To learn more about how Microsoft identity platform implements tokens and claim information, see access tokens and ID tokens.

How each flow emits tokens and codes

Depending on how your client is built, it can use one (or several) of the authentication flows supported by Microsoft identity platform. These flows can produce a variety of tokens (ID tokens, refresh tokens, access tokens) as well as authorization codes, and require different tokens to make them work. This chart provides an overview:

Flow Requires ID token access token refresh token authorization code
Authorization code flow x x x x
Implicit flow x x
Hybrid OIDC flow x x
Refresh token redemption refresh token x x x
On-behalf-of flow access token x x x
Client credentials x (app-only)

Tokens issued via the implicit mode have a length limitation due to being passed back to the browser via the URL (where response_mode is query or fragment). Some browsers have a limit on the size of the URL that can be put in the browser bar and fail when it is too long. Thus, these tokens do not have groups or wids claims.

Next steps

For other topics covering authentication and authorization basics:

  • See Authentication vs. authorization to learn about the basic concepts of authentication and authorization in Microsoft identity platform.
  • See Application model to learn about the process of registering your application so it can integrate with Microsoft identity platform.
  • See App sign-in flow to learn about the sign-in flow of web, desktop, and mobile apps in Microsoft identity platform.