Wednesday, October 8, 2014

OAuth 2.0 Chain Grant Type Profile

Once the audience restriction is enforced on OAuth tokens, they can only be used against the intended audience. You can access an API with an access token that has an audience restriction corresponding to that API. If this API wants to talk to another protected API to form the response to the client, the first API must authenticate to the second API. When it does so, the first API can’t just pass the access token it received initially from the client. That will fail the audience-restriction validation at the second API.

The audience (aud) parameter is defined in the OAuth 2.0: Audience Information Internet draft available at This is a new parameter introduced into the OAuth token-request flow and is independent of the token type. 

The Chain Grant Type OAuth 2.0 profile defines a standard way to address this concern. As shown in the above figure, according to the OAuth Chain Grant Type profile, the API hosted in the first resource server must talk to the authorization server and exchange the OAuth access token it received from the client for a new one that can be used to talk to the other API hosted in the second resource server.

The Chain Grant Type for OAuth 2.0 profile is available at 

The chain grant type request must be generated from the first resource server to the authorization server. The value of the grant type must be set to and should include the OAuth access token received from the client. The scope parameter should express the required scopes for the second resource in space-delimited strings. Ideally, the scope should be the same as or a subset of the scopes associated with original access token. If there is any difference, then the authorization server can decide whether to issue an access token. This decision can be based on an out-of-band agreement with the resource owner:

POST /token HTTP/1.1 
Content-Type: application/x-www-form-urlencoded 


This returns the following JSON response. The response includes an access token with a limited lifetime, but it should not have a refresh token. To get a new access token, the first resource server once again must present the original access token:

HTTP/1.1 200 OK 
Content-Type: application/json;charset=UTF-8 
Cache-Control: no-store 
Pragma: no-cache 

{ "access_token":"2YotnFZFEjr1zCsicMWpAA", "token_type":"Bearer", "expires_in":1800, } 

The first resource server can use the access token from this response to talk to the second resource server. Then the second resource server talks to the authorization server to validate the access token.

More details and the applications of the OAuth 2.0 Chain Grant Type Profile are covered in my book Advanced API Security