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:
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 Scopes and scope management. screen. Scopes can also be constrained on a client-to-client basis. For detailed information about scopes, see |
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 Scopes and scope management. screen. Scopes can also be constrained on a client-to-client basis. For detailed information about scopes, see |
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 Scopes and scope management. screen. Scopes can also be constrained on a client-to-client basis. For detailed information about scopes, see |
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."
}
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 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 Scopes and scope management. screen. Scopes can also be constrained on a client-to-client basis. For detailed information about scopes, see |
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 Scopes and scope management. screen. Scopes can also be constrained on a client-to-client basis. For detailed information about scopes, see |
Note that the client_id parameter is not required when the Allow unidentified clients to request extension grants check box is selected on the 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 Scopes and scope management. screen. Scopes can also be constrained on a client-to-client basis. For detailed information about scopes, see |
Note that the client_id parameter is not required when the Allow unidentified clients to request extension grants check box is selected on the 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 Scopes and scope management. screen. Scopes can also be constrained on a client-to-client basis. For detailed information about scopes, see |
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.
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).