OAuth introspection

An Introspection URL implemented to the spec of RFC 7662 allows for information about an access token to be returned. This allows OAuth clients to query a token to identify if the token exists and is valid. Extensions to this endpoint have been made to also include some information about the token, beyond whether the token is valid.

The introspection URL is disabled by default. To enable it, set the advanced configuration oauth20.introspectEndpointEnabled to true.

A usual introspection response for a valid token includes the following values:

{
“active”:true,
“username”:”jessica”,
“client_id”:”yb98la1”,
“scope”:”email profile”,
“iat”: 1487744340,
“exp”: 1487747940
}

active: Signifies this token is valid.
scope: The scope of the access token.
username: The username of the user token was granted by.
client_id: The client this token was granted to.
iat: The UNIX timestamp for when this token was granted.
exp: The UNIX timestamp for when this token will expire.

A usual introspection response for an invalid token includes the following values:

{
"active":false
}

active: Signifies this token is invalid.

The RFC articulates that the introspection endpoint must be authenticated with client credentials. These credentials can be provided as post parameters 'client_id' and 'client_secret', or they can be provided as a Basic Authentication (BA) header. The authentication using BA can occur at the point of contact (reverse proxy) or by the introspection endpoints itself (similar to the token endpoint). The client may also authenticate using an access token issued to this client.

This client authentication is performed in the pre-token mapping rule (with the default rule). This out of the box rule does not allow non-confidential clients to introspect tokens. However, by modification of the rule, non-confidential clients may be able to make use of this endpoint. The RFC articulates security concerns when allowing non-confidential clients to introspect tokens (DOS, crawling the possible token space. See section 4. https://tools.ietf.org/html/rfc7662#section-4). A non-confidential client can provide client credentials using BA or post parameters. When using BA, the credentials should present a password of empty string ("").

The introspection endpoint can allow clients to introspect the tokens of each other. By default, this is not allowed. However, a change to the POST token rule can be made to enable it. See the out of the box rule for details.

URL:

https://<Reverse proxy host/port/junction> /sps/oauth/oauth20/introspect

HTTP Request Example:

POST /mga/sps/oauth/oauth20/introspect HTTP/1.1						
     Host:  server.oauth.com									
     Accept: application/json									
     Content-Type: application/x-www-form-urlencoded					
													
     client_id=yb98la1&client_secret=4531959525657&token=2YotnFZFEjr1zCsicMWpAA

The introspection endpoint supports use of the 'token_type_hint' as per section 2.1 (https://tools.ietf.org/html/rfc7662#section-2.1). This allows an optimization in the time of the token lookup. This does not limit the breadth of the search for the token in the token cache. Any token type will still be found even when its type is not the same as the hint.

For example:

POST /sps/oauth/oauth20/introspect HTTP/1.1
Content-Type: application/x-www-form-urlencoded

token=&client_id=aClient&client_secret=aSecret&token_type_hint=access_token

Valid values for token_type_hint are 'access_token' and 'refresh_token'.

If using custom tokens that are not stored in the token cache, the pre-mapping rule can be used to inform the runtime that the token provided was valid. To do this, add a context attribute with the name 'active' and the type 'urn:ibm:names:ITFIM:oauth:rule:decision'. The response attribute type can also be used. If this parameter is provided, the runtime will do no further work, and the post-rule will be invoked. For example:

stsuu.addContextAttribute(new com.tivoli.am.fim.trustserver.sts.uuser.Attribute("active", 
"urn:ibm:names:ITFIM:oauth:rule:decision", "true"));