Essential Insights for Implementing OAuth/OIDC with MS Entra ID
Written on
Understanding OAuth/OIDC with MS Entra ID
Recently, I have been focused on integrating a Java-based web application with Microsoft Entra ID (previously Azure AD) using OIDC. This document outlines key insights I've gathered during this process.
Section 1.1: Utilize Version 2.0
It's common to face challenges during initial setups, and Microsoft is no different. When retrieving the well-known OIDC configuration from the provider URL, ensure that you use version 2.0. The URL should resemble the following format, with v2.0 highlighted:
In version 1, the issuer URL diverges from the provider URL, which breaches the standard.
Section 1.2: Differentiate Between Sub and Oid
ID tokens include both a sub and an oid claim, and it’s crucial to understand their distinctions. The subject (sub) uniquely identifies a user within your application, but this identification is not universal. Different applications will receive varying sub values for the same user.
Conversely, the object ID (oid) uniquely identifies a user across all applications within your Azure tenant. All applications will retrieve the same oid value for the same user.
Section 1.3: Limitations of MSAL
While the Microsoft Authentication Library (MSAL) is a valuable tool, it is primarily designed for token acquisition. If your application also exposes an API and requires validation of access tokens, you will need a more comprehensive solution.
I recommend the Nimbus SDK for OAuth 2.0, which includes extensions for OIDC and supports all flows and validation processes. It is well-documented and offers excellent examples. If MSAL meets your needs, that's fine, but be aware that transitioning to another OIDC provider may pose challenges.
Chapter 2: The On-Behalf-Of Flow
Section 2.1: Understanding On-Behalf-Of
When your application must access another application on behalf of the logged-in user, Microsoft provides the On-Behalf-Of (OBO) flow. It's surprising to discover that this flow is not mentioned in any OAuth 2.0 RFCs, as it is not a standard flow.
Instead, it’s a term Microsoft uses for a token request initiated with the type urn:ietf:params:oauth:grant-type:jwt-bearer. While it may sound appealing, clarity in naming conventions would be appreciated.
Caution: Microsoft mandates the inclusion of a requested_token_use attribute with the value on_behalf_of in a token request of type urn:ietf:params:oauth:grant-type:jwt-bearer, which contradicts the OAuth 2.0 standard.
Section 2.2: Implementing PKCE
PKCE, which stands for Proof Key for Code Exchange, is a vital security measure that should always be enabled. I previously wrote an article discussing this topic in depth. Don’t forget to activate it in your MS Entra ID settings!
Bonus Insight
As a bonus for those who have made it this far, remember to include offline_access in your token request scopes! Without it, you won't receive a refresh token, which can be essential for maintaining user sessions.