Token Exchange Grant Type

The Token Exchange grant type allows interoperability between PaaS/SaaS services and IaaS services by performing two-way conversions between IAM proof-of-possession (PoP) tokens and Identity Cloud Service OAuth tokens. A principal that has an IAM PoP token or an API key is able to make a request to an endpoint that supports only OAuth, without needing any other credentials if already authenticated to OCI.

Two-Legged Flow Examples

Use the following examples to create your Token Exchange grant type requests.

Each of these examples requires a signed request. To learn how to create signature header requests, see Request Signatures.

Request Example: Exchange an API Key for an Identity Cloud Service Access Token

Use the API Key of a User to make a signed request to obtain an access token for the user who owns that API Key.

curl  -X POST -sS https://stripe-base-url/oauth2/v1/token -i 
-H 'date: Wed, 07 Apr 2021 00:32:02 GMT' 
-H 'x-content-sha256: 5AfZSV0021K+QUDAdfV7g4wwqBsF2rgVOQWRMIrTa9Q=' 
-H 'content-type: application/x-www-form-urlencoded;charset=utf-8' 
-H 'content-length: 185' 
-H 'Authorization: Signature version="1",keyId="ocid1.tenancy.oc1..aaaaaaaaelaijxfptpfvis54ivamxvd5zbmlxfhcqp6iu43crzzz4ug7lgjq/ocid1.user.oc1..aaaaaaaameznr4sjrfifpgkqrjebfcgevoun4xcnhclsfkstb6ugqrvgmk3q/0c:a7:46:ce:35:f7:dc:55:ed:7d:e7:aa:f0:6c:c3:a5",algorithm="rsa-sha256",headers="(request-target) date host x-content-sha256 content-type content-length",signature="DJqo66...O0ag=="' 
-d 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange&scope=http://www.ocisampleservice.com/resume&requested_token_type=urn:ietf:params:oauth:token-type:access_token'

Request Example: Exchange a User Principal for an Identity Cloud Service Access Token

Use a User Principal to make a signed request to obtain an access token for that user.

curl  -X POST -sS https://stripe-base-url/oauth2/v1/token -i 
-H 'date: Fri, 26 Feb 2021 23:51:18 GMT' 
-H 'x-content-sha256: n0NyZzoYSrKNC6r6f3mrNxYCtZOuG1zK2TY/r+N676Y=' 
-H 'content-type: application/x-www-form-urlencoded;charset=utf-8' 
-H 'content-length: 163' 
-H 'Authorization: Signature version="1",keyId="ST$eyJraWQ...I8V8g",algorithm="rsa-sha256",headers="(request-target) date host x-content-sha256 content-type content-length",signature="a+aH0b...TLtPA=="' 
-d 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange&scope=http://www.ocisampleservice.com/resume&requested_token_type=urn:ietf:params:oauth:token-type:access_token'

The following additional scopes can also be used:

• offline_access
• urn:opc:resource:consumer:tokengenerator:appid::<appId>
• urn:opc:resource:consumer:<scopeExtension>::<scopeQualifier>

The following is request example using the offline_access scope.

curl  -X POST -sS https://stripe-base-url/oauth2/v1/token -i 
-H 'date: Wed, 12 May 2021 18:58:49 GMT' 
-H 'x-content-sha256: 7zRa1qI4iIQouzn2TCTisZKi1CSoXRDe1pUJ58IFyVk=' 
-H 'content-type: application/x-www-form-urlencoded;charset=utf-8' 
-H 'content-length: 284' 
-H 'Authorization: Signature version="1",keyId="ST$eyJraWQ...8V8g",algorithm="rsa-sha256",headers="(request-target) date host x-content-sha256 content-type content-length",signature="OWC2O...SxQ=="' 
-d 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange&client_id=be3af2a5a7ec4f30a334ei8e88e76540&client_secret=04ba8d34-fa08-47ea-aaca-6979e166813f&scope=http://www.docservice.com/report offline_access&isCLI=true&requested_token_type=urn:ietf:params:oauth:token-type:access_token???

When this scope is included, both an access token and a refresh token are produced. The refresh token format is listed in the response example below.

{
    "access_token": "eyJraWQiO.......Ao8A",
    "token_type": "Bearer",
    "expires_in": 3600
    "refresh_token": "<refresh token>"
}

Request Example: Exchange an Instance Principal (IPST) for an Identity Cloud Service Access Token

Use an Instance Principal to make a signed request to obtain an access token for that instance.

curl  -X POST -sS https://stripe-base-url/oauth2/v1/token -i 
-H 'date: Mon, 10 May 2021 12:07:10 GMT' 
-H 'x-content-sha256: t7NyZzoWSrKNC6r6f3mrNxYCtZOuG1zK2TY/r+N676Y=' 
-H 'content-type: application/x-www-form-urlencoded;charset=utf-8' 
-H 'content-length: 170' 
-H 'Authorization: Signature version="1",keyId="ST$eyJhbGc...ssw5c",algorithm="rsa-sha256",headers="(request-target) date host x-content-sha256 content-type content-length",signature="a+aH0b...TLtPA=="' 
-d 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange&scope=http://www.ocisampleservice.com/resume&requested_token_type=urn:ietf:params:oauth:token-type:access_token'

Request Example: Exchanging Resource Principal (RPST) for an Identity Cloud Service Access Token

Use a Resource Principal to make a signed request to obtain an access token for that resource.

curl  -X POST -sS https://stripe-base-url/oauth2/v1/token -i 
-H 'date: Wed, 12 May 2021 01:17:33 GMT' 
-H 'x-content-sha256: t7NyZzoWSrKNC6r6f3mrNxYCtZOuG1zK2TY/r+N676Y=' 
-H 'content-type: application/x-www-form-urlencoded;charset=utf-8' 
-H 'content-length: 197' 
-H 'Authorization: Signature version="1",keyId="ST$eyJheYa...asi9c",algorithm="rsa-sha256",headers="(request-target) date host x-content-sha256 content-type content-length",signature="a+aH0b...TLtPA=="' 
-d 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange&scope=http://www.ocisampleservice.com/resume&requested_token_type=urn:ietf:params:oauth:token-type:access_token'

Response Example

The following example shows the contents of the response body in JSON format when you use the Token Exchange grant type to obtain an access token for all 2-legged flow requests.

{
    "access_token": "eyJraWQiO.......Ao8A",
    "token_type": "Bearer",
    "expires_in": 3600
}