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.

Before you begin

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.

About this task

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 that are based on the metadata that is returned from the OpenID Connect Provider about the access token.

A Liberty 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
Avoid trouble: If you are using an outbound proxy, note that the OpenID Connect RP does not provide a means to route requests through a proxy host automatically.

If you must use a proxy to access the OpenID Connect Provider (OP), the value that you enter for any OP-related URL property must contain the proxy host and port, not the external OP host and port.

In most cases, you can replace the OP host and port with the proxy host and port. The URL that you enter must be visible to both the RP and client (browser or application). For further guidance on how to determine the correct URL to use, contact your proxy administrator.

In this example, the client expects the SSL port to be set to 443.

Procedure

  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 by 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 you 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.

Note: 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"
 }