OAuth Token Revocation with WSO2 Identity Server

The OAuth Token Revocation functionality is available with WSO2 Identity Server 4.1.0. The OAuth Token Revocation implementation follows the specification here. There are two endpoints exposed from the token revocation feature.

1. REST endpoint at /oauth2endpoints/revoke

2. SOAP endpoint at /services/OAuthAdminService with operation revokeAuthzForAppsByResourceOwner

The REST endpoint is for OAuth2.0 clients who want to revoke any access granted to them by a resource owner. This could be at the discretion of the resource owner or otherwise. In other words this endpoint is meant for OAuth2.0 clients only, to authenticate themselves using client_id and client_secret and revoke the authorization granted to them. They may use the access token or refresh token for this purpose. Whichever token the client uses the result is the same; the client cannot access the user’s resource again until such time the user explicitly provides his grant by authorizing the client at the OAuth2.0 authorization server.

Following is an example of the request that needs to be sent to the revocation REST endpoint by OAuth2.0 client to revoke a token:

curl -X POST --basic -u "4xTplVAiQEwrBF6wYSW3cpyqYDoa:GREoG5f80kmg7uHNed2YwfJSxlQa" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -k -d "token=d23e96c9bf2818fe5b4db0f8dbe829bb&token_type_hint=access_token" https://localhost:9443/oauth2endpoints/revoke

The token parameter used here can be an access token or refresh token. The token_type_hint parameter is optional. This parameter can take values access_token or refresh_token. The Identity Server will use this parameter to speed up the process of looking up the token by searching first in the set of tokens the client specifies (access_token or refresh_token). If the token is not to be found in the set the client claims it to be in, then the server will look for the token in the other set (refresh_token or access_token).

The SOAP endpoint on the other hand is for the resource owners to directly interact with the Authorization server and revoke authorization grants for applications they previously granted access to, without the OAuth2.0 application/client being an intermediary in the process. The use of this SOAP endpoint is demonstrated by the WSO2 Identity Server’s management console at Configure’ -> My Authorized Apps‘ for resource owners to login and revoke application authorization.

Following is a screen shot of the ‘My Authorized Apps’ page at an instance when the user ‘ResourceOwner’ has granted authorization to the application ‘Playground2.0’ created by user ‘AppDev’.

Application 'Playground2.0' created by user 'AppDev' granted authorization by user 'ResourceOwner'

Application ‘Playground2.0’ created by user ‘AppDev’ granted authorization by user ‘ResourceOwner’

The token revocation end-point also supports CORS (Cross-Origin Resource Sharing) specification and also JSONP (Remote JSON – JSONP).

CORS is supported through CORS-Filter which can be found here. The CORS Filter is designed to be plugged to a webapp using its deployment descriptor (web.xml). Since the OAuth2.0 endpoints in WSO2 Identity Server have been written as JAX-RS endpoints you can add the required CORS configurations to its deployment descriptor. You can find this webapp at <WSO2_IS_HOME>/repository/deployment/server/webapps/oauth2endpoints.war. Rather than editing the web.xml directly in the deployed directory, its easier to copy the oauth2endpoints.war file into another location, edit the web.xml and copy it back into the webapps folder and it will get hot deployed.

Example of a JSONP revocation request:

curl -X POST --basic -u "4xTplVAiQEwrBF6wYSW3cpyqYDoa:GREoG5f80kmg7uHNed2YwfJSxlQa" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -k -d "token=d23e96c9bf2818fe5b4db0f8dbe829bb&token_type_hint=access_token&callback=package.myCallback" https://localhost:9443/oauth2endpoints/revoke

The callback parameter is optional.