Authorization Code Grant Flow

 

Access to web APIs by native clients and websites in Azure Active Directory (Azure AD) is implemented by using the OAuth 2.0 Authorization Code Grant flow. In this flow, the user delegates access to a client application. The transaction is protected and mediated by a code grant, which is exchanged for an access token. The client application never sees the user's credentials and the user agent never sees the access token.

The standard Authorization Code Grant flow is described in Section 4.1 of the The OAuth 2.0 Authorization FrameworkThis diagram shows how the Authorization Code Grant Flow works in Azure AD.

Authorization Code Grant Flow Diagram

The following diagram illustrates the Authorization Code Grant flow.

1. The client application starts the flow by redirecting the user agent to the Azure AD authorization endpoint. The user authenticates and consents, if consent is required.

2. The Azure AD authorization endpoint redirects the user agent back to the client application with an authorization code. The user agent returns authorization code to the client application’s redirect URI.

3. The client application requests an access token from the Azure AD token issuance endpoint. It presents the authorization code to prove that the user has consented.

4. The Azure AD token issuance endpoint returns an access token and a refresh token. The refresh token can be used to request additional access tokens.

5. The client application uses the access token to authenticate to the Web API.

6. After authenticating the client application, the web API returns the requested data.

Register the Application in Azure AD

To begin, use the Azure Management Portal to register the application in your Azure AD tenant. For detailed instructions, see Adding, Updating, and Removing an App

Request an authorization code

Next, the application prompts the user to authenticate to Azure AD and to allow Azure AD to release an authorization code to the application. The application presents the authorization code to an authorization server and the authorization server returns an access token that gives the application permission to access the resource.

To get the authorization code, the web browser (or an embedded web browser control) navigates to a tenant-specific or common (tenant-independent) endpoint.

: https://login.microsoftonline.com/common/oauth2/authorize
-or-
: https://login.microsoftonline.com/<tenant id>/oauth2/authorize

Note

If the user is part of an organization, an administrator of the organization can consent or decline on the user's behalf, or permit the user to consent. The user is given the option to consent only when the administrator permits it.

Authorization Code Request

To request an authorization code for access to a resource, create an OAuth 2.0 GET request, like this one:

GET /common/oauth2/authorize? response_type=code&client_id=<client_ID>&redirect_uri=<redirect_uri>

For example:

GET /common/oauth2/authorize?response_type=code&client_id=2d4d11a2-f814-46a7-890a-274a72a7309e&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F

The following table describes the valid parameters in the request.

Parameter	Description
client_id	[Required] Specifies the client id of the application that is registered in Azure Active Directory. To find the application's client ID, in the Azure Management Portal, click Active Directory, click the directory, click the application and then click Configure.
domain_hint	[Optional] Provides a hint about the tenant or domain that the user should use to sign in. The value of the domain_hint is a registered domain for the tenant. If the tenant is federated to an on-premises directory, AAD redirects to the specified tenant federation server.
login_hint	[Optional] Provides a hint to the user on the sign-in page. For example, this value is pre-filled in the username field on the sign-in page.
prompt	[Optional] Indicate the type of user interaction that is required. Valid values are: -- login: The user should be prompted to re-authenticate.-- consent: User consent has been granted, but needs to be updated. The user should be prompted to consent. -- admin_consent: An administrator should be prompted to consent on behalf of all users in their organization.
redirect_uri	[Recommended] Specifies the reply URL of the application. To find the application's reply URL, in the Azure Management Portal, click Active Directory, click the directory, and then click the application and then click Configure. The Reply URL field is in the Single Sign-on section of the Configure page.
resource	[Optional] The App ID URI of the web API (secured resource). To find the App ID URI of the web API, in the Azure Management Portal, click Active Directory, click the directory, click the application and then click Configure.
response_type	[Required] Specifies the requested response type. In an authorization code grant request, the value must be code.
state	[Recommended] A randomly generated non-reused value that is sent in the request and returned in the response. This parameter is used as a mitigation against cross-site request forgery (CSRF) attacks. For more information, see Best Practices for OAuth 2.0 in Azure AD.

Examples

The following are examples of valid GET requests for an authorization code.

In this request, the application with client_id 2d4d11a2-f814-46a7-890a-274a72a7309e requests an authorization code. The authorization code will be used to request a token for the web API with the resource identifierhttps://service.contoso.com/. Because the expected user is admin@contoso.com, this value used in a login_hint that is prefilled in username field on the sign-in page. The redirect_uri value in the request is the registered redirect URI for the application. When the application runs on the user’s device and is not hosted on a website, the redirect URI does not need to be a physical endpoint.

GET 
/common/oauth2/authorize? response_type=code&client_id=2d4d11a2-f814-46a7-890a-274a72a7309e&resource=https%3A%2F%2Fservice.contoso.com%2F&redirect_uri=http%3A%2F%2Flocalhost/myapp%2F&state=D79E5777-702E-4260-9A62-37F75FF22CCE&login_hint=admin%40contoso.com

The following example is similar to the previous one, but it uses the domain_hint parameter to suggest a domain and the prompt parameter to specify a consent prompt.

GET 
/common/oauth2/authorize?response_type=code&client_id=2d4d11a2-f814-46a7-890a-274a72a7309e&resource=https%3A%2F%2Fservice.contoso.com%2F&redirect_uri=http%3A%2F%2Flocalhost/myapp%2F&state=D79E5777-702E-4260-9A62-37F75FF22CCE&domain_hint=contoso.com&prompt=login

Authorization Code Response

When an application sends a GET request for an authorization code, Azure AD sends a response to the value of the redirect_uri parameter in the request. The response includes the following parameters.

Parameter	Description
admin_consent	The value is True if an administrator consented to a consent request prompt.
code	The authorization code that the application requested. The application can use the authorization code to request an access token for the target resource.
session_state	A unique value that identifies the current user session. This value is a GUID, but should be treated as an opaque value that is passed without examination.
state	If a state parameter is included in the request, the same value should appear in the response. The application should verify that the state values in the request and response are identical. For more information, see Best Practices for OAuth 2.0 in Azure AD.

The following is a sample response to an authorization code request.

The location header value matches the redirect_uri value in the request. If the state value in the response matches the state value in the request, the application should store the authorization code for use in the access token request.

GET  HTTP/1.1 302 Found
Location: https://localhost/myapp/?code= AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrqqf_ZT_p5uEAEJJ_nZ3UmphWygRNy2C3jJ239gV_DBnZ2syeg95Ki-374WHUP-i3yIhv5i-7KU2CEoPXwURQp6IVYMw-DjAOzn7C3JCu5wpngXmbZKtJdWmiBzHpcO2aICJPu1KvJrDLDP20chJBXzVYJtkfjviLNNW7l7Y3ydcHDsBRKZc3GuMQanmcghXPyoDg41g8XbwPudVh7uCmUponBQpIhbuffFP_tbV8SNzsPoFz9CLpBCZagJVXeqWoYMPe2dSsPiLO9Alf_YIe5zpi-zY4C3aLw5g9at35eZTfNd0gBRpR5ojkMIcZZ6IgAA&session_state=7B29111D-C220-4263-99AB-6F6E135D75EF&state=D79E5777-702E-4260-9A62-37F75FF22CCE

Use the Authorization Code to Request an Access Token

When the application gets the authorization code from the authorization endpoint, it can use the authorization code to request an access token from Azure AD.

Access Token Request

To redeem an authorization code and get an access token, sent an HTTP POST request to a common or tenant-specific Azure AD Authorization endpoint.

: https://login.microsoftonline.com/common/oauth2/token
or
: https://login.microsoftonline.com/<tenant id>/oauth2/token

The following parameters are valid in a token request.

Parameter	Description
client_id	[Required] The client ID of the native client application. To find the application's client ID, in the Azure Management Portal, click Active Directory, click the directory, click the application and then click Configure.
client_secret	[Required for confidential clients (websites)] Contains the client password.
code	[Required] The authorization code from the aeab0a46-4da1-4300-be9c-3be418f07a5b#BKMK_authorization_code_response.
grant_type	[Required] Indicated the type of grant you are using. For an authorization code grant, the value is authorization_code.
redirect_uri	[Required if it was included in the authorization code request] Specifies the reply URL of the application. The value must match the value of the redirect_uri parameter in the authorization code request. To find the application's reply URL, in the Azure Management Portal, click Active Directory, click the directory, click the application, and then click Configure.
resource	The App ID URI of the web API (secured resource). To find the App ID URI, in the Azure Management Portal, click Active Directory, click the directory, click the application, and then click Configure. If resource was not specified when requesting an authorization code, resource must be specified. Otherwise, resource is optional.

Example

The following HTTP POST request includes all required parameters and the optional resource parameter.

POST common/oauth2/token HTTP/1.1
Host: : https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&client_id=2d4d11a2-f814-46a7-890a-274a72a7309e&code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrqqf_ZT_p5uEAEJJ_nZ3UmphWygRNy2C3jJ239gV_DBnZ2syeg95Ki-374WHUP-i3yIhv5i-7KU2CEoPXwURQp6IVYMw-DjAOzn7C3JCu5wpngXmbZKtJdWmiBzHpcO2aICJPu1KvJrDLDP20chJBXzVYJtkfjviLNNW7l7Y3ydcHDsBRKZc3GuMQanmcghXPyoDg41g8XbwPudVh7uCmUponBQpIhbuffFP_tbV8SNzsPoFz9CLpBCZagJVXeqWoYMPe2dSsPiLO9Alf_YIe5zpi-zY4C3aLw5g9at35eZTfNd0gBRpR5ojkMIcZZ6IgAA&redirect_uri=https%3A%2F%2Flocalhost%2Fmyapp%2F&resource=https%3A%2F%2Fservice.contoso.com%2F&client_secret=p@ssw0rd

Access Token Response

The response to a request for an access token includes the following parameters.

Parameter	Description
access_token	The requested access token. The application can use this token to authenticate to the secured resource, such as a web API.
expires_in	How long the access token is valid (in seconds).
expires_on	The time when the access token expires. The date is represented as the number of seconds from 1970-01-01T0:0:0Z UTC until the expiration time. This value is used to determine the lifetime of cached tokens.
id_token	An unsigned JSON Web Token (JWT). The application can use this token to request information about the user who consented. The application can cache the values and display them.
refresh_token	An OAuth 2.0 refresh token. The application can use this token acquire additional access tokens after the current access token expires.
resource	The App ID URI of the web API (secured resource).
scope	Impersonation permissions granted to the client application. The default permission is user_impersonation. The owner of the secured resource can register additional values in Azure AD.
token_type	Indicates the token type value. The only type that Azure AD supports is Bearer For more information about bearer tokens, see The OAuth 2.0 Authorization Framework: Bearer Token Usage (RFC 6750).

The id_token parameter value is a JSON web token (JWT) that includes the following claim types. For more information about JSON web tokens, see the JWT IETF draft specification at https://go.microsoft.com/fwlink/?LinkId=392344.

Claim type	Description
aud	Audience of the token. When the token is issued to a client application, the audience is the client_id of the client.
exp	Expiration time. The time when the token expires. For the token to be valid, the current date/time must be less than or equal to the exp value. The time is represented as the number of seconds from January 1, 1970 (1970-01-01T0:0:0Z) UTC until the time the token was issued.
family_name	User’s last name or surname. The application can display this value.
given_name	User’s first name. The application can display this value.
iat	Issued at time. The time when the JWT was issued. The time is represented as the number of seconds from January 1, 1970 (1970-01-01T0:0:0Z) UTC until the time the token was issued.
iss	Identifies the token issuer
nbf	Not before time. The time when the token becomes effective. For the token to be valid, the current date/time must be greater than or equal to the Nbf value. The time is represented as the number of seconds from January 1, 1970 (1970-01-01T0:0:0Z) UTC until the time the token was issued.
oid	Object identifier (ID) of the user object in Azure AD.
sub	Token subject identifier. This is a persistent and immutable identifier for the user that the token describes. Use this value in caching logic.
tid	Tenant identifier (ID) of the Azure AD tenant that issued the token.
unique_name	A unique identifier for that can be displayed to the user. This is usually a user principal name (UPN).
upn	User principal name of the user.
ver	Version. The version of the JWT token, typically 1.0.

Example

The following is a sample response to a request for an access token, when the token request includes an authorization code.

{
  "access_token": " eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1THdqcHdBSk9NOW4tQSJ9.eyJhdWQiOiJodHRwczovL3NlcnZpY2UuY29udG9zby5jb20vIiwiaXNzIjoiaHR0cHM6Ly9zdHMud2luZG93cy5uZXQvN2ZlODE0NDctZGE1Ny00Mzg1LWJlY2ItNmRlNTdmMjE0NzdlLyIsImlhdCI6MTM4ODQ0MDg2MywibmJmIjoxMzg4NDQwODYzLCJleHAiOjEzODg0NDQ3NjMsInZlciI6IjEuMCIsInRpZCI6IjdmZTgxNDQ3LWRhNTctNDM4NS1iZWNiLTZkZTU3ZjIxNDc3ZSIsIm9pZCI6IjY4Mzg5YWUyLTYyZmEtNGIxOC05MWZlLTUzZGQxMDlkNzRmNSIsInVwbiI6ImZyYW5rbUBjb250b3NvLmNvbSIsInVuaXF1ZV9uYW1lIjoiZnJhbmttQGNvbnRvc28uY29tIiwic3ViIjoiZGVOcUlqOUlPRTlQV0pXYkhzZnRYdDJFYWJQVmwwQ2o4UUFtZWZSTFY5OCIsImZhbWlseV9uYW1lIjoiTWlsbGVyIiwiZ2l2ZW5fbmFtZSI6IkZyYW5rIiwiYXBwaWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctODkwYS0yNzRhNzJhNzMwOWUiLCJhcHBpZGFjciI6IjAiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJhY3IiOiIxIn0.JZw8jC0gptZxVC-7l5sFkdnJgP3_tRjeQEPgUn28XctVe3QqmheLZw7QVZDPCyGycDWBaqy7FLpSekET_BftDkewRhyHk9FW_KeEz0ch2c3i08NGNDbr6XYGVayNuSesYk5Aw_p3ICRlUV1bqEwk-Jkzs9EEkQg4hbefqJS6yS1HoV_2EsEhpd_wCQpxK89WPs3hLYZETRJtG5kvCCEOvSHXmDE6eTHGTnEgsIk--UlPe275Dvou4gEAwLofhLDQbMSjnlV5VLsjimNBVcSRFShoxmQwBJR_b2011Y5IuD6St5zPnzruBbZYkGNurQK63TJPWmRd3mbJsGM0mf3CUQ",
  "token_type": "Bearer",
  "expires_in": "3600",
  "expires_on": "1388444763",
  "resource": "https://service.contoso.com/",
  "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4rTfgV29ghDOHRc2B-C_hHeJaJICqjZ3mY2b_YNqmf9SoAylD1PycGCB90xzZeEDg6oBzOIPfYsbDWNf621pKo2Q3GGTHYlmNfwoc-OlrxK69hkha2CF12azM_NYhgO668yfcUl4VBbiSHZyd1NVZG5QTIOcbObu3qnLutbpadZGAxqjIbMkQ2bQS09fTrjMBtDE3D6kSMIodpCecoANon9b0LATkpitimVCrl-NyfN3oyG4ZCWu18M9-vEou4Sq-1oMDzExgAf61noxzkNiaTecM-Ve5cq6wHqYQjfV9DOz4lbceuYCAA",
  "scope": "user_impersonation",
"id_token": " eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctODkwYS0yNzRhNzJhNzMwOWUiLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC83ZmU4MTQ0Ny1kYTU3LTQzODUtYmVjYi02ZGU1N2YyMTQ3N2UvIiwiaWF0IjoxMzg4NDQwODYzLCJuYmYiOjEzODg0NDA4NjMsImV4cCI6MTM4ODQ0NDc2MywidmVyIjoiMS4wIiwidGlkIjoiN2ZlODE0NDctZGE1Ny00Mzg1LWJlY2ItNmRlNTdmMjE0NzdlIiwib2lkIjoiNjgzODlhZTItNjJmYS00YjE4LTkxZmUtNTNkZDEwOWQ3NGY1IiwidXBuIjoiZnJhbmttQGNvbnRvc28uY29tIiwidW5pcXVlX25hbWUiOiJmcmFua21AY29udG9zby5jb20iLCJzdWIiOiJKV3ZZZENXUGhobHBTMVpzZjd5WVV4U2hVd3RVbTV5elBtd18talgzZkhZIiwiZmFtaWx5X25hbWUiOiJNaWxsZXIiLCJnaXZlbl9uYW1lIjoiRnJhbmsifQ.”
}

The JWT token in the value of the id_token parameter can be decoded into the following claims:

{
 "typ": "JWT",
 "alg": "none"
}.
{
 "aud": "2d4d11a2-f814-46a7-890a-274a72a7309e",
 "iss": "https://sts.windows.net/7fe81447-da57-4385-becb-6de57f21477e/",
 "iat": 1388440863,
 "nbf": 1388440863,
 "exp": 1388444763,
 "ver": "1.0",
 "tid": "7fe81447-da57-4385-becb-6de57f21477e",
 "oid": "68389ae2-62fa-4b18-91fe-53dd109d74f5",
 "upn": "frank@contoso.com",
 "unique_name": "frank@contoso.com",
 "sub": "JWvYdCWPhhlpS1Zsf7yYUxShUwtUm5yzPmw_-jX3fHY",
 "family_name": "Miller",
 "given_name": "Frank"
}.

Use the Access Token to Access the Resource

You can use the access token that is returned in the response to authenticate to a protected resources, such as a web API. Typically, the token is presented to the web API in an HTTP request using the Bearer scheme, which is described in RFC 6750. This specification explains how to use bearer tokens in HTTP requests to access protected resources.

When the web API receives and validates the token, it gives the native client application access to the web API.

The following example shows a GET request that passes an access token in the request body. The Authorization header indicates that it is a bearer token, which is valid for anyone who possesses the token.

GET /data HTTP/1.1
Host: service.contoso.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1THdqcHdBSk9NOW4tQSJ9.eyJhdWQiOiJodHRwczovL3NlcnZpY2UuY29udG9zby5jb20vIiwiaXNzIjoiaHR0cHM6Ly9zdHMud2luZG93cy5uZXQvN2ZlODE0NDctZGE1Ny00Mzg1LWJlY2ItNmRlNTdmMjE0NzdlLyIsImlhdCI6MTM4ODQ0MDg2MywibmJmIjoxMzg4NDQwODYzLCJleHAiOjEzODg0NDQ3NjMsInZlciI6IjEuMCIsInRpZCI6IjdmZTgxNDQ3LWRhNTctNDM4NS1iZWNiLTZkZTU3ZjIxNDc3ZSIsIm9pZCI6IjY4Mzg5YWUyLTYyZmEtNGIxOC05MWZlLTUzZGQxMDlkNzRmNSIsInVwbiI6ImZyYW5rbUBjb250b3NvLmNvbSIsInVuaXF1ZV9uYW1lIjoiZnJhbmttQGNvbnRvc28uY29tIiwic3ViIjoiZGVOcUlqOUlPRTlQV0pXYkhzZnRYdDJFYWJQVmwwQ2o4UUFtZWZSTFY5OCIsImZhbWlseV9uYW1lIjoiTWlsbGVyIiwiZ2l2ZW5fbmFtZSI6IkZyYW5rIiwiYXBwaWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctODkwYS0yNzRhNzJhNzMwOWUiLCJhcHBpZGFjciI6IjAiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJhY3IiOiIxIn0.JZw8jC0gptZxVC-7l5sFkdnJgP3_tRjeQEPgUn28XctVe3QqmheLZw7QVZDPCyGycDWBaqy7FLpSekET_BftDkewRhyHk9FW_KeEz0ch2c3i08NGNDbr6XYGVayNuSesYk5Aw_p3ICRlUV1bqEwk-Jkzs9EEkQg4hbefqJS6yS1HoV_2EsEhpd_wCQpxK89WPs3hLYZETRJtG5kvCCEOvSHXmDE6eTHGTnEgsIk--UlPe275Dvou4gEAwLofhLDQbMSjnlV5VLsjimNBVcSRFShoxmQwBJR_b2011Y5IuD6St5zPnzruBbZYkGNurQK63TJPWmRd3mbJsGM0mf3CUQ

Use the Refresh Token to Request a New Access Token

When an access token expires, the native client application can use the refresh token to get a new access token. The lifetime of the refresh token is not provided and varies based on policy settings and the time when the authorization code grant is revoked by Azure AD. The application should expect and handle cases when the request for a new access token fails. In that case, it should return to the code that requests a new access token. For details, see Best Practices for OAuth 2.0 in Azure AD.

Access Token Request with a Refresh Token

To use a refresh token to request a new access token, use an HTTP POST request to the common (tenant-independent) or a tenant-specific Azure AD endpoint.

: https://login.microsoftonline.com/common/oauth2/token
-or-
: https://login.microsoftonline.com/<tenant id>/oauth2/token

Use the following parameters in a token request that includes a refresh token.

Parameter	Description
client_id	[Optional] The client ID of the native client application that is registered in Azure AD. To find the application's client ID, in the Azure Management Portal, click Active Directory, click the directory, click the application, and then click Configure.
client_secret	[Required for confidential clients (websites)] Contains the client password.
grant_type	[Required] Indicates the type of grant being used. In this case, the value must be refresh_token.
refresh_token	[Required] The refresh token that was included in the response that provided the access token.
resource	[Optional] The App ID URI of the web API (secured resource). To find the App ID URI, in the Azure Management Portal, click Active Directory, click the directory, click the application, and then click Configure.

Examples

The following example uses a refresh_token to request a new access token. The POST includes the required grant_type and refresh_token parameters, but none of the optional parameters. Typically, this format is used when the original request specified the resource and there's no need to include it again.

POST common/oauth2/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4rTfgV29ghDOHRc2B-C_hHeJaJICqjZ3mY2b_YNqmf9SoAylD1PycGCB90xzZeEDg6oBzOIPfYsbDWNf621pKo2Q3GGTHYlmNfwoc-OlrxK69hkha2CF12azM_NYhgO668yfcUl4VBbiSHZyd1NVZG5QTIOcbObu3qnLutbpadZGAxqjIbMkQ2bQS09fTrjMBtDE3D6kSMIodpCecoANon9b0LATkpitimVCrl-NyfN3oyG4ZCWu18M9-vEou4Sq-1oMDzExgAf61noxzkNiaTecM-Ve5cq6wHqYQjfV9DOz4lbceuYCAA

The following example shows a request from a confidential client (website). It includes the client_id and client_secret parameters

POST common/oauth2/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token&refresh_token=AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4rTfgV29ghDOHRc2B-C_hHeJaJICqjZ3mY2b_YNqmf9SoAylD1PycGCB90xzZeEDg6oBzOIPfYsbDWNf621pKo2Q3GGTHYlmNfwoc-OlrxK69hkha2CF12azM_NYhgO668yfcUl4VBbiSHZyd1NVZG5QTIOcbObu3qnLutbpadZGAxqjIbMkQ2bQS09fTrjMBtDE3D6kSMIodpCecoANon9b0LATkpitimVCrl-NyfN3oyG4ZCWu18M9-vEou4Sq-1oMDzExgAf61noxzkNiaTecM-Ve5cq6wHqYQjfV9DOz4lbceuYCAA&client_id=f8cf8d0f-9c77-4606-aa05-abcde9526166&client_secret=p@ssw0rd

The following example also uses a refresh token to request an access token. This request includes the resource parameter with a value that indicates the secured resource that the application wants to access.

POST common/oauth2/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4rTfgV29ghDOHRc2B-C_hHeJaJICqjZ3mY2b_YNqmf9SoAylD1PycGCB90xzZeEDg6oBzOIPfYsbDWNf621pKo2Q3GGTHYlmNfwoc-OlrxK69hkha2CF12azM_NYhgO668yfcUl4VBbiSHZyd1NVZG5QTIOcbObu3qnLutbpadZGAxqjIbMkQ2bQS09fTrjMBtDE3D6kSMIodpCecoANon9b0LATkpitimVCrl-NyfN3oyG4ZCWu18M9-vEou4Sq-1oMDzExgAf61noxzkNiaTecM-Ve5cq6wHqYQjfV9DOz4lbceuYCAA&resource=https%3A%2F%2Fservice.contoso.com%2F

Access Token Response with a Refresh Token

A successful response to an access token request that includes a refresh token includes the following parameters.

Parameter	Description
access_token	The new access token that was requested.
expires_in	The remaining lifetime of the token in seconds. A typical value is 3600 (one hour).
expires_on	The date and time on which the token expires. The date is represented as the number of seconds from 1970-01-01T0:0:0Z UTC until the expiration time.
refresh_token	A new OAuth 2.0 refresh_token that can be used to request new access tokens when the one in this response expires.
resource	Identifies the secured resource that the access token can be used to access.
scope	Impersonation permissions granted to the native client application. The default permission is user_impersonation. The owner of the target resource can register alternate values in Azure AD.
token_type	The token type. The only supported value is bearer.

Examples

The following is a sample response to an access token request that includes a refresh token.

{
  "access_token": " eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1THdqcHdBSk9NOW4tQSJ9.eyJhdWQiOiJodHRwczovL3NlcnZpY2UuY29udG9zby5jb20vIiwiaXNzIjoiaHR0cHM6Ly9zdHMud2luZG93cy5uZXQvN2ZlODE0NDctZGE1Ny00Mzg1LWJlY2ItNmRlNTdmMjE0NzdlLyIsImlhdCI6MTM4ODQ0MDg2MywibmJmIjoxMzg4NDQwODYzLCJleHAiOjEzODg0NDQ3NjMsInZlciI6IjEuMCIsInRpZCI6IjdmZTgxNDQ3LWRhNTctNDM4NS1iZWNiLTZkZTU3ZjIxNDc3ZSIsIm9pZCI6IjY4Mzg5YWUyLTYyZmEtNGIxOC05MWZlLTUzZGQxMDlkNzRmNSIsInVwbiI6ImZyYW5rbUBjb250b3NvLmNvbSIsInVuaXF1ZV9uYW1lIjoiZnJhbmttQGNvbnRvc28uY29tIiwic3ViIjoiZGVOcUlqOUlPRTlQV0pXYkhzZnRYdDJFYWJQVmwwQ2o4UUFtZWZSTFY5OCIsImZhbWlseV9uYW1lIjoiTWlsbGVyIiwiZ2l2ZW5fbmFtZSI6IkZyYW5rIiwiYXBwaWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctODkwYS0yNzRhNzJhNzMwOWUiLCJhcHBpZGFjciI6IjAiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJhY3IiOiIxIn0.JZw8jC0gptZxVC-7l5sFkdnJgP3_tRjeQEPgUn28XctVe3QqmheLZw7QVZDPCyGycDWBaqy7FLpSekET_BftDkewRhyHk9FW_KeEz0ch2c3i08NGNDbr6XYGVayNuSesYk5Aw_p3ICRlUV1bqEwk-Jkzs9EEkQg4hbefqJS6yS1HoV_2EsEhpd_wCQpxK89WPs3hLYZETRJtG5kvCCEOvSHXmDE6eTHGTnEgsIk--UlPe275Dvou4gEAwLofhLDQbMSjnlV5VLsjimNBVcSRFShoxmQwBJR_b2011Y5IuD6St5zPnzruBbZYkGNurQK63TJPWmRd3mbJsGM0mf3CUQ",
  "token_type": "Bearer",
  "expires_in": "3600",
  "expires_on": "1388450610",
  "resource": "https://service.contoso.com/",
  "refresh_token": "AwABAAAAv YNqmf9SoAylD1PycGCB90xzZeEDg6oBzOIPfYsbDWNf621pKo2Q3GGTHYlmNfwoc-OlrxK69hkha2CF12azM_NYhgO668yfcUl4VBbiSHZyd1NVZG5QTIOcbObu3qnLutbpadZGAxqjIbMkQ2bQS09fTrjMBtDE3D6kSMIodpCecoANon9b0LATkpitimVCrl PM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4rTfgV29ghDOHRc2B-C_hHeJaJICqjZ3mY2b_YNqmf9SoAylD1PycGCB90xzZeEDg6oBzOIPfYsbDWNf621pKo2Q3GGTHYlmNfwoc-OlrxK69hkha2CF12azM_NYhgO668yfmVCrl-NyfN3oyG4ZCWu18M9-vEou4Sq-1oMDzExgAf61noxzkNiaTecM-Ve5cq6wHqYQjfV9DOz4lbceuYCAA",
  "scope": "user_impersonation"
}

See Also

OAuth 2.0 in Azure AD
Service to Service Calls Using Client Credentials
Error Handling in OAuth 2.0
Best Practices for OAuth 2.0 in Azure AD