Single Sign-On

When you request for an access token, you can also get an OpenID Connect 1.0 id_token. You can get the id_token in the Implicit Grant flow and in the Authorization Code Grant flow.

In the Authorization Code Grant flow, you can get an id_token by including the openid scope in the request for the authorization code. The service returns the id_token in the response body, after the client successfully exhanges the authorization code for an access token.
For more information, see the Grants section of the documentation.

In the Implicit Grant flow, the client can request for an id_token by setting the request parameter response_type to id_token token. When the user is successfully authenticated, the service returns the id_token in the Location header of the response.

By using the id_token in subsequent requests for access tokens, the client can acquire a new access token for a different tenant without interrupting the user experience with login prompts.

The client passes the id_token hint (id_token_hint) as:

  • A form parameter for POST requests
  • A query parameter for GET requests

The client must store the id_token securely so that the user's identity remains confidential. For more information, see the OpenID Connect 1.0 specification.

The id_token represents the user's (resource owner's) identity. It does not allow to access data in tenants that are not related to the user or to elevate the allowed scopes. All existing security rules apply exactly as if the user had provided the credentials on a sign-in page.

The following example shows a single sign-on flow.

  1. Acquire an access token with id_token. Note the use of the id_token token and nonce parameters, which are required by the OpenID Connect specification. The correct response contains both the access token and an id_token. The id_token can be used in subsequent requests to the /authorize endpoint. This shows a typical request:

    curl -i -H "Content-Type: application/x-www-form-urlencoded" -X POST -d "response_type=id_token token&client_id=CLIENT_ID&nonce=NONCE&scope=SCOPE&state=STATE"
  2. Use the id_token acquired in the first step to get an access token for another tenant. The response from the service is the same as in the first step. However, this time the service accepts the id_token provided as the value of the id_token_hint parameter. The user doesn't have to provide credentials on a sign-in screen to continue. This shows a typical request:

    curl -i -H "Content-Type: application/x-www-form-urlencoded" -X POST -d "response_type=token&client_id=CLIENT_ID&scope=SCOPE&state=STATE&id_token_hint=ID_TOKEN_OBTAINED_IN_CALL_FROM_STEP_1"
You must validate ID tokens to avoid misuse and mitigate security risks. Find more information in the Validate an ID token section.