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
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
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
-
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
orPOST
request. The client ID and password are encoded by using theapplication/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
orPOST
request to the introspection endpoint. -
Send the
GET
orPOST
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
, andurn: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.
introspect_tokens
set to
true.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"
}