Every app registration in Azure AD 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.
| Value | Description |
|---|---|
common | Users with both a personal Microsoft account and a work or school account from Azure AD can sign in to the application. |
organizations | Only users with work or school accounts from Azure AD can sign in to the application. |
consumers | Only users with a personal Microsoft account can sign in to the application. |
8eaef023-2b34-4da1-9baa-8bc8c9d6a490 or contoso.onmicrosoft.com | Only users from a specific Azure AD tenant (directory members with a work or school account or directory guests with a personal Microsoft account) can sign in to the application. The value can be the domain name of the Azure AD tenant or the tenant ID in GUID format. You can also use the consumer tenant GUID, 9188040d-6c67-4c5b-b112-36a304b66dad, in place of consumers. |
Tip
Note that when using the common or consumers authority for personal Microsoft accounts, the consuming resource application must be configured to support such type of accounts in accordance with signInAudience.
To find the OIDC configuration document in the Azure portal, navigate to the Azure portal and then:
- Select Azure Active Directory > App registrations > <your application> > Endpoints.
- 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:
HTTPCopy
GET /common/v2.0/.well-known/openid-configuration
Host: login.microsoftonline.com
Tip
Try it! To see the OpenID configuration document for an application’s common authority, navigate to https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration.
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.
JSONCopy
{
"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
openidscope in thescopeparameter. - Specify
codein theresponse_typeparameter. - Include the
nonceparameter.
Example sign-in request (line breaks included only for readability):
HTTPCopy
GET https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&response_type=id_token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=form_post
&scope=openid
&state=12345
&nonce=678910
| Parameter | Condition | Description |
|---|---|---|
tenant | Required | You can use the {tenant} value in the path of the request to control who can sign in to the application. The allowed values are common, organizations, consumers, and tenant identifiers. For more information, see protocol basics. Critically, for guest scenarios where you sign a user from one tenant into another tenant, you must provide the tenant identifier to correctly sign them into the resource tenant. |
client_id | Required | The Application (client) ID that the Azure portal – App registrations experience assigned to your app. |
response_type | Required | Must include code for OpenID Connect sign-in. |
redirect_uri | Recommended | The redirect URI of your app, where authentication responses can be sent and received by your app. It must exactly match one of the redirect URIs you registered in the portal, except that it must be URL-encoded. If not present, the endpoint will pick one registered redirect_uri at random to send the user back to. |
scope | Required | A space-separated list of scopes. For OpenID Connect, it must include the scope openid, which translates to the Sign you in permission in the consent UI. You might also include other scopes in this request for requesting consent. |
nonce | Required | A value generated and sent by your app in its request for an ID token. The same nonce value is included in the ID token returned to your app by the Microsoft identity platform. To mitigate token replay attacks, your app should verify the nonce value in the ID token is the same value it sent when requesting the token. The value is typically a unique, random string. |
response_mode | Recommended | Specifies the method that should be used to send the resulting authorization code back to your app. Can be form_post or fragment. For web applications, we recommend using response_mode=form_post, to ensure the most secure transfer of tokens to your application. |
state | Recommended | A value included in the request that also will be returned in the token response. It can be a string of any content you want. A randomly generated unique value typically is used to prevent cross-site request forgery attacks. The state also is used to encode information about the user’s state in the app before the authentication request occurred, such as the page or view the user was on. |
prompt | Optional | Indicates the type of user interaction that is required. The only valid values at this time are login, none, consent, and select_account. The prompt=login claim forces the user to enter their credentials on that request, which negates single sign-on. The prompt=none parameter is the opposite, and should be paired with a login_hint to indicate which user must be signed in. These parameters ensure that the user isn’t presented with any interactive prompt at all. If the request can’t be completed silently via single sign-on, the Microsoft identity platform returns an error. Causes include no signed-in user, the hinted user isn’t signed in, or multiple users are signed in but no hint was provided. The prompt=consent claim triggers the OAuth consent dialog after the user signs in. The dialog asks the user to grant permissions to the app. Finally, select_account shows the user an account selector, negating silent SSO but allowing the user to pick which account they intend to sign in with, without requiring credential entry. You can’t use both login_hint and select_account. |
login_hint | Optional | You can use this parameter to pre-fill the username and email address field of the sign-in page for the user, if you know the username ahead of time. Often, apps use this parameter during reauthentication, after already extracting the login_hint optional claim from an earlier sign-in. |
domain_hint | Optional | The realm of the user in a federated directory. This skips the email-based discovery process that the user goes through on the sign-in page, for a slightly more streamlined user experience. For tenants that are federated through an on-premises directory like AD FS, this often results in a seamless sign-in because of the existing login session. |
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 multi-tenant 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:
HTTPCopy
POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded
id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNB...&state=12345
| Parameter | Description |
|---|---|
id_token | The ID token that the app requested. You can use the id_token parameter to verify the user’s identity and begin a session with the user. For more information about ID tokens and their contents, see the ID token reference. |
state | If a state parameter is included in the request, the same value should appear in the response. The app should verify that the state values in the request and response are identical. |
Error response
Error responses might also be sent to the redirect URI so the app can handle them, for example:
HTTPCopy
POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded
error=access_denied&error_description=the+user+canceled+the+authentication
| Parameter | Description |
|---|---|
error | An error code string that you can use to classify types of errors that occur, and to react to errors. |
error_description | A specific error message that can help you identify the root cause of an authentication error. |
Error codes for authorization endpoint errors
The following table describes error codes that can be returned in the error parameter of the error response:
| Error code | Description | Client action |
|---|---|---|
invalid_request | Protocol error like a missing required parameter. | Fix and resubmit the request. This development error should be caught during application testing. |
unauthorized_client | The client application can’t request an authorization code. | This error can occur when the client application isn’t registered in Azure AD or isn’t added to the user’s Azure AD tenant. The application can prompt the user with instructions to install the application and add it to Azure AD. |
access_denied | The resource owner denied consent. | The client application can notify the user that it can’t proceed unless the user consents. |
unsupported_response_type | The authorization server doesn’t support the response type in the request. | Fix and resubmit the request. This development error should be caught during application testing. |
server_error | The server encountered an unexpected error. | Retry the request. These errors can result from temporary conditions. The client application might explain to the user that its response is delayed because of a temporary error. |
temporarily_unavailable | The server is temporarily too busy to handle the request. | Retry the request. The client application might explain to the user that its response is delayed because of a temporary condition. |
invalid_resource | The target resource is invalid because it doesn’t exist, Azure AD can’t find it, or it’s configured incorrectly. | This error indicates that the resource, if it exists, hasn’t been configured in the tenant. The application can prompt the user with instructions for installing the application and adding it to Azure AD. |
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 apps (SPAs), 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 in the ID token reference. 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 multi-factor 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:
HTTPCopy
// Line breaks are for legibility only.
GET https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e // 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:
HTTPCopy
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.
| Parameter | Description |
|---|---|
access_token | The token that will be used to call the UserInfo endpoint. |
token_type | Always “Bearer” |
expires_in | How long until the access token expires, in seconds. |
scope | The permissions granted on the access token. Because the UserInfo endpoint is hosted on Microsoft Graph, it’s possible for scope to contain others previously granted to the application (for example, User.Read). |
id_token | The ID token that the app requested. You can use the ID token to verify the user’s identity and begin a session with the user. You’ll find more details about ID tokens and their contents in the ID token reference. |
state | If a state parameter is included in the request, the same value should appear in the response. The app should verify that the state values in the request and response are identical. |
Warning
Don’t attempt to validate or read tokens for any API you don’t own, including the tokens in this example, in your code. Tokens for Microsoft services can use a special format that will not validate as a JWT, and may also be encrypted for consumer (Microsoft account) users. While reading tokens is a useful debugging and learning tool, do not take dependencies on this in your code or assume specifics about tokens that aren’t for an API you control.
Error response
Error responses might also be sent to the redirect URI so that the app can handle them appropriately:
HTTPCopy
POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded
error=access_denied&error_description=the+user+canceled+the+authentication
| Parameter | Description |
|---|---|
error | An error code string that you can use to classify types of errors that occur, and to react to errors. |
error_description | A specific error message that can help you identify the root cause of an authentication error. |
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 exactly as described. 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 these operations:
- Redirect the user’s user-agent to the Microsoft identity platform’s logout URI
- Clear your app’s cookies or otherwise end the user’s session in your application.
If you fail to perform either operation, the user may remain authenticated and not be prompted to sign-in the next time they user 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.
HTTPCopy
GET https://login.microsoftonline.com/common/oauth2/v2.0/logout?
post_logout_redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
| Parameter | Condition | Description |
|---|---|---|
post_logout_redirect_uri | Recommended | The URL that the user is redirected to after successfully signing out. If the parameter isn’t included, the user is shown a generic message that’s generated by the Microsoft identity platform. This URL must match one of the redirect URIs registered for your application in the app registration portal. |
logout_hint | Optional | Enables sign-out to occur without prompting the user to select an account. To use logout_hint, enable the login_hint optional claim in your client application and use the value of the login_hint optional claim as the logout_hint parameter. Don’t use UPNs or phone numbers as the value of the logout_hint parameter. |
Note
After successful sign-out, the active sessions will be set to inactive. If a valid Primary Refresh Token (PRT) exists for the signed-out user and a new sign-in is executed, SSO will be interrupted and user will see a prompt with an account picker. If the option selected is the connected account that refers to the PRT, sign-in will proceed automatically without the need to insert fresh credentials.
Single sign-out
When you redirect the user to the end_session_endpoint, the Microsoft identity platform clears the user’s session from the browser. However, the user may still be signed in to other applications that use Microsoft accounts for authentication. To enable those applications to sign the user out simultaneously, the Microsoft identity platform sends an HTTP GET request to the registered LogoutUrl of all the applications that the user is currently signed in to. Applications must respond to this request by clearing any session that identifies the user and returning a 200 response. If you wish to support single sign-out in your application, you must implement such a LogoutUrl in your application’s code. You can set the LogoutUrl from the app registration portal.
Ref: OpenID Connect (OIDC) on the Microsoft identity platform – Microsoft Entra | Microsoft Learn