OAuth revocation

The DataPower® Gateway can handle token revocation requests by the OAuth client or the resource owner.

To enable revocation support, you must use the system cache or distributed cache or provide a custom stylesheet or GatewayScript file that defines how to record revocation.

By using the system cache, the DataPower Gateway records the revocation request that it receives in the cache. When the client or the resource owner requests to revoke a token, the DataPower Gateway verifies the token access in the cache and completes the revocation action.
By using the distributed cache, the DataPower Gateway records both the information of tokens when they are issued and the revocation request that the DataPower Gateway receives in the data storage associated with the quota enforcement server. The DataPower Gateway uses this information to verify whether a token is still valid and is not revoked by either the application or the resource owner when there is a revocation request.
By using a custom stylesheet or GatewayScript file, you can define how to persist tokens when they are issued and how to handle a revocation request from either an OAuth client or the resource owner.

The DataPower Gateway supports OAuth revocation by defining revocation grant types in the authorization request.

For an OAuth client, set the revocation grant type in the request to revoke specific access tokens or refresh tokens. Define the following parameters of a client revocation grant type.
- grant_type: urn:ibm:datapower:client:revoke
- client_id: The client ID as defined in the OAuth specification.
- Optional: client_secret: The client secret as defined in the OAuth specification, when the client type is confidential and the client uses client secret for authentication.
- Optional: access_token: The access token to be revoked.
- Optional: refresh_token: The refresh token to be revoked.
For example, the OAuth client makes the following HTTP request to revoke a refresh token.
```
POST /clientrevoke HTTP/1.1
Host: datapower.ibm.example.com
Authorization: Basic c3Bvb24tYXBwbDp4c3hzeHM=
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aibm%3Adatapower%3Aclient%3Arevoke&refresh_token=DA84%2F543254
```
The following excerpt shows a sample response of a successful revocation.
```
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Cache-Control: no-store, no-cache
Pragma: no-cache

{"status", "success"}
```
For a resource owner, set the revocation grant type in the request to revoke all the tokens that the resource owner issued to a specific client. Define the following parameters of a resource owner revocation grant type.
- grant_type: urn:ibm:datapower:owner:revoke
- client_id: The client ID that indicates from which client the resource owner requests to revoke all the tokens.
For example, the resource owner makes the following HTTP request to revoke the authorization to the client spoon-restaurant-app.
```
POST /owner-revoke HTTP/1.1
Host: datapower.ibm.example.com
Authorization: Basic bXV0dDpzcG9vbg==
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aibm%3Adatapower%3Aowner%3Arevoke&client_id=spoon-restuarant-app
```
The following excerpt shows a sample response of a failed revocation.
```
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Cache-Control: no-store, no-cache
Pragma: no-cache

{"status", "failure"}
```

The output of a revocation grant type can be one of the following values.

http 200: success.
http 401: failed client authentication. The client returns a JSON format result, for example, {error, [error_description]}.
http 403: not authorized, for example, the client did not issue the token.
http 400: all other issues.