Refresh Tokens for Multiple Resources

Article
01/06/2016

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.

Register the Application in Azure AD

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 to register the application in your Azure AD tenant. For detailed instructions, see Adding, Updating, and Removing an App

Get an Access Token and Refresh Token

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.

Request Another Access 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.

Additional Access Token Request with a Refresh Token

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, 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, 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

Additional Access Token Response with a Refresh Token

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"
}