I happened to spend a decent part of 2021 skimming through Microsoft documentation along with OAuth and associated RFCs to understand the specifics of authorization flows to secure APIs. On one such quest, I was to figure out a good way to identify a unique user from a JWT token passed on by Microsoft Identity Plaftform. Now to be clear, the problem wasn’t lack of a way to do so; rather multiple ways. Some outright wrong, some more right than others depending on what you really want to achieve. So let’s take a look. There’s a TL;DR right below.

Some basics

The title already tells you that there are two claims in a JWT token that we are most interested in. For those who haven’t had their essential visit to the Microsoft Access Token or ID Token documentation - UPN, Email or Phone numbers aren’t guaranteed to be unique system wide. UPN (User Principal Name) especially misleads devs into assuming uniqueness.

The only two eligible candidates for guaranting unique values within a tenant are OID and SUB.

OID vs SUB

This is what you are here for. Both of these claims guarantee uniqueness. There are subtle differences like the degree of uniqueness that these values provide.

Object Identifier Claim (OID)

In context of Microsoft Identity Platform this property maps directly to Object Identifier in the directory. For Enterprise applications integrating with Microsoft services, this becomes the easy choice. This property guarantees uniqueness in general. However, pairing the OID with TID (Tenant ID) provides additional defence against an accidental GUID collision.

By design, for the same user on different tenants (as a guest user), applications will get a different identifier. This is to protect a user’s directory or application information on a tenant from being mapped to another tenant.

However, a user from the same tenant appearing on multiple applications will share that same OID. This has prompted Microsoft to enforce apps to have the profile scope enabled to obtain this claim for users.

It is also important to note that OID does not find place in the JWT RFC (rfc7519). So if your application accepts tokens from multiple Identity Providers, OID might NOT be your best choice.

Subject Claim (SUB)

The subject claim is guaranteed to be unique within a tenant and within the application as well. Meaning that the same user appearing on two different applications will use a different SUB value. This makes it difficult for applications to map a user’s data across two different applications. This is highly advantageous for applications that would like to meet high privacy standards.

Additionaly, SUB is supported via the JWT token RFC (rfc7519). Meaning, every Identity Provider passing on JWT tokens is bound to provide a SUB claim that is populated with a unique value per user. If you are looking at extending support to multiple Identity Providers, SUB would be your best choice.

TL;DR

• OID works best for applications that are looking to integrate exclusively with the Microsoft Identity Platform.
• OID works best if applications rely on the directory identifier to integrate with other applications.
• SUB works best for applications aiming to serve high privacy standards.
• SUB works best for applications that are looking to integrate with multiple identity providers serving fully complaint JWTs.