Identity V On
-->
The Microsoft identity platform helps you build applications your users and customers can sign in to using their Microsoft identities or social accounts, and provide authorized access to your own APIs or Microsoft APIs like Microsoft Graph.
Identity.com is an open source ecosystem providing access to on-demand, secure identity verification. Governed by a staking mechanism designed to ensure compliance and good behavior within the ecosystem, Identity.com grants users, requesters, and validators around the world access to low-cost reusable identity verification powered by CVC tokens.
There are several components that make up the Microsoft identity platform:
- OAuth 2.0 and OpenID Connect standard-compliant authentication service enabling developers to authenticate several identity types, including:
- Work or school accounts, provisioned through Azure AD
- Personal Microsoft account, like Skype, Xbox, and Outlook.com
- Social or local accounts, by using Azure AD B2C
- Open-source libraries: Microsoft Authentication Libraries (MSAL) and support for other standards-compliant libraries
- Application management portal: A registration and configuration experience in the Azure portal, along with the other Azure management capabilities.
- Application configuration API and PowerShell: Programmatic configuration of your applications through the Microsoft Graph API and PowerShell so you can automate your DevOps tasks.
- Developer content: Technical documentation including quickstarts, tutorials, how-to guides, and code samples.
For developers, the Microsoft identity platform offers integration of modern innovations in the identity and security space like passwordless authentication, step-up authentication, and Conditional Access. You don’t need to implement such functionality yourself: applications integrated with the Microsoft identity platform natively take advantage of such innovations.
With the Microsoft identity platform, you can write code once and reach any user. You can build an app once and have it work across many platforms, or build an app that functions as a client as well as a resource application (API).
Identity & Access Management. Redefine your security posture, tightly securing your internal environment. Microsoft Platform Management. Move faster, improve security and stay in control for everything Microsoft. Unified Endpoint Management. Manage, secure & patch all endpoints. Take control of network-connected devices. Home - Supreme Court of the United States.
For a video overview of the platform and a demo of the authentication experience, see What is the Microsoft identity platform for developers?.
Getting started
Choose the application scenario you'd like to build. Each of these scenario paths starts with an overview and links to a quickstart to help you get up and running:
As you work with the Microsoft identity platform to integrate authentication and authorization in your apps, you can refer to this image that outlines the most common app scenarios and their identity components. Select the image to view it full-size.
Learn authentication concepts
Learn how core authentication and Azure AD concepts apply to the Microsoft identity platform in this recommended set of articles:
More identity and access management options
Azure AD B2C - Build customer-facing applications your users can sign in to using their social accounts like Facebook or Google, or by using an email address and password.
Azure AD B2B - Invite external users into your Azure AD tenant as 'guest' users, and assign permissions for authorization while they use their existing credentials for authentication.
Azure Active Directory for developers (v1.0) - Shown here for developers with existing apps that use the older v1.0 endpoint. Do not use v1.0 for new projects.
Next steps
If you have an Azure account you already have access to an Azure Active Directory tenant, but most Microsoft identity platform developers need their own Azure AD tenant for use while developing applications, a 'dev tenant.'
Learn how to create your own tenant for use while building your applications:
-->OpenID Connect (OIDC) is an authentication protocol built on OAuth 2.0 that you can use to securely sign in a user to an application. When you use the Microsoft identity platform's implementation of OpenID Connect, you can add sign-in and API access to your apps. This article shows how to do this independent of language and describes how to send and receive HTTP messages without using any Microsoft open-source libraries.
OpenID Connect extends the OAuth 2.0 authorization protocol for use as an authentication protocol, so that you can do single sign-on using OAuth. OpenID Connect introduces the concept of an ID token, which is a security token that allows the client to verify the identity of the user. The ID token also gets basic profile information about the user. It also introduces the UserInfo endpoint, an API that returns information about the user.
Tip
Try executing this request and more in Postman -- don't forget to replace tokens and IDs!
Protocol diagram: Sign-in
The most basic sign-in flow has the steps shown in the next diagram. Each step is described in detail in this article.
Fetch the OpenID Connect metadata document
OpenID Connect describes a metadata document (RFC) that contains most of the information required for an app to do sign in. This includes information such as the URLs to use and the location of the service's public signing keys. You can find this document by appending the discovery document path to the authority URL:
Discovery document path: /.well-known/openid-configuration
Authority: https://login.microsoftonline.com/{tenant}/v2.0
The {tenant} can take one of four values:
| 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 (whether they are members in the directory with a work or school account, or they are guests in the directory with a personal Microsoft account) can sign in to the application. Either the friendly domain name of the Azure AD tenant or the tenant's GUID identifier can be used. You can also use the consumer tenant, 9188040d-6c67-4c5b-b112-36a304b66dad, in place of the consumers tenant. |
The authority differs across national clouds - e.g. https://login.microsoftonline.de for the Azure AD Germany instance. If you do not use the public cloud, please review the national cloud endpoints to find the appropriate one for you. Ensure that the tenant and /v2.0/ are present in your request so you can use the v2.0 version of the endpoint.
Tip
Try it! Click https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration to see the common configuration.
Sample request
To call the userinfo endpoint for the common authority on the public cloud, use the following:
Sample response
The metadata is a simple JavaScript Object Notation (JSON) document. See the following snippet for an example. The contents are fully described in the OpenID Connect specification.
If your app has custom signing keys as a result of using the claims-mapping feature, you must append an appid query parameter containing the app ID in order to get a jwks_uri pointing to your app's signing key information. For example: https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration?appid=6731de76-14a6-49ae-97bc-6eba6914391e contains a jwks_uri of https://login.microsoftonline.com/{tenant}/discovery/v2.0/keys?appid=6731de76-14a6-49ae-97bc-6eba6914391e.
Typically, you would use this metadata document to configure an OpenID Connect library or SDK; the library would use the metadata to do its work. However, if you're not using a pre-built OpenID Connect library, you can follow the steps in the remainder of this article to do sign-in in a web app by using the Microsoft identity platform.
Send the sign-in request
When your web app needs to authenticate the user, it can direct the user to the /authorize endpoint. This request is similar to the first leg of the OAuth 2.0 authorization code flow, with these important distinctions:
- The request must include the
openidscope in thescopeparameter. - The
response_typeparameter must includeid_token. - The request must include the
nonceparameter.
Important
In order to successfully request an ID token from the /authorization endpoint, the app registration in the registration portal must have the implicit grant of id_tokens enabled in the Authentication tab (which sets the oauth2AllowIdTokenImplicitFlow flag in the application manifest to true). If it isn't enabled, an unsupported_response error will be returned: 'The provided value for the input parameter 'response_type' isn't allowed for this client. Expected value is 'code'
For example:
| 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 id_token for OpenID Connect sign-in. It might also include other response_type values, such as code. |
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 included in the request, generated by the app, that will be included in the resulting id_token value as a claim. The app can verify this value to mitigate token replay attacks. The value typically is a randomized, unique string that can be used to identify the origin of the request. |
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 (because no user is signed in, the hinted user isn't signed in, or there are multiple users signed in and no hint is provided), the Microsoft identity platform returns an error. 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 cannot use login_hint and select_account together. |
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_hintoptional 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 looks like this:
| 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_tokens 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 that the app can handle them. An error response looks like this:
| 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, such as a missing, required parameter. | Fix and resubmit the request. This is a development error that typically is caught during initial testing. |
unauthorized_client | The client application can't request an authorization code. | This usually occurs 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 does not support the response type in the request. | Fix and resubmit the request. This is a development error that typically is caught during initial 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 either it does not exist, Azure AD can't find it, or it isn't correctly configured. | This 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
Just receiving an id_token isn't always sufficient to authenticate the user; you may also need to validate the id_token's signature and verify the claims in the token per your app's requirements. Like all OIDC platforms, the Microsoft identity platform uses JSON Web Tokens (JWTs) and public key cryptography to sign ID tokens and verify that they're valid.
Not all apps benefit from verifying the ID token - native apps and single page apps, for instance, rarely benefit from validating the ID token. Someone with physical access to the device (or browser) can bypass the validation in many ways - from editing the web traffic to the device to provide fake tokens and keys to simply debugging the application to skip the validation logic. On the other hand, web apps and APIs using an ID token to authorization must validate the ID token carefully since they are gating access to data.
Once you've validated the signature of the id_token, there are a few claims you'll be required to verify. See the id_token reference for more information, including Validating Tokens and Important Information About Signing Key Rollover. We recommend making use of a library for parsing and validating tokens - there is at least one available for most languages and platforms.
You may also wish to validate additional claims depending on your scenario. Some common validations include:
- 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 have validated the id_token, you can begin a session with the user and use the claims in the id_token to obtain information about the user in your app. This information can be used for display, records, personalization, etc.
Protocol diagram: Access token acquisition
Many web apps need to not only sign the user in, but also to access a web service on behalf of the user by using OAuth. This scenario combines OpenID Connect for user authentication while simultaneously getting an authorization code that you can use to get access tokens if you are using the OAuth authorization code flow.
The full OpenID Connect sign-in and token acquisition flow looks similar to the next diagram. We describe each step in detail in the next sections of the article.
Get an access token to call UserInfo
To acquire a token for the OIDC UserInfo endpoint, modify the sign-in request:
You can also use the authorization code flow, the device code flow, or a refresh token in place of response_type=token to get a token for your app.
Tip
Click the following link to execute this request. After you sign in, your browser is redirected to https://localhost/myapp/, with an ID token and a token in the address bar. Note that this request uses response_mode=fragment for demonstration purposes only - for a webapp we recommend using form_post for additional security where possible.https://login.microsoftonline.com/common/oauth2/v2.0/authorize...
Successful token response
A successful response from using response_mode=form_post looks like this:
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. Note that since the UserInfo endpoint is hosted on MS Graph, there may be additional Graph scopes listed here (e.g. user.read) if they were previously granted to the app. That's because a token for a given resource always includes every permission currently granted to the client. |
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_tokens 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 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. An error response looks like this:
| 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 the call the UserInfo endpoint with this token.
Send a sign-out request
When you want to sign out the user from your app, it isn't sufficient to clear your app's cookies or otherwise end the user's session. You must also redirect the user to the Microsoft identity platform to sign out. If you don't do this, the user reauthenticates to your app without entering their credentials again, because they will have a valid single sign-in session with the Microsoft identity platform.
You can redirect the user to the end_session_endpoint listed in the OpenID Connect metadata document:
| 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. |
Single sign-out
Identity V Online
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.
Identity V On Kindle
Next steps
Identity V On Laptop
- Review the UserInfo documentation
- Learn how to customize the values in a token with data from your on-premises systems.
- Learn how to include additional standard claims in tokens.