Other parameters accepted by the /as/token.oauth2 endpoint vary by the grant type being presented. They also include both OAuth-defined standard parameters and parameters proprietary to PingFederate. The grant type of the access token request is indicated by the following parameter:

Parameter Description
grant_type

(Required)

Indicates the type of grant being presented in exchange for an access token and possibly a refresh token. The value is an extensibility mechanism of the OAuth 2.0 specification. PingFederate supports these values:
  • authorization_code
  • refresh_token
  • password
  • client_credentials
  • urn:openid:params:grant-type:ciba
  • urn:ietf:params:oauth:grant-type:device_code
  • urn:ietf:params:oauth:grant-type:jwt-bearer
  • urn:ietf:params:oauth:grant-type:saml2-bearer
  • urn:ietf:params:oauth:grant-type:token-exchange
  • urn:pingidentity.com:oauth2:grant_type:validate_bearer
Note:

Further parameters associated with each grant type are defined in the following sections.

Authorization code grant type

These parameters apply when the grant_type parameter for /as/token.oauth2 is set to authorization_code.

Parameter Description
code

(Required)

The authorization code received from the authorization server during the redirect interaction at the authorization endpoint when the response_type parameter is code.
code_verifier Required if the authorization request was sent with a code_challenge parameter to reduce the risk of code interception attack.

Based on the code_challenge_method parameter value (if provided in the request for the authorization code in the first place), PingFederate OAuth AS validates the code_verifier parameter value against that of the code_challenge value. If the validation returns no error, PingFederate OAuth AS returns an access token (provided that there is no other error condition); otherwise it returns an error to the client.

For more information about the code_challenge parameter, the code_challenge_method parameter, and the support for the Proof Key for Code Exchange (PKCE) by OAuth Public Clients specification (tools.ietf.org/html/rfc7636), see Authorization endpoint.

redirect_uri This parameter is required if the redirect_uri parameter was included in the authorization request that resulted in the issuance of the code (see Authorization endpoint). The value here must match the authorization-request value, if applicable.

The parameter is also required for clients with multiple redirection URIs or one redirection URI that uses wildcards.

The parameter is optional for clients with only one specific redirection URI.

scope

(Optional)

The scope of the access request expressed as a list of space-delimited, case-sensitive strings. The requested scope must be equal to or less than the scope originally authorized. If omitted, the scope is treated as equal to the scope originally authorized.

Scope values are globally defined on the OAuth Server > Scope Management screen. Scopes can also be constrained on a client-to-client basis. For detailed information about scopes, see Scopes and scope management.

Refresh token grant type

These parameters apply when the grant_type parameter for /as/token.oauth2 is set to refresh_token.

Parameter Description
refresh_token

(Required)

The refresh token issued to the client during a previous access-token request.
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.

scope The scope of the access request expressed as a list of space-delimited, case-sensitive strings. The requested scope must be equal to or less than the scope originally granted. If omitted, the scope is treated as equal to the original set.

Scope values are globally defined on the OAuth Server > Scope Management screen. Scopes can also be constrained on a client-to-client basis. For detailed information about scopes, see Scopes and scope management.

Resource owner password credentials grant type

These parameters apply when the grant_type parameter for /as/token.oauth2 is set to password.

Parameter Description
username

(Required)

The username, encoded as UTF-8.
password

(Required)

The password, encoded as UTF-8.
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.

scope The scope of the access request expressed as a list of space-delimited, case-sensitive strings.

Scope values are globally defined on the OAuth Server > Scope Management screen. Scopes can also be constrained on a client-to-client basis. For detailed information about scopes, see Scopes and scope management.

validator_id A PingFederate OAuth AS parameter indicating the instance ID of the password credential validator to be used to check the username and password (and the associated attribute mapping into the USER_KEY of the persistent grant). If multiple validator instances are configured and mapped and no validator_id parameter is provided, each instance will be tried sequentially until one succeeds or they all fail.

When a token request triggers an invalid_grant error because the corresponding LDAP Username Password Credential Validator instance returns an authentication error, PingFederate includes the relevant message in the error response; for example:

{
  "error":"invalid_grant",
  "error_description":"We didn't recognize the username or password you entered. Please try again."
}
The error description varies based on the error condition detected by the LDAP Username PCV. OAuth-client developers may create custom experiences based on the error messages.
Tip:

These customizable messages are stored in the PingFederate message file, pingfederate-messages.properties, located in the <pf_install>/pingfederate/server/default/conf/language-packs directory.

As needed, you may localize these messages by using the PingFederate localization framework for an international audience (see Localizing messages for end users).

Note that the client_id parameter is not required when the Allow unidentified clients to make resource owner password credentials grants check box is selected on the OAuth Server > Authorization Server Settings screen.

Client credentials grant type

The following parameters applies when the grant_type parameter for /as/token.oauth2 is set to client_credentials.

Parameter Description
scope The scope of the access request expressed as a list of space-delimited, case-sensitive strings.

Scope values are globally defined on the OAuth Server > Scope Management screen. Scopes can also be constrained on a client-to-client basis. For detailed information about scopes, see Scopes and scope management.

Client-initiated backchannel authentication (CIBA)

The following parameter applies when the grant_type parameter for /as/token.oauth2 is set to urn:openid:params:grant-type:ciba.

Parameter Description
auth_req_id The unique identifier to identify the authentication request.
Sample request
POST /as/token.oauth2 HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: www.example.com
...

grant_type=urn%3Aopenid%3Aparams%3Agrant-type%3Aciba&client_id=myCibaApp&auth_req_id=yQn...1Vw

Note that the auth_req_id parameter value in the sample is truncated for readability.

Device authorization grant type

The following parameter applies when the grant_type parameter for /as/token.oauth2 is set to urn:ietf:params:oauth:grant-type:device_code.

The OAuth 2.0 Device Authorization Grant specification defines the process that allows a user to grant authorization to a device using a browser on a second device, such as a smartphone or a computer. For more information, see Device authorization grant.

Parameter Description
device_code

(Required)

The device code found in the device authorization response.

JWT Bearer Token grant type

These parameters apply when the grant_type parameter for /as/token.oauth2 is set to urn:ietf:params:oauth:grant-type:jwt-bearer.

Parameter Description
assertion

(Required)

A JSON Web Token (JWT), as defined in RFC7523, section 2.1 (tools.ietf.org/html/rfc7523#section-2.1).
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.

scope The scope of the access request expressed as a list of space-delimited, case-sensitive strings.

Scope values are globally defined on the OAuth Server > Scope Management screen. Scopes can also be constrained on a client-to-client basis. For detailed information about scopes, see Scopes and scope management.

Note that the client_id parameter is not required when the Allow unidentified clients to request extension grants check box is selected on the OAuth Server > Authorization Server Settings screen.

SAML 2.0 Bearer Assertion grant type

These parameters apply when the grant_type parameter for /as/token.oauth2 is set to urn:ietf:params:oauth:grant-type:saml2-bearer.

Parameter Description
assertion

(Required)

A single SAML 2.0 assertion, which must be encoded using base64url, as described in RFC4648, section 5 (tools.ietf.org/html/rfc4648#section-5).
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.

scope The scope of the access request expressed as a list of space-delimited, case-sensitive strings.

Scope values are globally defined on the OAuth Server > Scope Management screen. Scopes can also be constrained on a client-to-client basis. For detailed information about scopes, see Scopes and scope management.

Note that the client_id parameter is not required when the Allow unidentified clients to request extension grants check box is selected on the OAuth Server > Authorization Server Settings screen.

Token exchange grant type

The following parameters apply when the grant_type parameter for /as/token.oauth2 is set to urn:ietf:params:oauth:grant-type:token_exchange.

Parameter Description
resource An absolute URI that indicates the target service or resource where the client will use the requested security token. This information lets the authorization server apply the appropriate policy for the target. For example, the authorization server can ensure that the token it issues has the type, content, and encryption that the target requires. If the issued token will be used at multiple targets, multiple resource parameters can be used.
audience The logical name of the target where the client will use the requested security token. This serves a purpose like the resource parameter. To interpret the audience, the value must be something that both the client and the authorization server understand. The value must be unique within the authorization server. If the issued token will be used at multiple targets, multiple audience parameters can be used. When indicating multiple targets, audience and resource parameters can be used together.
scope The scope of the access request expressed as a list of space-delimited, case-sensitive strings.

Scope values are globally defined on the OAuth Server > Scope Management screen. Scopes can also be constrained on a client-to-client basis. For detailed information about scopes, see Scopes and scope management.

requested_token_type An identifier for the type of the requested security token. If the requested type is not specified, the authorization server can determine which type is required by the target that the resource or audience parameter identifies.
subject_token

(Required)

A security token that represents the identity of the party on behalf of whom the request is being made. Typically, the subject of this token will be the subject of the security token issued in response to the request.
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.

subject_token_type

(Required)

An identifier for the type of security token in the subject_token parameter.
actor_token A security token that represents the identity of the acting party. Typically, this will be the party that is authorized to use the requested security token and act on behalf of the subject.
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.

actor_token_type

(Required when the actor_token parameter is present in the request but must not be included otherwise)

An identifier for the type of security token in the actor_token parameter.

Access token validation grant type

The following parameter applies when the grant_type parameter for /as/token.oauth2 is set to urn:pingidentity.com:oauth2:grant_type:validate_bearer.

Parameter Description
token

(Required)

The bearer access 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.

This validation grant type is a custom PingFederate OAuth extension that enables a resource server (RS) to communicate with the OAuth AS while leveraging the established communication and encoding patterns from OAuth 2.0. The grant type allows an RS to check with the OAuth AS on the validity of a bearer access token that it has received from a client making a protected-resources call.

Tip:

Alternatively, an RS client can use the standard-based Introspection Endpoint (at /as/introspect.oauth2) to validate an access token or a refresh token.

Client authentication is not required. In other words, when creating a client for the sole purpose of validating access tokens, the Client Secret field is optional. For this grant type, the RS acts in the role of a client for the request/response exchange with the OAuth AS to make the validation call.

The response is a standard OAuth access-token response from the token endpoint with some extensions and minor semantic differences in the treatment of some of the parameters. The returned token is in a JSON structure with name-to-value elements or name-to-array elements.

The token type is urn:pingidentity.com:oauth2:validated_token, a URN indicating the token represents the attributes associated with the validated access token passed on the request. A client_id element is returned indicating the client identifier of the client to whom the grant was made. A scope element is returned, 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. The expires_in element indicates for how many more seconds the token is valid; note that the value may increase on subsequent validation calls if a token lifetime extension policy is in place.

Sample response when scope group expansion is disabled (the default)
{
  "access_token": {
    "Username": "joe",
    "OrgName": "Ping Identity Corporation"
  },
  "scope": "openid AAAGroup",
  "token_type": "urn:pingidentity.com:oauth2:validated_token",
  "expires_in": 7121,
  "client_id": "ac_oic_client"
}

Note that AAAGroup is a scope group.

Sample response when scope group expansion is enabled
{
  "access_token": {
    "Username": "joe",
    "OrgName": "Ping Identity Corporation"
  },
  "scope": "openid AAA1 AAA2",
  "token_type": "urn:pingidentity.com:oauth2:validated_token",
  "expires_in": 7169,
  "client_id": "ac_oic_client"
}

Note that AAA1 and AAA2 are the expanded outcome of AAAGroup.

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).