This documentation is for WSO2 Identity Server 5.4.0 . View documentation for the latest release.

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

The OAuth Introspection endpoint is as follows:

Code Block
https://localhost:9443/oauth2/introspect

...

The states and descriptions of authorization codes and access tokens are as follows.
  • Authorization codes:
    1. ACTIVE - Valid and yet to be exchanged for an access token.
    2. INACTIVE - Invalid and already being exchanged for an access token.
    3. EXPIRED - Invalid as it got expired before being exchanged to an access token. 
  • Access tokens:
    1. ACTIVE - Valid access token. Although the state is ACTIVE, the timestamp calculation may reveal it to be EXPIRED, but this happens only during the first access token request or token validation request after expiration.
    2. INACTIVE - Refreshed using refresh_token grant type before expiration. Also this state is used in cases when users and user stores are deleted, user passwords are updated, etc.
    3. EXPIRED - Invalid and expired access token. Refresh token can still be valid though.
    4. REVOKED - Revoked access token. Refresh token also gets revoked along with access token. Access token could have been in ACTIVE or EXPIRED state while revoking.

Invoking the endpoint

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

Table of Contents
maxLevel5
minLevel5
excludeAuthorization codes|Access tokens

...

WSO2 Identity Server provides a SOAP service to validate the OAuth2 token it has issued, which can be used by the resource server.

Children Display

However from these 2 methods, the recommended approach is to use the REST API given above.

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, uncomment below configuration in <IS_HOME>/repository/conf/identity/identity.xml

file

.

 

Panel
titleRelated Topics

You can also use the SOAP service provided in WSO2 Identity Server to validate an issued OAuth token. However the recommended approach is to use the REST API given above.

To use the SOAP service, see the OAuth Token Validation Using SOAP Service topic
Code Block
languagexml
<Resource context="(.*)/oauth2/introspect(.*)" secured="true" http-method="all">
    <Permissions>/permission/admin/manage/identity/applicationmgt/view</Permissions>
</Resource>
Get a valid token

...

Code Block
languagebash
titleRequest
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
Code Block
languagebash
titleSample 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

...

Code Block
{"token_type":"Bearer","expires_in":3600,"access_token":"fbc4e794-23db-3394-b1e5-f2c3e511d01f"}
Validate the token

...

Code Block
languagebash
titleRequest
curl -k -u <USERNAME>:<PASSWORD> -H 'Content-Type: application/x-www-form-urlencoded' -X POST --data 'token=<ACCESS_TOKEN>' https://localhost:9443/oauth2/introspect
Code Block
languagebash
titleSample 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=bearer).

...

Code Block
{"exp":1464161608,"username":"admin@carbon.super","active":true,"token_type":"Bearer","client_id":"rgfKVdnMQnJSSr_pKFTxj3apiwYa","iat":1464158008}
Get a valid token with a scope

...

Code Block
languagebash
titleRequest
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://localhost:9443/oauth2/token
Code Block
languagebash
titleSample 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

...

Code Block
{"access_token":"34060588-dd4e-36a5-ad93-440cc77a1cfb","scope":"test1 test2","token_type":"Bearer","expires_in":3600}
Validate the token
Request
Code Block
languagebash
titleRequest
curl -k -u <USERNAME>:<PASSWORD> -H 'Content-Type: application/x-www-form-urlencoded' -X POST --data 'token=<ACCESS_TOKEN>' https://localhost:9443/oauth2/introspect
Code Block
languagebash
titleSample 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
Code Block
{"exp":1464161560,"username":"admin@carbon.super","scope":"test1 test2","active":true,"token_type":"Bearer","client_id":"rgfKVdnMQnJSSr_pKFTxj3apiwYa","iat":1464157960}
Invalid token

...

Code Block
languagebash
titleRequest
curl -k -u <USERNAME>:<PASSWORD> -H 'Content-Type: application/x-www-form-urlencoded' -X POST --data 'token=<ACCESS_TOKEN>' https://localhost:9443/oauth2/introspect
Code Block
languagebash
titleSample 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

...

Code Block
{'active':false}
Empty token

...

Code Block
languagebash
titleRequest
curl -k -u <USERNAME>:<PASSWORD> -H 'Content-Type: application/x-www-form-urlencoded' -X POST --data 'token=' https://localhost:9443/oauth2/introspect
Code Block
languagebash
titleSample CURL
 curl -k -u admin:admin -H 'Content-Type: application/x-www-form-urlencoded' -X POST --data 'token=' https://localhost:9443/oauth2/introspect

...

Code Block
{'error': 'Invalid input'}
<BuildSubjectIdentifierFromSPConfig>true</BuildSubjectIdentifierFromSPConfig>

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