Introspection endpoint
A resource server (RS) client uses the introspection endpoint to validate an access token or a refresh token prior to granting access to a protected-resources call.
The OAuth 2.0 Token Introspection documentation defines the introspection endpoint.
This endpoint accepts only the HTTP POST method. |
Endpoint: /as/introspect.oauth2
When transmitting through the HTTP POST method, the required Content-Type
value is application/x-www-form-urlencoded
. The RS acts in the role of a client for the request/response exchange with the PingFederate OAuth AS. The validation call is made using the following parameters.
Parameter | Description | ||
---|---|---|---|
(Required) |
The bearer access token or refresh token to be validated.
|
||
|
A hint about the type of token submitted for validation. PingFederate supports values of Required only when validating a refresh token. |
Client authentication is not required; when creating a client for the sole purpose of validating access tokens and refresh tokens, the Client Secret field is optional.
The response is in a JSON structure with a list of name-to-value elements. If a token is valid, the OAuth AS returns to the client a JSON object with the following elements:
-
An
"active": true
element to indicate the token is valid. This is also the only element returned by the OAuth AS for a valid refresh token. -
A
client_id
element to indicate the client identifier of the client to whom the grant was made. -
A
scope
element, if the scope is greater than the default implied scope, indicating the approved scope of the grant. If you configured the issuing access token management (ATM) instance to expand scope groups, the response includes the corresponding sub scopes instead of the scope groups. -
An
exp
element indicates the token is valid until the number of seconds since January 1, 1970 UTC (epoch time). -
Other elements from the access token.
-
For token introspection requests, if the
Accept
HTTP request header is present the value must beapplication/token-introspection+jwt
To receive the token introspection JSON response as a JSON Web Token (JWT), specify the
Accept
HTTP request header with the valueapplication/token-introspection+jwt
. -
For token introspection requests, if the
Content-Type
response header is present the value must beapplication/token-introspection+jwt
The response includes the |
- A sample JSON response for a valid access token when a JWT header is present on token introspection requests
{
"typ": "token-introspection+jwt",
"alg": "RS256",
"kid": "wG6D"
}
- A sample JSON response for a valid access token. If the JWT Accept header is specified in the request, the JSON will be returned as a JSON web token (JWT).
{
"iss":"https://as.example.com/",
"aud":"https://rs.example.com/resource",
"iat":1514797892,
"token_introspection":
{
"active":true,
"iss":"https://as.example.com/",
"aud":"https://rs.example.com/resource",
"iat":1514797822,
"exp":1514797942,
"client_id":"paiB2goo0a",
"scope":"read write dolphin",
"sub":"Z5O3upPC88QrAjx00dis",
"birthdate":"1982-02-01",
"given_name":"John",
"family_name":"Doe",
"jti":"t1FoCCaZd4Xv4ORJUWVUeTZfsKhW30CQCrWDDjwXy6w"
}
}
If a token is invalid, the OAuth AS returns \{"active": false}
to the client.
- A sample response for a valid access token when scope group expansion is disabled (the default)
{
"scope": "openid AAAGroup",
"active": true,
"OrgName": "Ping Identity Corporation",
"token_type": "Bearer",
"exp": 1556823489,
"client_id": "ac_oic_client"
}
AAAGroup
is a scope group.
- A sample response for a valid access token when scope group expansion is enabled
{
"scope": "openid AAA1 AAA2",
"active": true,
"OrgName": "Ping Identity Corporation",
"token_type": "Bearer",
"exp": 1556823764,
"client_id": "ac_oic_client"
}
AAA1
and AAA2
are the expanded outcome of AAAGroup
.
- Response for a valid refresh token
{
"active": true
"exp": 1556823764
}
If the refresh token is configured to never expire, the |
- Response for an invalid token
{"active":false}
OAuth client identification and authentication
The authentication requirement of this endpoint depends on the client authentication method configured for the clients.
Authentication method | Parameters | ||
---|---|---|---|
Client secret |
Clients can present their client identifier and client secret using the HTTP Basic authentication scheme, where the client identifier is the username, and the client secret is the password. Clients can provide credentials using the request parameters
|
||
Client certificate |
Clients must present their client certificate for mutual TLS authentication. The issuer and the subject distinguished name (DN) of the client certificate must match values configured for the clients. |
||
Private key JWT or Client Secret JWT |
Clients must include request parameters
Example ... client_assertion_type= urn%3Aietf%3Aparams%3Aoauth% 3Aclient-assertion-type%3Ajwt-bearer& client_assertion= eyJhbGciOiJSUzI1NiIs...LbSWi1YO-TILOd4L7ZCg& ...
For more information about the private_key_jwt and client_secret_jwt client authentication methods, see Client Authentication and Using Assertions for Client Authentication. |
||
None |
Clients must pass in the |
OAuth access token management parameters
PingFederate supports multiple access token management (ATM) instances. Clients can specify an ATM instance by providing the ATM ID (access_token_manager_id
) or a resource URI (aud
) in their requests to the PingFederate OAuth AS.
Parameter | Description | ||
---|---|---|---|
|
The
|
||
|
The |
A match can be an exact match or a partial match where the provided URI has the same scheme and authority parts and a more specific path contained within the path of the pre-configured resource URI. PingFederate takes an exact match over a partial match. If there are multiple partial matches, PingFederate takes the partial match where the provided URI matches more specifically against the pre-configured resource URI.
Example
A partial match
A resource URI of https://app.example.local
is a partial match for the following provided URIs:
-
https://app.example.local/file1.ext
-
https://app.example.local/path/file2.ext
-
https://app.example.local/path/more
Example
An exact match is a better match than a partial match
Access Token Management instances | Resource URIs (configured) |
---|---|
ATM1 |
|
ATM2 |
|
https://localhost:9031/app1
(a resource URI pre-configured for ATM1) is a partial match for https://localhost:9031/app1/data (the provided URI). However, PingFederate chooses ATM2 because https://localhost:9031/app1/data
(a resource URI pre-configured for ATM2) is an exact match against the provided URI.
Example
A more specific partial match is a better match
Both https://localhost:9031/app2/data
(a resource URI for ATM1) and https://localhost:9031/app2/data/get
(a resource URI for ATM2) are partial matches for https://localhost:9031/app2/data/get/sample (the provided URI). However, PingFederate chooses ATM2 because https://localhost:9031/app2/data/get
matches more specifically against the provided URI.
- Validate against all eligible ATM instances
-
If multiple ATM instances are eligible, the configuration of the RS client determines whether it must specify the desired ATM instance in its token validation requests. For more information, see Configuring OAuth clients.
After an ATM instance is chosen, PingFederate considers the per-instance session validation settings and processes the validation request. For more information, see Managing session validation settings.