In this post, we’ll explore the differences between the different types of security tokens that are provided by the Microsoft Identity Platform. We will compare access tokens and ID tokens, showing how and where you should use them in your application. We will highlight why access tokens should be treated as opaque by client applications and outline best practices around access token usage, helping you avoid common pitfalls.

Starting October 2024, we have been gradually enabling encrypted access tokens for more Microsoft-owned APIs. Consequently, the format of access tokens for these APIs is changing. It’s important for you to ensure your applications are following best practices when handling tokens in client applications.

What is an Access Token

Access tokens are a type of security token designed for authorization, granting access to specific resources on behalf of an authenticated user. Think of them as keys that unlock certain parts of an application or system. Access tokens contain information about the user as well as individual pieces of data, called claims, which define what the user is authorized to do.

Access tokens enable clients to securely access protected web APIs. Although client applications will receive access tokens, they should be treated as opaque strings—meaning they should not be inspected or parsed. Client applications should not attempt to validate access tokens. The only use of the access token within a client application is to pass it to the relevant resource server, which will then validate it before accepting it as proof of authorization, i.e. the contents of access tokens are intended only for the API.

What is an ID Token

ID tokens differ from access tokens in that they serve as proof of authentication, confirming that a user is successfully authenticated. Like name tags at a conference, ID tokens enable a client to verify that a user is who they claim to be. When a user successfully authenticates, the authorization server issues an ID token that contains claims that carry information about the user. ID tokens can be sent alongside or instead of an access token and are always in JWT (JSON Web Token) format. They should be used by the client application to authenticate the user and never used for authorization purposes. The claims provided by ID tokens can be used for UX inside your application, as keys in a database, displaying user profile information, and for providing access to client applications, etc.

Best practice for handling access tokens

As mentioned above, access tokens should be treated as opaque strings by client applications, meaning that they should not attempt to read, inspect, or parse them. Only web APIs should parse access tokens (since they are the ones defining the format and setting the encryption keys).

Note: This is important because access tokens can change format without notice, potentially breaking any client-side code that relies on this token structure.

An Example: Access token encryption

Many Microsoft-owned APIs are configured to receive encrypted access tokens today. Starting October 2024, we have been gradually enabling encrypted access tokens for more Microsoft-owned APIs. Consequently, the format of access tokens for these APIs is changing. If you have been relying on the value of a claim in an access token, that will stop working. You should always use the ID token if client applications need to learn something about the user.

Another example of a change to access token format, that could break your application if you incorrectly rely on them, is changes to how the value of a claim is represented, e.g. changing the ‘aud’ claim to use a GUID instead of the URI.

If your client application currently parses access tokens, it is important to review and update your code. Not treating them as opaque strings is not aligned with our current best practices, which have been documented on the Microsoft identity platform documentation portal. 

What you should do next

If your application follows best practices and treats access tokens as opaque strings, no action is required.

However, if your client application currently parses access tokens issued for Microsoft-owned Web APIs, it may break when these Web APIs start receiving encrypted access tokens. Review your application’s code to ensure it does not parse access tokens meant for Web APIs and continues to function smoothly after the changes take effect.

For simplicity, just remember to use the ID token if client applications need to learn something about the user.

Stay connected and informed

For more detailed guidance, visit our documentation on best practices. Stay informed and ensure your client applications remain secure and scalable as these important changes roll out.

To learn more or test out features in the Microsoft Entra portfolio, visit our developer center. Make sure you subscribe to the Identity developer blog for more insights and to keep up with the latest on all things Identity. And, follow us on YouTube for video overviews, tutorials, and deep dives.