SALES: 1-800-867-1380

Refresh Tokens for Multiple Resources

Updated: April 2, 2014

When using the Authorization Code Grant Flow, you can configure the client to call multiple resources. Typically, this would require a call to the authorization endpoint for each target service. To avoid multiple calls and multiple user consent prompts, and reduce the number of refresh tokens the client needs to cache, Azure Active Directory (Azure AD) has implemented multi-resource refresh tokens. This feature allows you to use a single refresh token to request access tokens for multiple resources.

To begin, create the client application and all resource applications and configure the call between the client and all service applications. Then, use the Azure Management Portal to register the application in your Azure AD tenant. For detailed instructions, see Adding, Updating, and Removing an App

If you are building a native client application, use the procedure described in Authorization Code Grant Flow to get an authorization code, and then exchange the authorization code for an access token and a refresh token. Or, if you are building a web service, follow the instructions in Service to Service Calls Using Client Credentials to get an access token and a refresh token.

Use a refresh token to request an access token for any other resource that the client is permitted to call. To do this, set the resource parameter in the request to the targeted resource.

To request an access token to an additional resource, use a refresh token.

When you use a refresh token, the parameter in the POST request are identical to the parameters that you would use to request an access token when an original access token expires. The only difference is that the resource parameter is required.

 

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.

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

[Required] 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.

In the following example, a native client application is using a refresh token to request an access token for the https://service.fabrikam.com/resource web API.

POST common/oauth2/token HTTP/1.1
Host: login.windows.net
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.fabrikam.com%2F

A successful response to an access token request that includes a refresh token includes the following parameters. This response is identical to the response that is sent when you use a refresh token to request an new access token for the same resource.

 

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

Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft