Introspection endpoint - PingFederate - 12.1

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.

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 be application/token-introspection+jwt
  Note:

  To receive the token introspection JSON response as a JSON Web Token (JWT), specify the Accept HTTP request header with the value application/token-introspection+jwt.

• For token introspection requests, if the Content-Type response header is present the value must be application/token-introspection+jwt

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
}

Note:

If the refresh token is configured to never expire, the "exp" attribute will not be returned.

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.

...
client_assertion_type=
urn%3Aietf%3Aparams%3Aoauth%
3Aclient-assertion-type%3Ajwt-bearer&
client_assertion=
eyJhbGciOiJSUzI1NiIs...LbSWi1YO-TILOd4L7ZCg&
...

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 or resource) in their requests to the PingFederate OAuth AS.

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.