The token endpoint is defined in the the OAuth 2.0 Authorization Framework (tools.ietf.org/html/rfc6749#section-3.2) and used by the client to obtain an access token and possibly a refresh token by presenting its authorization grant. The token endpoint is used with every authorization grant except for the Implicit grant type (since an access token is issued directly from the authorization endpoint).

Note:

Per specification, this endpoint accepts only the HTTP POST method.

Endpoint: /as/token.oauth2

Parameters vary depending on the grant type (see OAuth grant type parameters). The required Content-Type value is application/x-www-form-urlencoded.

Like other OAuth 2.0 endpoints, the token endpoint is accessible at the base URL and any configured virtual host names.

If the Token Endpoint Base URL field is configured on the OAuth Server > Authorization Settings screen, the token endpoint is also accessible at such location.

For example, if the base URL is https://www.example.com:9031 and the Token Endpoint Base URL field value is https://www.example.local:9031, the token endpoints are accessible at the following locations:

  • https://www.example.com:9031/as/token.oauth2, and
  • https://www.example.local:9031/as/token.oauth2

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.
client_assertion_type
The value describes the format of the assertion as defined by the authorization server. For the private_key_jwt client authentication method, the value is urn:ietf:params:oauth:client-assertion-type:jwt-bearer.
client_assertion
The value is the authentication token.

Example:

...
client_assertion_type=
urn%3Aietf%3Aparams%3Aoauth%
3Aclient-assertion-type%3Ajwt-bearer&
client_assertion=
eyJhbGciOiJSUzI1NiIs...LbSWi1YO-TILOd4L7ZCg&
...
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 because https://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) 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, ATM2 is chosen because https://localhost:9031/app2/data/get matches more specifically against the provided URI.