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:
Note:
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. Important:
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. Important:
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."
}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 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...1VwThe 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. Important:
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 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. Important:
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 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. Important:
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. Important:
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. Important: 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. Important:
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.