Token revocation
In IBM® API Connect, you can revoke or refresh tokens. If necessary, you can also revoke all tokens that are issued to a specific client ID or a resource owner.
Token revocation using an external third party service
This topic describes token revocation using a third party, external service. This option is configured in the Native OAuth provider, using the 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 blocklist (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.
screen. The revocation URL is an endpoint that links to an external service which contains information about access or refresh tokens.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 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:
<?xml version="1.0" encoding="UTF-8"?>
GET <revocationURL> HTTP/1.1
User-Agent: IBM-APIManagement/4.0
Accept: application/xml; text/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 type="access">AAETb2F1dGgtcmV2b2tlLWN1c3RvbfZaRlVbnPSc1...</token>
<token type="refresh">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>
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
<?xmlversion="1.0" encoding="UTF-8"?>
<token>
<token_type>bearer</token_type>
<access_token>AAENYy1hbGwtcmVmcmVzaOfNeQKX8ZeojsBY9v0FI7/OerQvzKHq...</access_token>
<expires_in>3600</expires_in>
<scope>3600</scope>
<resource-owner>alice</resource-owner>
<client_id>83d9cdcd-ba72-4d00-abae-005da8da5fb1</client_id>
</token>
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>GET HTTP/1.1
refresh-token: AAETb2F1dGgtcmV2b2tlLWN1c3RvbfZaRlVbnPSc1
client-id: 760d75a2-44b1-4485-8c6f-0d264fcf7398
resource-owner: alice
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
Cache-Control: public, max-age=120
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>
- In the previous example, there are no entries older than one month in the response (the maximum life of a refresh token).
- Each response is cached for up to two minutes according to response's directive.
- The
before
attribute uses thexs:dateTime
syntax.