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
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
Procedure
- 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.
- Include the string value for the access token as a parameter in the GET or POST request to the introspection endpoint.
- Send the GET or POST request to the introspection endpoint URL.
Results
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.
Example
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"
}