Invoking the Introspection Endpoint for OpenID Connect

The introspection endpoint enables holders of access tokens to request a set of metadata about an access token from the OpenID Connect Provider that issued the access token. The access token must be one that was obtained through OpenID Connect or OAuth authentication.

When a resource service or a client application invokes the introspection endpoint, it must register itself as a normal OAuth 2.0 client to the OpenID Connect server. The registered client metadata must include the attribute introspectTokens = true.

Information that is contained within access tokens that are used in OpenID Connect and OAuth 2.0 is opaque to clients. This can enable protected resources or clients to make authorization decisions based on the metadata that is returned from the OpenID Connect Provider about the access token.

A Liberty profile server with OpenID Connect enabled has access to the OpenID Connect introspection endpoint at the following URL:

https://server.example.com:443/oidc/endpoint/<provider_name>/introspect

In this example, the SSL port of the OP is expected to be 443.

1. Set up client authentication with the client ID and password for a registered OpenID Connect Client in the HTTP Basic Authorization header of a GET or POST request. The client ID and password are encoded using the application/x-www-form-urlencoded encoding algorithm. The encoded client ID is used as the username and the encoded password is used as the password.

2. Include the string value for the access token as a parameter in the GET or POST request to the introspection endpoint.

3. Send the GET or POST request to the introspection endpoint URL.

Results

After completing these steps we have a valid HTTP request that is being sent to the introspection endpoint as shown in the Examples section.

For valid requests, the introspection endpoint returns an HTTP 200 response with a JSON object in application/json format that includes the following information, depending upon whether the access token is active or expired.

When the access token is active, the endpoint returns active:true, as well as the following additional information in the JSON object:

active

Boolean indicator of whether the access token is active.

client_id

Client identifier of the OpenID Connect Client who requested the access token.

sub

Resource owner who authorized the access token.

scope

Space-separated list of scopes that are associated with the access token.

iat

Integer timestamp, measured in seconds since January 1, 1970 UTC, indicating when the access token was issued.

exp

Integer timestamp, measured in seconds since January 1, 1970 UTC, indicating when the access token will expire.

realmName

Realm name of the resource owner.

uniqueSecurityName

Unique security name of the resource owner.

tokenType

Access token type. For OpenID Connect, this value is Bearer.

grant_type

String indicating the type of grant that generated the access token. Possible values are: authorization_code, password, refresh_token, client_credentials, resource_owner, implicit, and urn:ietf:params:oauth:grant-type:jwt-bearer.

If the access token is expired, but the provided authentication is valid, or if the provided access token is of the wrong type, the endpoint returns active:false in the JSON object.

For a client or resource service to perform access token introspection, the client or resource service must register itself as a client to the OpenID Connect provider, and the client metadata must have introspect_tokens set to true.

Example

The following shows examples of an active and expired access token along with a request.

An example request is shown here:

POST /register HTTP/1.1
 Accept: application/x-www-form-urlencoded
 Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3
     token=SOYleDziTitHeKcodp6vqEmRwKPjz3lFZTcsQtVC

An example response for an active access token:

 HTTP/1.1 200 OK
 Content-Type: application/json
 Cache-Control: no-store
{  
   "exp"                : 1415307710,    "realmName"          : "BasicRealm",    "sub"                : "testuser",    "scope"              : "openid scope2 scope1",    "grant_type"         : "authorization_code",    "uniqueSecurityName" : "testuser",    "active"             : true,    "token_type"         : "Bearer",    "client_id"          : "pclient01",    "iat"                : 1415307700
}

Example response for an expired access token:

 HTTP/1.1 200 OK
 Content-Type: application/json
 Cache-Control: no-store
 {
     "active":"false"
 }

Parent topic:

Configure an OpenID Connect Client

Concepts:

OpenID Connect

OAuth

Tasks:

Invoking the Authorization Endpoint for OpenID Connect

Invoking the Token Endpoint for OpenID Connect