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:
NOTEFurther 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 paramter 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 Proof Key for Code Exchange (PKCE) by OAuth Public Clients(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.
|
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. |
| 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 by the resource owner. If omitted, the scope is treated as equal to that originally granted by the resource owner.
Valid scope values are defined in the screen.
Scopes can also be restricted per client.
|
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. |
| scope | The scope of the access request. |
| 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 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 PCV. OAuth-client developers may create custom experiences based on the error messages.
TIPThese customizable messages are stored in the<pf_install>/pingfederate/server/default/conf/language-packs/pingfederate-messages.properties file.
As needed, they may be localized using the PingFederate localization framework for an international audience.
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
These parameters apply when the grant_type parameter for
/as/token.oauth2 is set to client_credentials.| Parameter | Description |
| scope | The scope of the access request. |
SAML 2.0 Bearer Assertion grant type
These parameters apply when the grant_type parameter for
/as/token.oauth2 is set tourn: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). |
| scope | The scope of the access request. |
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.
Access token validation grant type
These parameters apply when the grant_type parameter for
/as/token.oauth2 is set tourn: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. 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.
TIPAlternatively, 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. 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 (applicable only to access tokens using the reference-token data model).
Example
{
"scope":"read edit admin",
"token_type":"urn:pingidentity.com:oauth2:validated_token",
"expires_in":3172,
"client_id":"super_cool_mobile_client",
"access_token":
{
"uid":"sfHqhad9onMjXsQNI1mZP9mD7AQasmskd",
"group":["employee","sales","manager"],
"email":"someguy@example.cloud"
}
}
No comments:
Post a Comment