The introspection endpoint is defined in the OAuth 2.0 Token Introspection specification (tools.ietf.org/html/rfc7662) and used by a resource server (RS) client to validate an access token or a refresh token prior to granting access to a protected-resources call.
Per specification, this endpoint accepts only the HTTP POST method.
Endpoint: /as/introspect.oauth2
The RS acts in the role of a client for the request/response exchange with the PingFederate
OAuth AS to make the validation call using the following parameters. The required
Content-Type value is application/x-www-form-urlencoded
when transmitting via the HTTP POST method.
Parameter | Description |
---|---|
token (Required) |
The bearer access token or refresh token to be validated. Important:
This is a sensitive parameter. To avoid recording it in web server logs, we recommend to only pass in this parameter (via the HTTP POST method) in the message body, instead of in a query string. |
token_type_hint | A hint about the type of token submitted for validation. PingFederate
supports the following values:
Required only when validating a refresh token. |
Client authentication is not required. In other words, 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. Note that 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 the issuing access token management (ATM) instance is configured 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.
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" }
Note that 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" }
Note that AAA1 and AAA2 are the expanded outcome of AAAGroup.
- Response for a valid refresh token
-
{ "active": true "exp": 1556823764 }
- 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. Alternatively, clients can provide credentials using these request parameters: client_id and client_secret. Important:
This is a sensitive parameter. To avoid recording it in web server logs, we recommend to only pass in this parameter (via the HTTP POST method) in the message body or through the use of the HTTP Basic authentication scheme, instead of in a query string. |
Client certificate | Clients must present their client certificate for mutual TLS authentication. The issuer and the subject DN of the client certificate must match values configured for the clients. |
Private key JWT | Clients must include request parameters
client_assertion_type and
client_assertion in the message body of their requests.
Example:
Note:
For readability, line breaks are inserted and the authentication token is truncated. For more information about the private_key_jwt client authentication method, see Client Authentication in the OpenID Connect specification (openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication) and Using Assertions for Client Authentication in RFC7521 (tools.ietf.org/html/rfc7521#section-4.2). |
None | Clients must pass in the client_id parameter in a query string or the message body to identify themselves. |
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 |
---|---|
access_token_manager_id | The access_token_manager_id value is the instance
ID of the desired ATM instance. When specified, PingFederate uses the
desired ATM instance for the request if it is eligible; otherwise it aborts
the request. Note:
When the access_token_manager_id parameter is specified, PingFederate ignores the aud parameter. |
aud | The aud is the resource URI the client wants to access. The provided value is matched against resource URIs configured in access token management instances. When a match is found, PingFederate uses the corresponding access token management instance for the request if it is eligible; otherwise it aborts the request. |
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 which would be 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 1: 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 2: An exact match is a better match than a partial match
-
Access Token Management instances Resource URIs (configured) ATM1 https://localhost:9031/app1
https://localhost:9031/app2/data
https://app.example.local
ATM2 https://localhost:9031/app1/data
https://localhost:9031/app2/data/get
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, ATM2 is chosen becausehttps://localhost:9031/app1/data
(a resource URI pre-configured for ATM2) is an exact match against the provided URI. - Example 3: A more specific partial match is a better match
- Both
https://localhost:9031/app2/data
(a resource URI for ATM1) andhttps://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, ATM2 is chosen becausehttps://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 (see Configuring an OAuth client).
Once an ATM instance is chosen, PingFederate takes into consideration the per-instance session validation settings and processes the validation request (see Managing session validation settings).