PingFederate Server

OAuth grant type parameters

The /as/token.oauth2 endpoint accepts other parameters which vary by the grant type presented.

These parameters include OAuth-defined standard parameters and parameters proprietary to PingFederate. The following parameter indicates the grant type of the access token request.

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

The following sections define further parameters associated with each grant type.

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.

If a code_challenge_method parameter value is provided in the request for the authorization code, PingFederate OAuth Authorization Server (AS) validates the code_verifier parameter value against that of the code_challenge value. If the validation returns no errors, PingFederate OAuth AS returns an access token; 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. For more information, 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.

Scopes can also be constrained on a client-to-client basis. For more information, 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.

To avoid recording this parameter in web server logs, only pass it in the message body using the HTTP POST method.

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.

Scopes can also be constrained on a client-to-client basis. For more information, 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.

To avoid recording this parameter in web server logs, only pass it in the message body using the HTTP POST method.

scope

The scope of the access request expressed as a list of space-delimited, case-sensitive strings. Scopes can also be constrained on a client-to-client basis. For more information, see Scopes and scope management.

validator_id

A PingFederate OAuth AS parameter indicating the instance ID of the password credential validator 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, in no particular order, 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. See the following 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 that the LDAP Username PCV detects. OAuth-client developers can create custom experiences based on the error messages.

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.

You can localize these messages by using the PingFederate localization framework for an international audience. For more information, see Localizing messages for end users.

The client_id parameter is not required when the Allow unidentified clients to make resource owner password credentials grants check box is selected in the System → OAuth Settings → Authorization Server Settings window.

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. Scopes can also be constrained on a client-to-client basis. For more information, 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

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 smart phone 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.

To avoid recording this parameter in web server logs, only pass it in the message body using the HTTP POST method.

scope

The scope of the access request expressed as a list of space-delimited, case-sensitive strings. Scopes can be constrained on a client-to-client basis. For more information, see Scopes and scope management.

The client_id parameter is not required when the Allow unidentified clients to request extension grants check box is selected in the System → OAuth Settings → Authorization Server Settings window.

SAML 2.0 Bearer Assertion grant type

The following 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. For more information, see RFC4648, section 5.

To avoid recording this parameter in web server logs, only pass it in the message body using the HTTP POST method.

scope

The scope of the access request expressed as a list of space-delimited, case-sensitive strings. Scopes can be constrained on a client-to-client basis. For more information, see Scopes and scope management.

The client_id parameter is not required when the Allow unidentified clients to request extension grants check box is selected in the System → OAuth Settings → Authorization Server Settings window.

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. Scopes can also be constrained on a client-to-client basis. For more information, 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.

To avoid recording this parameter in web server logs, only pass it in the message body using the HTTP POST method.

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.

To avoid recording this parameter in web server logs, only pass it in the message body using the HTTP POST method.

actor_token_type

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

This parameter is required when the actor_token parameter is present in the request but must not be included otherwise.

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.

To avoid recording this parameter in web server logs, only pass it in the message body using the HTTP POST method.

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. This grant type allows an RS to verify with the OAuth AS on the validity of a bearer access token that it has received from a client making a protected-resources call.

An RS client can also 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; the value can 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"
}

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"
}

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