OAuth 2.0 Token Introspection Endpoint (client-centric)

The Token Introspection Endpoint (RFC 7662) allows clients or other entities receiving OAuth 2.0 tokens to determine the validity of an Access Token or Refresh Token. This is necessary in scenarios where the client forwards any token to another party on behalf of the user. Using this feature, that party can verify the validity and some attributes of the provided token.

The RFC does not distinguish between Access Tokens and Refresh Tokens in the context of this endpoint; receiving a successful response therefore doesn't imply the token being an Access Token. It is the callers responsibility to know the type of the token.

First of all, a normal AS setup needs to be configured as documented in OAuth AS configuration - client-centric.

To enable the Token Introspection Endpoint for a specific client, navigate to its Authorization Server Settings and add the Token Introspection Endpoint. The only thing that needs configuring is the access control (supporting Basic Authentication) where a list of username/password combinations can be specified.

If enabled, the endpoint listens in the loginapp under the path <URL of Loginapp>/oauth2-introspection/<URL encoded client id> . Remember to use HTTPS for all calls to this endpoint.

The RFC specifies a list of optional return values in the response.

IAM provides the following attributes in any successful response:

1. active (Boolean indicator of whether or not the presented token is currently active)
2. scope (Scope(s) of the queried token)
3. client_id (Client ID matching the one specified in the endpoint URL)
4. exp (Token expiry date (only if token validity is not set to infinite in the configuration))
5. iat (Timestamp of the moment this token was created)
6. sub (Username of the user owning this token. Notice that this always represents the technical userid and ignores any username transformation in the target application)