Invoke the OAuth Introspection Endpoint¶

The OAuth introspection endpoint is:

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

This guide explains how to invoke the OAuth Introspection Endpoint.

Register a service provider¶

To register your application as a service provider in the MWARE IAM:

1. Log in to the MWARE IAM Management Console using administrator credentials.

2. Go to Main > Identity > Service Providers > Add.

3. Enter a Service Provider Name. Optionally, enter a Description.

4. Click Register.

Configure the service provider¶

Make the following changes to the created service provider.

1. Expand Inbound Authentication Configuration > OAuth/OpenID Connect Configuration and click Configure.

2. 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.

3. Click Add. Note the OAuth Client Key and OAuth Client Secret that appear.

[oauth]
validation_response_subject_identifier_format= "app_configured"

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.

Prerequisites¶

Note the following before you begin.

• Token validation requests sent to the introspection endpoint can be authenticated using basic authentication or client credentials.

  Important

  Basic authentication is enabled by default. However, it is recommended to use client credentials for authenticating to the introspection endpoint as it improves server performance.

  To enable token validation using client credentials, apply the following configurations to the deployment.toml file (stored in the <IS_HOME>/repository/conf directory).

  [[resource.access_control]]
  context="(.*)/oauth2/introspect(.*)"
  http_method = "all"
  secure = true
  allowed_auth_handlers="BasicClientAuthentication"

• For token validation requests that require CLIENT_ID:CLIENT_SECRET, use the client ID and client secret of the OAuth service provider you configured above.

• For token validation requests that require USERNAME:PASSWORD, you can use credentials of any user with /permission/admin/manage/identity/applicationmgt/view permissions. If you want to allow users with other permissions to send token 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 (without scopes)¶

First, you need to get a valid access token as follows:

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

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

You will receive the access token as follows:

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

Get a valid token (with scopes)¶

First, you need to get a valid access token as follows:

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=<scope 1> <scope 2>' https://<IS_HOST>:<IS_PORT>/oauth2/token

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

You will receive the access token as follows:

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

Validate the token¶

You can send a token validation request using one of the following authentication methods:

• Using basic authentication:

  Request Format

  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 Request

  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

  Note that 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).

• Using authentication with client credentials:

  Tip

  Note that authentication using client credentials should be enabled for the server. See the prerequisites for instructions.

  Request Format

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

  ---

  Sample Request

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

You will receive one of the following responses:

• If the access token did not request scopes:

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

• If the access token requested scopes:

  {"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 :

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

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

{'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.

Prerequisites¶

Note the following before you begin.

• Token validation requests sent to the introspection endpoint can be authenticated using basic authentication or client credentials.

  Important

  Basic authentication is enabled by default. However, it is recommended to use client credentials for authenticating to the introspection endpoint as it improves server performance.

  To enable token validation using client credentials, apply the following configurations to the deployment.toml file (stored in the <IS_HOME>/repository/conf directory) and restart the server.

  [[resource.access_control]]
  context="(.*)/oauth2/introspect(.*)"
  http_method = "all"
  secure = true
  allowed_auth_handlers="BasicClientAuthentication"

• For token validation requests that require CLIENT_ID:CLIENT_SECRET, use the client ID and client secret of the OAuth service provider you configured above.

• For token validation requests that require USERNAME:PASSWORD, you can use credentials of any user with /permission/admin/manage/identity/applicationmgt/view permissions. If you want to allow users with other permissions to send token 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 (without scopes)¶

First, you need to get a valid access token as follows:

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>/t/<TENANT_DOMAIN>/oauth2/token

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/t/foo.com/oauth2/token

You will receive the access token as follows:

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

Get a valid token (with scopes)¶

First, you need to get a valid access token as follows:

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>/t/<TENANT_DOMAIN>/oauth2/token

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/t/foo.com/oauth2/token

You will receive the access token as follows:

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

Validate the token¶

You can send a token validation request using one of the following authentication methods:

• Using basic authentication:

  Request Format (method 1)

  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

  ---

  Request Format (method 2)

  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 Request

  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

  Note that 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).

• Using authentication with client credentials:

  Tip

  Note that authentication using client credentials should be enabled for the server. See the prerequisites for instructions.

  Request Format

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

  ---

  Sample Request

  curl -k -u rgfKVdnMQnJSSr_pKFTxj3apiwYa:BRebJ0aqfclQB9v7yZwhj0JfW0ga -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

You will receive one of the following responses:

• If the access token did not request scopes:

  {"active":true,"token_type":"Bearer","exp":1517922556,"iat":1517918956,"client_id":"okaN2IXAsLx5SBH9Los1C6zX1RIa","username":"admin@foo.com”}

• If the access token requested scopes:

  {"scope":"1 test","active":true,"token_type":"Bearer","exp":1517922663,"iat":1517919063,"client_id":"okaN2IXAsLx5SBH9Los1C6zX1RIa","username":"admin@foo.com"}

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:

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

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

{'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.