Azure AD Tokens and Claims

First let’s take a look at how tokens work in Azure AD.

  • A client wants to call a service with validation taking place via Azure AD.
  • The server redirects me to Azure AD.
  • Here I log in with my username and password.
  • Azure AD returns an access token(AT1) and a refresh token(RT) to the client
  • The access token is short-lived, ie valid for let’s say one hour. The refresh token is valid for 30 days with a sliding window with a maximum of 90 days. The refresh token is valid as long as the underlying password hasn’t been changed en the user hasn’t been logged out on all devices (session ended).
  • The refresh token is automatically sent behing the scenes from the client to Azure AD to get a new access token and a new refresh token.
  • The client sends the access token to the service for authentication.
  • Now, let’s say you want to call another service from the same client.
  • The client sends a refresh token to Azure AD indicating that he wants to call another service.
  • Azure AD sends another access token(AT2) and an updated refresh token(RT) to the client.
  • The client sends the access token to the service for authentication.

Take Away: You only get prompted once for username and password. After that, you simply use access tokens and refresh tokens.

Now let’s look at claims. Apps are often said to be claims-aware or claims-based. Claims are key/value pairs attached to the user. For instance the user Bob could have a claim with the name “email” and the value “”.

On-prem line of business apps typically don’t use claims. They simply access AD for authentication. Whenever extra information is needed, for instance to authorize the user, a direct query is made against Active Directory using LDAP. But what if you don’t have access to Active Directory? Let’s say you’re in a cloud scenario. In that case you might receive a token upon signing in. The token in turn contains a set of claims.

Claims are used to decouple identity providers. Let’s say you use Facebook as a federated identity provider. Facebook doesn’t want to allow you access into their database. Instead they return a token with claims. Claims are a subset of the entire Facebook profile. There are two additional concerns with claims:

  • There’s no standard for the claims identity providers return as part of a token. Facebook might be ok with returning claims that Google do not provide, and vice versa. This means that if you are implementing an app you should always check to see that you get the info you need from the identity providers you support.
  • Identity providers may not want to share all user information with a certain third party. This is why most identity providers usually present a consent screen indicating the type of information shared.

In browser-based applications there is a limit to how much data you can store in a token. Don’t store anything you need to know about a user in the token, but restrict yourself to key pieces of info needed directly in the app or for lookups. In turn, claims can be transformed or augmented/enriched.
For coding examples on how to access, transform and enrich claims, see: aadguide .