Page Comparison

WSO2 Identity Server provides two ways to validate an issued OAuth2 Token:

Child pages (Children Display)

The OAuth Introspection endpoint is as follows:

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

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. This metadata includes whether or not the token is currently active (or if it has expired or otherwise been revoked), what rights of access the token carries (usually conveyed through OAuth 2.0 scopes), and the authorization context in which the token was granted (including who authorized the token and which client it was issued to). Token introspection allows a protected resource to query this information regardless of whether or not it is carried in the token itself, allowing this method to be used along with or independently of structured token values.

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

maxLevel	5
minLevel	5
exclude	Authorization codes\|Access tokens

Note

For requests that require CLIENT_ID:CLIENT_SECRET, use the client Id and client secret of the OAuth application.
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, edit the following property found under the <ResourceAccessControl> tag of the <IS_HOME>/repository/conf/identity/identity.xml file.
Code Block
language xml
<Resource context="(.*)/oauth2/introspect(.*)" secured="true" http-method="all"> <Permissions>/permission/admin/manage/identity/applicationmgt/view</Permissions> </Resource>

Get a valid token

Request

Code Block

language	bash
title	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

Code Block

language	bash
title	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

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

Validate the token

Request

Code Block

language	bash
title	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

Code Block

language	bash
title	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=bearer).

Response

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

Request

Code Block

language	bash
title	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://localhost:9443/oauth2/token

Code Block

language	bash
title	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

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

Validate the token

Request

Code Block

language	bash
title	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

Code Block

language	bash
title	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

Code Block
{"exp":1464161560,"username":"admin@carbon.super","scope":"test1 test2","active":true,"token_type":"Bearer","client_id":"rgfKVdnMQnJSSr_pKFTxj3apiwYa","iat":1464157960}

Invalid token

Request

Code Block

language	bash
title	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

Code Block

language	bash
title	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

Code Block
{'active':false}

Empty token

Request

Code Block

language	bash
title	Request

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

Code Block

language	bash
title	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

Code Block
{'error': 'Invalid input'}

Panel

title	Related 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.

Versions Compared

Old Version 1

New Version 2

Key

Authorization codes:

Access tokens:

Invoking the endpoint

Get a valid token

Validate the token

Get a valid token with a scope

Validate the token

Invalid token

Empty token