How to write a Custom Introspection Data Provider — WSO2 Identity Server

Photo by Fotis Fotopoulos on Unsplash

OAuth 2.0 Token Introspection defines a protocol that allows authorized protected resources to query the authorization server to determine the set of metadata for a given token that was presented to them by an OAuth Client. You can refer WSO2 documentation of “Invoke the OAuth Introspection Endpoint” to get more detail on invoking OAuth 2.0 Token Introspection.

Recently, I wrote a Custom Introspection Data provider to inject some claims to introspection response. Let me share my experience in writing a Custom Introspection Data provider and how to try out it.

The following config needs to be added to the deployment.toml file in “<IS_HOME>/repository/conf directory in order to enable the custom introspection data provider.

[oauth.grant_type.uma_ticket]
retrieve_uma_permission_info_through_introspection = true

The following code will guide you on how to write a custom introspection data provider by extending “AbstractIdentityHandler” while implementing the “getIntrospectionData” method in “IntrospectionDataProvider”. With this custom introspection data provider, I have injected “sub” and “iss” values to the introspection response by putting them to the returning introspection data Map. Similarly, you also can inject any required feasible value to the introspection response.

Following is the service component of the custom-introspection-dataprovider OSGI bundle which shows how I activated the custom introspection data provider.

Build your implemented custom-introspection-data provider and add the jar file to <IS_HOME>/respository/components/dropins directory and start the WSO2 identity Server.

Try out

Let’s try out invoking the introspection endpoint with the custom introspection data provider.

First, invoke the token endpoint to get the access token. Following you can find the request to invoke the token endpoint and a sample request for your reference.

For requests that require CLIENT_ID:CLIENT_SECRET, use the client ID and client secret of the OAuth service provider. For more information on creating an OAuth service provider, see Configuring Inbound Authentication for a Service Provider.

Request

curl -v -X POST --basic -u <CLIENT_ID>:<CLIENT_SECRET> -H 'Content-Type: application/x-www-form-urlencoded;charset=UTF-8' -k -d 'grant_type=client_credentials' https://localhost:9443/oauth2/token

Sample cURL

curl -v -X POST --basic -u rgfKVdnMQnJSSr_pKFTxj3apiwYa:BRebJ0aqfclQB9v7yZwhj0JfW0ga -H 'Content-Type: application/x-www-form-urlencoded;charset=UTF-8' -k -d 'grant_type=client_credentials' https://localhost:9443/oauth2/token

Token response for client credential grant type is as follows and copy the access token for the next step.

Response

{"token_type":"Bearer",
 "expires_in":3600,
 "access_token":"fbc4e794-23db-3394-b1e5-f2c3e511d01f"}

Let’s invoke the introspection endpoint. There you have to add the copied access token value to the token. Following you can find the request to invoke the introspection endpoint and a sample CURL request for your reference.

For requests that require USERNAME:PASSWORD, by default you can use credentials of any user with "/permission/admin/manage/identity/applicationmgt/view" permissions.

Request

curl -k -u <USERNAME>:<PASSWORD> -H 'Content-Type: application/x-www-form-urlencoded' -X POST --data 'token=<ACCESS_TOKEN>' https://localhost:9443/oauth2/introspect

Sample cURL

curl -k -u admin:admin -H 'Content-Type: application/x-www-form-urlencoded' -X POST --data 'token=fbc4e794-23db-3394-b1e5-f2c3e511d01f' https://localhost:9443/oauth2/introspect

Following is a sample request that you will receive the custom introspection data provider. There you can see, values for “iss” and “sub” are there in introspection response as we have injected those values through the custom introspection data provider.

Response

{"exp":1464161608,
 "username":"admin@carbon.super",
 "active":true, 
 "token_type":"Bearer",
 "iss":"rgfKVdnMQnJSSr_pKFTxj3apiwYa",
 "sub":"admin",
 "client_id":"rgfKVdnMQnJSSr_pKFTxj3apiwYa",
 "iat":1464158008}

Congratulations !!! Now you know how to inject values to the introspection response through an introspection data provider.