This site contains the documentation that is relevant to older WSO2 product versions and offerings.
For the latest WSO2 documentation, visit https://wso2.com/documentation/.
Invoke the OAuth Introspection Endpoint
The OAuth Introspection endpoint is as follows:
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.
Authorization codes:
ACTIVE
- Valid and yet to be exchanged for an access token.INACTIVE
- Invalid and already being exchanged for an access token.EXPIRED
- Invalid as it got expired before being exchanged to an access token.Â
Access tokens:
ACTIVE
- Valid access token. Although the state is ACTIVE, thetimestamp
calculation may reveal it to beEXPIRED
, but this happens only during the first access token request or token validation request after expiration.INACTIVE
- Refreshed usingrefresh_token
grant type before expiration. Also this state is used in cases when users and user stores are deleted, user passwords are updated, etc.EXPIRED
- Invalid and expired access token. Refresh token can still be valid though.REVOKED
- Revoked access token. Refresh token also gets revoked along with access token. Access token could have been inACTIVE
orEXPIRED
state while revoking.
Follow the sections given below to invoke the endpoint:
Invoking the endpoint for the super tenant
- 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. 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.<Resource context="(.*)/oauth2/introspect(.*)" secured="true" http-method="all"> <Permissions>/permission/admin/manage/identity/applicationmgt/view</Permissions> </Resource>
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://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 |
---|---|
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://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 You can pass the token type as an optional parameter in the request (e.g., |
---|---|
Response | {"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 | 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 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://localhost:9443/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":"admin@carbon.super","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://localhost:9443/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
- 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. For requests that require
USERNAME@TENANT_DOMAIN:PASSWORD
, by default you can use credentials of any user with "/permission/admin/manage/identity/applicationmgt/view" permissions.
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://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 |
---|---|
Response | {"token_type":"Bearer","expires_in":3600,"access_token":"fbc4e794-23db-3394-b1e5-f2c3e511d01f"} |
Validate the token
You can pass the token type as an optional parameter in the request (e.g., token_type_hint=bearer
).
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://localhost:9443/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 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":"admin@foo.com”} |
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://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&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://localhost:9443/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 admin@foo.com: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":"admin@foo.com"} |
Invalid token
{'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://localhost:9443/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'} |