

Invoke the OAuth Introspection Endpoint¶

The OAuth introspection endpoint is:

https://<IS_HOST>:<IS_PORT>/oauth2/introspect

This page guides you through invoking the OAuth Introspection Endpoint.

Register a service provider¶

You need to register your application as a service provider in WSO2 Identity Server.

Log in to the WSO2 Identity Server Management Console (https://<IS_HOST>:<PORT>/carbon) using administrator credentials (admin:admin).
Navigate to Main > Identity > Service Providers > Add.
Enter a Service Provider Name. Optionally, enter a Description.
Click Register.

Configure the service provider¶

Make the following changes to the created service provider.

Expand Inbound Authentication Configuration > OAuth/OpenID Connect Configuration and click Configure.
Enter the Callback Url.

Note

The Callback Url is the exact location in the service provider's application to which an access token will be sent. This URL should be the URL of the page that the user is redirected to after successful authentication.
Click Add. Note the OAuth Client Key and OAuth Client Secret that appear.

Tip

To configure more advanced configurations, see OAuth/OpenID Connect Configurations.

Info

If subject identifier in the token validation response needs to adhere to the " Use tenant domain in local subject identifier" and " Use user store domain in local subject identifier" configurations in service provider, add the following configuration to the <IS_HOME>/repository/conf/deployment.toml file .

[oauth]
validation_response_subject_identifier_format= "app_configured"

Default value of this property is false.
If the value is false, subject identifier will be set as the fully qualified username.

Invoking the endpoint for the super tenant¶

Use the cURL commands given in the following sections to invoke the OAuth introspection endpoint for the super tenant users.

Tip

For requests that require CLIENT_ID:CLIENT_SECRET, use the client ID and client secret of the OAuth service provider you configured above.
For requests that require USERNAME:PASSWORD by default, you can use credentials of any user with /permission/admin/manage/identity/applicationmgt/view permissions.

To allow users with other permissions to send validation requests, add the permissions to the <IS_HOME>/repository/conf/deployment.toml file as shown below and restart the server.
```
[resource_access_control.introspect]
permissions = ["/permission/admin/manage/identity/applicationmgt/view","/permission/admin/login"]
```

Get a valid token¶

Request

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://<IS_HOST>:<IS_PORT>/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

Response

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

Validate the token¶

Request

Request

curl -k -u <USERNAME>:<PASSWORD> -H 'Content-Type: application/x-www-form-urlencoded' -X POST --data 'token=<ACCESS_TOKEN>' https://<IS_HOST>:<IS_PORT>/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

You can pass the token type as an optional parameter in the request (e.g., token_type_hint=access_token or token_type_hint=refresh_token).

Response

{"exp":1464161608,"username":"[email protected]","active":true,"token_type":"Bearer","client_id":"rgfKVdnMQnJSSr_pKFTxj3apiwYa","iat":1464158008}

Get a valid token with a scope¶

Request

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&scope=test1 test2' https://<IS_HOST>:<IS_PORT>/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&scope=test1 test2' https://localhost:9443/oauth2/token

Response

{"access_token":"34060588-dd4e-36a5-ad93-440cc77a1cfb","scope":"test1 test2","token_type":"Bearer","expires_in":3600}

Validate the token¶

Request

Request

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

Sample cURL

curl -k -u admin:admin -H 'Content-Type: application/x-www-form-urlencoded' -X POST --data 'token=334060588-dd4e-36a5-ad93-440cc77a1cfb' https://localhost:9443/oauth2/introspect

Response

{"exp":1464161560,"username":"[email protected]","scope":"test1 test2","active":true,"token_type":"Bearer","client_id":"rgfKVdnMQnJSSr_pKFTxj3apiwYa","iat":1464157960}

Invalid token¶

If the token that you used is invalid, you get the following response:

{'active':false}

Empty token¶

If you leave the token parameter empty as shown below, you get the following response :

Request

Request

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

Sample cURL

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

Response

{'error': 'Invalid input'}

Invoking the endpoint for tenants¶

Use the following cURL commands given in the following sections to invoke the OAuth introspection endpoint for tenant users.

Tip

For requests that require CLIENT_ID:CLIENT_SECRET, use the client ID and client secret of the OAuth service provider you configured above.
For requests that require [email protected]_DOMAIN:PASSWORD by default, you can use credentials of any user with /permission/admin/manage/identity/applicationmgt/view permissions.

To allow users with other permissions to send validation requests, add the permissions to the <IS_HOME>/repository/conf/deployment.toml file as shown below and restart the server.
```
[resource_access_control.introspect]
permissions = ["/permission/admin/manage/identity/applicationmgt/view","/permission/admin/login"]
```
- Token introspection across tenant domains is disabled by default. To allow cross tenant token validation, add the following configuration to the <IS_HOME>/repository/conf/deployment.toml file and restart the server.
```
[oauth.introspect]
allow_cross_tenant = true
```

Get a valid token¶

Request

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://<IS_HOST>:<IS_PORT>/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

Response

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

Validate the token¶

Request

You can use any of the request formats given below:

Request

curl -k -u <USERNAME>@<TENAND_DOMAIN>:<PASSWORD> -H 'Content-Type: application/x-www-form-urlencoded' -X POST --data 'token=<ACCESS_TOKEN>' https://<IS_HOST>:<IS_PORT>/t/<TENANT_DOMAIN>/oauth2/introspect

Or

Request

curl -v -k -H 'Authorization: Basic <BASE64ENCODED(USERNAME@TENAND_DOMAIN:PASSWORD)>' -H 'Content-Type: application/x-www-form-urlencoded' -X POST --data 'token=<ACCESS_TOKEN>' https://localhost:9443/t/<TENANT_DOMAIN>/oauth2/introspect

You can pass the token type as an optional parameter in the request (e.g., token_type_hint=access_token or token_type_hint=refresh_token).

Sample cURL

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

Response

{"active":true,"token_type":"Bearer","exp":1517922556,"iat":1517918956,"client_id":"okaN2IXAsLx5SBH9Los1C6zX1RIa","username":"[email protected]”}

Get a valid token with a scope¶

Request

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&scope=test1 test2' https://<IS_HOST>:<IS_PORT>/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&scope=test1 test2' https://localhost:9443/oauth2/token

Response

{"access_token":"34060588-dd4e-36a5-ad93-440cc77a1cfb","scope":"test1","token_type":"Bearer","expires_in":3600}

Validate the token¶

Request

You can use any of the request formats given below:

Request

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

Or

Request

curl -v -k -H 'Authorization: Basic <BASE64ENCODED(USERNAME@TENANT_DOMAIN:PASSWORD)>' -H 'Content-Type: application/x-www-form-urlencoded' -X POST --data 'token=<ACCESS_TOKEN>' https://localhost:9443/t/<TENANT_DOMAIN>/oauth2/introspect

Sample cURL

curl -k -u [email protected]:admin -H 'Content-Type: application/x-www-form-urlencoded' -X POST --data 'token=334060588-dd4e-36a5-ad93-440cc77a1cfb' https://localhost:9443/t/foo.com/oauth2/introspect

Response

{"scope":"1 test","active":true,"token_type":"Bearer","exp":1517922663,"iat":1517919063,"client_id":"okaN2IXAsLx5SBH9Los1C6zX1RIa","username":"[email protected]"}

Invalid token¶

If the token that you used is invalid, you get the following response:

Response

{'active':false}

Empty token¶

If you leave the token parameter empty as shown below, you get the following response:

Request

Example:

Request

curl -k -u <USERNAME>@<TENANT_DOMAIN>:<PASSWORD> -H 'Content-Type: application/x-www-form-urlencoded' -X POST --data 'token=' https://<IS_HOST>:<IS_PORT>/t/<TENANT_DOMAIN>/oauth2/introspect

Sample cURL

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

Response

{'error': 'Invalid input'}

The samples given above only demonstrate how to validate a token obtained for the client credentials grant using the introspect endpoint. Similarly, you can invoke introspection endpoint with a token obtained from any other grant type as well.