OAuth revocation URL

In IBM® API Connect, you use an OAuth revocation URL to revoke or refresh specific access tokens. If necessary, you can also revoke all tokens that are issued to a specific client ID or a resource owner.

Token revocation

An OAuth revocation URL provides a link to an external service that contains information about access or refresh tokens. API Connect is involved in the initial creation and validation of tokens. When an OAuth revocation URL is present, API Connect calls the URL to determine if the associated token can be trusted. The token server then checks a token blacklist (a data store of inactive tokens) to ensure that the token is still valid. If the token is still valid, API Connect continues the processing.

You can also use DataPower® gateway distributed cache support. For more information, see: Using Revocation with API Connect.

Examples

A number of revocation examples follow. The first shows a sample fetch request and the response from a remote revocation URL.

GET request and response

In an access code flow, when exchanging the temporary authorization code for an access token, API Connect sends a GET request to the Revocation URL to determine if the temporary authorization code is valid, and (or) whether it has been used previously:

GET <revocationURL> HTTP/1.1
client-id: e515f992-cea3-4ff5-936e-39ec7fe80a40
resource-owner: alice
code: AAJgZEEoYF3el5xjZ_IUp_k6Q...
Cache-Control: no-transform
Host: token-mgmtsrv:10443

If the code is not in use, and therefore the request is valid, the OAuth revocation URL records the code and returns HTTP 200. If the OAuth revocation URL returns any response other than HTTP 200, the DataPower gateway service considers the request as failed and does not issue an access token. Possible reasons for failure include determining that the authorization code was previously used or could not be recorded by the revocation endpoint.

The maximum authorization code lifetime is 10 minutes.

In this example, an API Gateway server issues a GET request to the Revocation URL and receives a result. It shows that different resource owners (Laura and Emily) can revoke all tokens when using the same application (client ID).

Request:

GET <revocationURL> HTTP/1.1
Accept: application/xml

Response:

<?xml version="1.0" encoding="UTF-8"?>
<oauth-revocation>

<!--
Access Tokens and/or Refresh Tokens that are revoked can be individually listed.
To keep this list small, please only include access tokens and refresh tokens that are valid.
For access tokens, any token older than 20 minutes is no longer valid.
For refresh tokens, any token older than 44700 minutes is no longer valid.
-->

<token>AAETb2F1dGgtcmV2b2tlLWN1c3RvbfZaRlVbnPSc1...</token>
<token>fZaRlVbnPSc1UGTjCRdq4mPbOosD2+aZIKbJ6bTeW...</token>

<!--
If a resource owner has revoked all tokens issued to a given application, please
list them as shown here. 
-->

<resource-owner client-id="760d75a2-44b1-4485-8c6f-0d264fcf7398">laura</resource-owner>
<resource-owner client-id="760d75a2-44b1-4485-8c6f-0d264fcf7398">emily</resource-owner>

</oauth-revocation>

The revocation URL can respond with the access and refresh tokens that are to be revoked, or any resource owners for which all tokens are to be revoked.

POST request and response

The next example shows a post request and response.

Request:

POST <revocationURL> HTTP/1.1
User-Agent: IBM-APIManagement/4.0
Content-Type: application/xml
X-Global-Transaction-ID: d37f0b165ce9273e132592f3
X-Transaction-ID: 402837825
Content-Length: 348
Host: token-endpoint:2775

<?xmlversion="1.0" encoding="UTF-8"?>
<token>
   <token_type>bearer</token_type>
   <access_token>AAENYy1hbGwtcmVmcmVzaOfNeQKX8ZeojsBY9v0FI7/OerQvzKHq...</access_token>
   <expires_in>3600</expires_in>
   <refresh_token>AAJnzJY3_EiHPDS6MVkcLV0ST9t5O_vq2I9VUrc_BEZG3qBgglITWOMysig-1ORdc9DSjctGgcIM_bGNqOadTLQ-</refresh_token>
   <refresh_token_expires_in>2682000</refresh_token_expires_in>
   <scope>scope1</scope>
   <resource-owner>alice</resource-owner>
   <client_id>83d9cdcd-ba72-4d00-abae-005da8da5fb1</client_id>
</token>

The refresh_token and refresh_token_expires_in elements are required only if the refresh token is present. For the Access code grant type, a code parameter will be present.

Response:

HTTP/1.1 200 OK

Provide token information on revocation request

In this example, the application calls an API and passes a bearer token. In response, the Gateway fetches the revocation URL and provides information on the token being verified.

Gateway:

GET <revocationURL> HTTP/1.1 
access-token: AAETb2F1dGgtcmV2b2tlLWN1c3RvbfZaRlVbnPSc1
client-id: 760d75a2-44b1-4485-8c6f-0d264fcf7398
resource-owner: alice

Alternatively, the same process occurs when using a refresh token to issue a new access token. The application sends a refresh request to the token service. The Gateway then fetches the revocation URL, providing information on the refresh token being verified.

Gateway:

GET <revocationURL> HTTP/1.1 
refresh-token: AAETb2F1dGgtcmV2b2tlLWN1c3RvbfZaRlVbnPSc1
client-id: 760d75a2-44b1-4485-8c6f-0d264fcf7398 
resource-owner: alice

Note: If you are using a third party OAuth provider then, for API Calls with bearer tokens, when Introspect URL is enabled on the API, the revocation URL is not applicable. Instead, the third party endpoint must validate the token and also check for revocation before returning a

200
OK

response to the Gateway.

Revoking tokens issued to Alice up to and including a specific date

On May 1st, Alice loses her phone and needs to reset her password. As a result, the token provider wants to revoke every token issued before Alice lost her phone. In this example, the Gateway sends a GET request to the revocation service. The revocation service replies confirming revocation of the specified tokens.

Gateway:

GET <revocationURL> HTTP/1.1 
access-token: AAETb2F1dGgtcmV2b2tlLWN1c3RvbfZaRlVbnPSc1 
client-id: 760d75a2-44b1-4485-8c6f-0d264fcf7398 
resource-owner: alice

Revocation Service:

<?xml version="1.0" encoding="UTF-8"?>
<oauth-revocation>
  <resource-owner before="2015-05-01T09:30:10Z">alice</resource-owner>
</oauth-revocation>

Revoking all tokens issued up to and including a specific date

Under certain catastrophic conditions, you may need to revoke all tokens issued up to and including a specific date, for example, May 1st. In this example, the Gateway sends a GET request to the revocation service. The revocation service replies confirming revocation of the specified tokens.

Gateway:

GET <revocationURL> HTTP/1.1 
access-token: AAETb2F1dGgtcmV2b2tlLWN1c3RvbfZaRlVbnPSc1
client-id: 760d75a2-44b1-4485-8c6f-0d264fcf7398
resource-owner: alice

Revocation Service:

<?xml version="1.0" encoding="UTF-8"?>
<oauth-revocation>
  <everytoken before="2015-05-01T09:30:10Z" />
</oauth-revocation>

Putting it all together

The following shows the examples contained in this topic executed in a single action:

Gateway:

GET <revocationURL> HTTP/1.1 
access-token: AAETb2F1dGgtcmV2b2tlLWN1c3RvbfZaRlVbnPSc1
client-id: 760d75a2-44b1-4485-8c6f-0d264fcf7398
resource-owner: alice

Revocation Service:

HTTP/1.1 200 OK
Content-Type: application/xml
Date: Fri, 08 May 2015 21:49:03 GMT


<?xml version-"1.0" encoding="UTF-8"?>
<oauth-revocation>
  <resource-owner before="2015-04-08T09:30:10Z">mary</resource-owner>
  <resource-owner before="2015-04-12T09:30:10Z">john</resource-owner>
  <resource-owner before="2015-04-13T09:30:10Z">kevin</resource-owner>  
  <resource-owner before="2015-04-01T09:30:10Z">alice</resource-owner>
</oauth-revocation>

Note:

In the previous example, there are no entries older than one month in the response (the maximum life of a refresh token).
The before attribute uses the xs:dateTime syntax.