OpenID Connect on the Microsoft identity platform

OpenID Connect (OIDC) extends the OAuth 2.0 authorization protocol for use as another authentication protocol. You can use OIDC to enable single sign-on (SSO) between your OAuth-enabled applications by using a security token called an ID token.

The full specification for OIDC is available on the OpenID Foundation's website at OpenID Connect Core 1.0 specification.

Protocol flow: Sign-in

The following diagram shows the basic OpenID Connect sign-in flow. The steps in the flow are described in more detail in later sections of the article.

Enable ID tokens

The ID token introduced by OpenID Connect is issued by the authorization server, the Microsoft identity platform, when the client application requests one during user authentication. The ID token enables a client application to verify the identity of the user and to get other information (claims) about them.

ID tokens aren't issued by default for an application registered with the Microsoft identity platform. ID tokens for an application are enabled by using one of the following methods:

1. Sign in to the Microsoft Entra admin center.
2. Browse to Identity > Applications > App registrations > <your application> > Authentication.
3. Under Platform configurations, select Add a platform.
4. In the pane that opens, select the appropriate platform for your application. For example, select Web for a web application.
5. Under Redirect URIs, add the redirect URI of your application. For example, https://localhost:8080/.
6. Under Implicit grant and hybrid flows, select the ID tokens (used for implicit and hybrid flows) checkbox.

Or:

1. Select Identity > Applications > App registrations > <your application> > Manifest.
2. Set oauth2AllowIdTokenImplicitFlow to true in the app registration's application manifest.

If ID tokens aren't enabled for your app and one is requested, the Microsoft identity platform returns an unsupported_response error similar to:

The provided value for the input parameter 'response_type' isn't allowed for this client. Expected value is 'code'.

Requesting an ID token by specifying a response_type of id_token is explained in Send the sign-in request later in the article.

Fetch the OpenID configuration document

OpenID providers like the Microsoft identity platform provide an OpenID Provider Configuration Document at a publicly accessible endpoint containing the provider's OIDC endpoints, supported claims, and other metadata. Client applications can use the metadata to discover the URLs to use for authentication and the authentication service's public signing keys.

Authentication libraries are the most common consumers of the OpenID configuration document, which they use for discovery of authentication URLs, the provider's public signing keys, and other service metadata. If an authentication library is used in your app, you likely won't need to hand-code requests to and responses from the OpenID configuration document endpoint.

Find your app's OpenID configuration document URI

Every app registration in Microsoft Entra ID is provided a publicly accessible endpoint that serves its OpenID configuration document. To determine the URI of the configuration document's endpoint for your app, append the well-known OpenID configuration path to your app registration's authority URL.

• Well-known configuration document path: /.well-known/openid-configuration
• Authority URL: https://login.microsoftonline.com/{tenant}/v2.0

The value of {tenant} varies based on the application's sign-in audience as shown in the following table. The authority URL also varies by cloud instance.

To find the OIDC configuration document in the Microsoft Entra admin center, sign in to the Microsoft Entra admin center and then:

1. Browse to Identity > Applications > App registrations > <your application> > Endpoints.
2. Locate the URI under OpenID Connect metadata document.

Sample request

The following request gets the OpenID configuration metadata from the common authority's OpenID configuration document endpoint on the Azure public cloud:

GET /common/v2.0/.well-known/openid-configuration
Host: login.microsoftonline.com

Sample response

The configuration metadata is returned in JSON format as shown in the following example (truncated for brevity). The metadata returned in the JSON response is described in detail in the OpenID Connect 1.0 discovery specification.

{
  "authorization_endpoint": "https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize",
  "token_endpoint": "https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token",
  "token_endpoint_auth_methods_supported": [
    "client_secret_post",
    "private_key_jwt"
  ],
  "jwks_uri": "https://login.microsoftonline.com/{tenant}/discovery/v2.0/keys",
  "userinfo_endpoint": "https://graph.microsoft.com/oidc/userinfo",
  "subject_types_supported": [
      "pairwise"
  ],
  ...
}

Send the sign-in request

To authenticate a user and request an ID token for use in your application, direct their user-agent to the Microsoft identity platform's /authorize endpoint. The request is similar to the first leg of the OAuth 2.0 authorization code flow but with these distinctions:

• Include the openid scope in the scope parameter.
• Specify id_token in the response_type parameter.
• Include the nonce parameter.

Example sign-in request (line breaks included only for readability):

GET https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=id_token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=form_post
&scope=openid
&state=12345
&nonce=678910

At this point, the user is prompted to enter their credentials and complete the authentication. The Microsoft identity platform verifies that the user has consented to the permissions indicated in the scope query parameter. If the user hasn't consented to any of those permissions, the Microsoft identity platform prompts the user to consent to the required permissions. You can read more about permissions, consent, and multitenant apps.

After the user authenticates and grants consent, the Microsoft identity platform returns a response to your app at the indicated redirect URI by using the method specified in the response_mode parameter.

Successful response

A successful response when you use response_mode=form_post is similar to:

POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded

id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNB...&state=12345

Error response

Error responses might also be sent to the redirect URI so the app can handle them, for example:

POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded

error=access_denied&error_description=the+user+canceled+the+authentication

Error codes for authorization endpoint errors

The following table describes error codes that can be returned in the error parameter of the error response:

Validate the ID token

Receiving an ID token in your app might not always be sufficient to fully authenticate the user. You might also need to validate the ID token's signature and verify its claims per your app's requirements. Like all OpenID providers, the Microsoft identity platform's ID tokens are JSON Web Tokens (JWTs) signed by using public key cryptography.

Web apps and web APIs that use ID tokens for authorization must validate them because such applications get access to data. Other types of application might not benefit from ID token validation, however. Native and single-page applications (SPA), for example, rarely benefit from ID token validation because any entity with physical access to the device or browser can potentially bypass the validation.

Two examples of token validation bypass are:

• Providing fake tokens or keys by modifying network traffic to the device
• Debugging the application and stepping over the validation logic during program execution.

If you validate ID tokens in your application, we recommend not doing so manually. Instead, use a token validation library to parse and validate tokens. Token validation libraries are available for most development languages, frameworks, and platforms.

What to validate in an ID token

In addition to validating ID token's signature, you should validate several of its claims as described in Validating an ID token. Also see Important information about signing key-rollover.

Several other validations are common and vary by application scenario, including:

• Ensuring the user/organization has signed up for the app.
• Ensuring the user has proper authorization/privileges
• Ensuring a certain strength of authentication has occurred, such as multifactor authentication.

Once you've validated the ID token, you can begin a session with the user and use the information in the token's claims for app personalization, display, or for storing their data.

Protocol diagram: Access token acquisition

Many applications need not only to sign in a user, but also access a protected resource like a web API on behalf of the user. This scenario combines OpenID Connect to get an ID token for authenticating the user and OAuth 2.0 to get an access token for a protected resource.

The full OpenID Connect sign-in and token acquisition flow looks similar to this diagram:

Get an access token for the UserInfo endpoint

In addition to the ID token, the authenticated user's information is also made available at the OIDC UserInfo endpoint.

To get an access token for the OIDC UserInfo endpoint, modify the sign-in request as described here:

// Line breaks are for legibility only.

GET https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444        // Your app registration's Application (client) ID
&response_type=id_token%20token                       // Requests both an ID token and access token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F       // Your application's redirect URI (URL-encoded)
&response_mode=form_post                              // 'form_post' or 'fragment'
&scope=openid+profile+email                           // 'openid' is required; 'profile' and 'email' provide information in the UserInfo endpoint as they do in an ID token. 
&state=12345                                          // Any value - provided by your app
&nonce=678910                                         // Any value - provided by your app

You can use the authorization code flow, the device code flow, or a refresh token in place of response_type=token to get an access token for your app.

Successful token response

A successful response from using response_mode=form_post:

POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded
 access_token=eyJ0eXAiOiJKV1QiLCJub25jZSI6I....
 &token_type=Bearer
 &expires_in=3598
 &scope=email+openid+profile
 &id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI....
 &state=12345

Response parameters mean the same thing regardless of the flow used to acquire them.

Error response

Error responses might also be sent to the redirect URI so that the app can handle them appropriately:

POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded

error=access_denied&error_description=the+user+canceled+the+authentication

For a description of possible error codes and recommended client responses, see Error codes for authorization endpoint errors.

When you have an authorization code and an ID token, you can sign the user in and get access tokens on their behalf. To sign the user in, you must validate the ID token as described in the validate tokens. To get access tokens, follow the steps described in OAuth code flow documentation.

Calling the UserInfo endpoint

Review the UserInfo documentation to look over how to call the UserInfo endpoint with this token.

Send a sign-out request

To sign out a user, perform both of the following operations:

1. Redirect the user's user-agent to the Microsoft identity platform's logout URI.
2. Clear your app's cookies or end the user's session in your application.

If you fail to perform either of these operations, the user may remain authenticated and not be prompted to sign-in the next time they use your app.

Redirect the user-agent to the end_session_endpoint as shown in the OpenID Connect configuration document. The end_session_endpoint supports both HTTP GET and POST requests.

GET https://login.microsoftonline.com/common/oauth2/v2.0/logout?
post_logout_redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F

Single sign-out

When you redirect the user to the end_session_endpoint in an application, the Microsoft identity platform ends the user session for this application. However, the user may still be signed in to other applications that use the same Microsoft accounts for authentication.

When a user has signed into multiple web or SPA applications registered in this directory (also known as a tenant) single sign-out allows this user to sign out of all applications instantly by signing out in either one of the applications.

To enable single sign-out for your Entra application, you should use the OpenID Connect front channel logout feature. This feature allows an application to notify other applications that the user has logged out. When the user logs out of one application, the Microsoft identity platform sends an HTTP GET request to the front-channel logout URL of every application that the user is currently signed in to.

These applications must respond to this request by performing the following two actions for single sign-out to be successful:

1. Clear any session that identifies the user.
2. Applications must respond to this request by clearing any session that identifies the user and returning a 200 response.

What is a front channel logout URL?

A front channel logout URL is where your web or SPA application receives the sign out request from the Entra authentication server and performs single sign-out functionality. Each application has one front channel logout URL.

When should you set a front channel logout URL?

If you or your developer has determined single sign-out is required for an application, you must set the front channel logout URL for this application’s app registration. Once the front channel logout URL is set for this application’s app registration, the Microsoft identity platform sends an HTTP GET request to the front-channel logout URL of this application when the signed in user has signed out of another application.

How to set up single sign out using front channel logout feature

To use the front channel logout feature for a set of applications, you must complete the following two tasks:

• Set the front channel logout URL in the Microsoft Entra admin center for all the applications that should be signed out simultaneously. Each application typically has its own dedicated front channel logout URL.
• Edit the applications code so that they listen for an HTTP GET request sent by the Microsoft identity platform to the front channel logout URL, and respond to this request by clearing any session that identifies the user and returning a 200 response.

How to choose a front channel logout URL

The front channel logout URL should be a URL that is capable of receiving and responding to HTTP GET requests and should be able to clear any session that identifies the user. Examples of a front channel logout URL could be, but aren't limited to, the following:

• https://example.com/frontchannel_loout
• https://example.com/signout
• https://example.com/logout

Next steps

• Review the UserInfo endpoint documentation.
• Populate claim values in a token with data from on-premises systems.
• Include your own claims in tokens.