The OAuth authorization server (AS) uses the authorization endpoint to interact directly with resource owners, authenticate them, and obtain their authorizations.
The OAuth 2.0 Authorization Framework defines the authorization endpoint. Typically, an OAuth client makes an authorization request by directing a resource owner through an HTTP user-agent to the authorization endpoint. After the OAuth AS completes its interaction with the resource owner, the OAuth AS redirects the resource owner's user-agent back to the client's redirect URI with the response to the authorization request.
This endpoint can be used in an OAuth Scope Authentication Selector configuration, which can affect the behavior of the endpoint. For example, the idp parameter might be enforced or overridden by policy determined by an instance of the OAuth Scope Authentication Selector.
This endpoint accepts the HTTP GET and POST methods.
When transmitting through the HTTP POST method, the required
Content-Type value is
application/x-www-form-urlencoded. The following table describes
parameters for this endpoint.
|The client identifier.|
|response_mode||When set to
|response_type||A value of
To initiate a Hybrid Flow, multiple response_type values can be specified by space-separating them. When using the Hybrid Flow, some tokens are returned from the Authorization Endpoint and others are returned from the Token Endpoint. For information about multiple-valued response type combinations, see the description of the restrictedResponseTypes parameter in OAuth Client Management Service.
|code_challenge||To reduce the risk of authorization code interception attack, supply a
one-time string value to associate the authorization request with the token
request. For more information, see Proof Key for Code Exchange (PKCE) by OAuth Public Clients.
Applicable only when response_type parameter
If used, the OAuth client must submit the corresponding code verifier when using the authorization code to obtain an access token. For more information, see code_verifier in OAuth grant type parameters.
|code_challenge_method||Applicable only when the response_type parameter
This parameter indicates the transformation method used to derive the code_challenge parameter value from that of the code_verifier parameter. PingFederate OAuth AS supports two transformation methods:
The code_challenge_method parameter value is case-sensitive. An error message is returned to the clients for any other values.
Omitting the code_challenge_method
parameter has the same effect as providing the
code_challenge_method parameter with a value of
|redirect_uri||The URI to which PingFederate redirects the resource owner's user-agent
after an authorization is obtained.
For OpenID Connect protocol compliance, clients that use the authorization code or implicit grant type must include this parameter in their authorization requests. It is also the default behavior in new PingFederate installations starting with version 9.1.4.
For upgraded installations, this requirement remains true for clients that have been configured with more than one redirection URIs. For clients that have been configured with only one redirection URI, this requirement is waived to minimize the impact that it might impose on customers upgrading to version 9.1.4 or a subsequent release. As needed, it can be enabled at a later time.
If this parameter is used, the same parameter and value must also be used in subsequent token requests. For more information, see OAuth grant type parameters.
|claims_locales||Specifies the end-user's preferred languages for claims being returned
in a space-separated list, ordered by preference. The values must conform to
the IETF BCP 47 guidelines.
You can map the claims_locales value into the persistent grants (and therefore the access tokens, the ID tokens, or both) from an IdP adapter or an IdP connection by selecting Context under Source and Requested Claims Locales under Value in the Contract Fulfillment tab in the IdP Adapter Mapping configuration or the OAuth Attribute Mapping configuration in an IdP connection.
|login_hint||Provides a hint to the PingFederate AS about the end user. For example, when an OAuth client includes a login_hint in its authorization request and the authentication source is an HTML Form Adapter instance, the username field in the login form is pre-populated with the login_hint parameter value.|
|max_age||Sets an allowable elapsed time in seconds since the end user last
authenticated. If the elapsed time exceeds the value of
max_age, PingFederate prompts the end user for
The HTML Form Adapter supports the max_age parameter by tracking the authentication time for each user.
A single, self-contained parameter; a signed JWT whose claims represent the request parameters of the authorization request. The OpenID Connect specification calls this JWT a request object.
The request parameter is required if a client is configured to transmit request parameters in signed request objects. When PingFederate receives an authorization request, it verifies the digital signature of the signed request object based on the key obtained from the pre-configured JWKS URL or JWKS, and the selected request object signing algorithms. If the signature does not pass the verification process, the request fails.
The request parameter is optional if a client is not configured to transmit request parameters in signed request objects but is configured with a JWKS URL or an actual JWKS. This flexibility allows the client to transmit request parameters in signed request objects for some requests and without the use of signed request objects for some other transactions. When PingFederate receives an authorization request with a signed request object, it verifies the digital signature of the signed request object based on the key obtained from the pre-configured JWKS URL or JWKS, and the selected request object signing algorithms. If the signature does not pass the verification process, the request fails.
If a client is not configured to transmit request parameters in signed request objects and is not configured with a JWKs URL or an actual JWKs, PingFederate ignores the request parameter. When PingFederate receives an authorization request with a signed request object, it processes the authorization request and disregards the signed request object. As needed, develop a custom IdP adapter using the PingFederate SDK to extract the request parameter and its value from the HTTP request for further processing.
If a client includes in an authorization request a request parameter other than client_id, as a parameter outside of the signed request object and a claim inside of the signed request object, PingFederate always uses the claim value found inside the signed request object to process the request further.
For the client_id request parameter, the values outside of the signed request object must match the claim values inside of the signed request object. If the values do not match, PingFederate returns an error message to the client.
If a request parameter is found only outside of the signed request object, PingFederate ignores the request parameter and returns no error message.
Per OAuth and OpenID Connect specifications, a client must always include in an authorization request the client_id parameter outside of the signed request object.
For client configuration information, see the Require Signed Request setting in Configuring OAuth clients. For more information about request objects, see JWT Secured Authorization Request (JAR) draft specification.
|request_uri||This parameter indicates that the client is using the pushed authorization requests (PAR) protocol
to initiate an authorization flow. The client previously pushed an
authorization request payload to the PAR endpoint of the AS. The payload can
contain any of the parameters that usually comprise an authorization request
and any additional parameters needed for client authentication. After the AS
validated the request and saved the payload, it sent the
request_uri parameter to the client to serve as a
reference to the payload.
Now the client is using the request_uri parameter to request an authorization code or token. The AS uses the value of the request_uri to look up the request payload and continue the authorization flow as usual. The AS accepts a particular request URI only once. For more information about PAR, see Pushed authorization requests endpoint.
|scope||Expresses the scope of the access request as a list of space-separated, case-sensitive strings. For detailed information about scopes, see Scopes and scope management.|
|state||An opaque value used by the client to maintain state between the request and callback. If included, the AS returns this parameter and the given value when redirecting the user agent back to the client.|
|ui_locales||Specifies the end-user's preferred languages for OAuth user interactions in a space-separated list, ordered by preference. The values must conform to the IETF BCP 47 guidelines.|
|idp or PartnerIdpId||A PingFederate OAuth AS parameter indicating the entity ID or the connection ID of the IdP with whom to initiate Browser SSO for user authentication.|
|pfidpadapterid or IdpAdapterId||A PingFederate OAuth AS parameter indicating the IdP adapter instance ID
of the adapter to use for user authentication.
This parameter might be overridden by policy based on authentication policies. For example, an OAuth Scope Authentication Selector instance could enforce the use of a given adapter instance based on client-requested scopes.
If more than one source of authentication is configured in the system and no pfidpadapterid or idp parameter is provided, PingFederate provides users with an intermediate page asking them to choose among the available sources of authentication. The authentication results in a set of user attributes that must be mapped into the USER_KEY attribute for persistent grant storage and the USER_NAME attribute that displays on the user authorization page.
OpenID Connect parameters
The following table describes OpenID Connect parameters for this endpoint.
|acr_values||Specifies the Authentication Context Class Reference (acr) values for the AS to use when processing an Authentication Request. Express the values as a space-separated string, and list them in order of preference.|
|id_token_hint||Includes an ID token as a hint to the PingFederate AS about the end user. If the authenticated user does not match the information stored in the ID token, the PingFederate AS rejects the authorization request and returns an error message.|
|nonce||Specifies a string value used to associate a client session with an ID token and to reduce replay attacks. The value passes through unmodified from an authorization request to the ID token.|
|prompt||Specifies whether the AS prompts the end user for reauthentication
and consent. Expressed as a list of space-separated, case-sensitive ASCII
string values. If included, the client can use this parameter to verify
that the end user is still present for the current session or to bring
attention to the request.
PingFederate supports values of
OAuth access token management parameters
PingFederate supports multiple access token management (ATM) instances. Clients can specify an ATM instance by providing the ATM ID (access_token_manager_id) or a resource URI (aud) in their requests to the PingFederate OAuth AS.
|access_token_manager_id||The access_token_manager_id value is the instance
ID of the desired ATM instance. When specified, PingFederate uses the
desired ATM instance for the request if it is eligible; otherwise it aborts
When the access_token_manager_id parameter is specified, PingFederate ignores the aud parameter.
|aud||The aud is the resource URI the client wants to access. The provided value is matched against resource URIs configured in access token management instances. When a match is found, PingFederate uses the corresponding access token management instance for the request if it is eligible; otherwise it aborts the request.|
A match can be an exact match or a partial match where the provided URI has the same scheme and authority parts and a more specific path contained within the path of the pre-configured resource URI. PingFederate takes an exact match over a partial match. If there are multiple partial matches, PingFederate takes the partial match where the provided URI matches more specifically against the pre-configured resource URI.
A partial matchA resource URI of
https://app.example.localis a partial match for the following provided URIs:
An exact match is a better match than a partial match
|Access Token Management instances||Resource URIs (configured)|
https://localhost:9031/app1 (a resource URI pre-configured for ATM1) is
a partial match for https://localhost:9031/app1/data (the provided URI). However,
PingFederate chooses ATM2 because
resource URI pre-configured for ATM2) is an exact match against the provided URI.
A more specific partial match is a better matchBoth
https://localhost:9031/app2/data(a resource URI for ATM1) and
https://localhost:9031/app2/data/get(a resource URI for ATM2) are partial matches for https://localhost:9031/app2/data/get/sample (the provided URI). However, PingFederate chooses ATM2 because
https://localhost:9031/app2/data/getmatches more specifically against the provided URI.