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 | ||
---|---|---|---|
(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 grant type
These parameters apply when the grant_type
parameter for /as/token.oauth2
is set to authorization_code
.
Parameter | Description |
---|---|
(Required) |
The authorization code received from the authorization server during the redirect interaction at the authorization endpoint when the |
|
Required if the authorization request was sent with a If a For more information about the |
|
This parameter is required if the 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. |
(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 | ||
---|---|---|---|
(Required) |
The refresh token issued to the client during a previous access token request.
|
||
|
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 | ||
---|---|---|---|
(Required) |
The username, encoded as UTF-8. |
||
(Required) |
The password, encoded as UTF-8.
|
||
|
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. |
||
|
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 If multiple validator instances are configured and mapped and no |
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, 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 |
---|---|
|
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 |
---|---|
|
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 |
---|---|
(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 | ||
---|---|---|---|
(Required) |
A JSON Web Token (JWT), as defined in RFC7523, section 2.1.
|
||
|
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 | ||
---|---|---|---|
(Required) |
A single SAML 2.0 assertion, which must be encoded using base64url. For more information, see RFC4648, section 5.
|
||
|
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 |
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 | ||
---|---|---|---|
|
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 |
||
|
The logical name of the target where the client will use the requested security token. This serves a purpose like the |
||
|
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. |
||
|
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 |
||
(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.
|
||
(Required) |
An identifier for the type of security token in the |
||
|
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.
|
||
|
An identifier for the type of security token in the
|
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.
|
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 |
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.