The authorization endpoint is defined in the OAuth 2.0 Authorization Framework (tools.ietf.org/html/rfc6749#section-3.1) and is used by the OAuth AS to interact directly with resource owners, authenticate them, and obtain their authorizations. Typically, an OAuth client makes an authorization request by directing a resource owner, via an HTTP user-agent, to the authorization endpoint. After completing 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 may be used as part of 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.
Endpoint: /as/authorization.oauth2
The following table describes parameters for this endpoint. The required
Content-Type value is
application/x-www-form-urlencoded
when transmitting via the HTTP
POST method.
Parameter | Description |
---|---|
client_id (Required) |
The client identifier. |
response_mode | When set to form_post , the authorization response is
returned to the client in an auto-POST form in accordance with the OAuth 2.0 Form Post Response
Mode specification
(openid.net/specs/oauth-v2-form-post-response-mode-1_0.html). |
response_type (Required) |
A value of code results in the Authorization Code grant
type while a value of token implies the Implicit grant
type. Additionally, a value of id_token can be requested by
implicit clients. 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 | Supply a one-time string value to associate the authorization request
with the token request to reduce the risk of authorization code interception
attack. For more information, refer to the Proof Key for Code Exchange (PKCE) by
OAuth Public Clients specification (tools.ietf.org/html/rfc7636).
Applicable only when response_type parameter
value is Note:
If used, the OAuth client must submit the corresponding code verifier when using the authorization code to obtain an access token (see code_verifier in OAuth grant type parameters). |
code_challenge_method | Applicable only when the response_type parameter
value is code and a code_challenge
parameter value is provided.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. Note that 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 all 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. However, for clients that have been configured with only one redirection URI, this requirement is waived to minimize the impact that it may impose on customers upgrading to version 9.1.4 (or a subsequent release). As needed, it can be enabled at a later time. Note:
If this parameter is used, the same parameter and value must also be used in subsequent token requests (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
guidelines defined under IETF BCP 47
(tools.ietf.org/html/bcp47). Tip:
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 screen 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 | The allowable elapsed time (in seconds) since the end users last
authenticated. If the elapsed time exceeds the value of max_age, the end
users are prompted for reauthentication. Tip:
The HTML Form Adapter supports the max_age parameter by tracking the authentication time for each user. |
request | 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.
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 algorithm (or algorithms). If the signature does not pass the verification process, the request fails. Optional if a client is not configured to transmit request parameters in signed request objects but it 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 algorithm (or algorithms). If the signature does not pass the verification process, the request fails. Ignored if a client is not configured to transmit request parameters in signed request objects and it is not configured with a JWKs URL or an actual JWKs. When PingFederate receives an authorization request with a signed request object, it processes the authorization request without taking the signed request object into consideration. 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. Note:
If a client includes in an authorization request a request parameter (other than client_id and response_type) 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 and response_type request parameters, 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. It is also worth noting that if a request parameter is found only outside of the signed request object, such request parameter is dropped and ignored; no error message is returned. Tip:
Per OAuth and OpenID Connect specifications, a client must always include in an authorization request the client_id, response_type, and scope request parameters outside of the signed request object. For client configuration information, see Configuring an OAuth client (the Require Signed Request setting). For more information about request object, please refer to the OpenID Connect specification (openid.net/specs/openid-connect-core-1_0.html#RequestObject). |
scope | The scope of the access request expressed as a list of space-separated,
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 |
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 guidelines defined under IETF BCP 47 (tools.ietf.org/html/bcp47). |
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. Note:
This parameter may 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, users are presented 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 is displayed on the user authorization page.
OpenID Connect parameters
The following table describes OpenID Connect parameters for this endpoint.
Parameter | Description |
---|---|
acr_values | Specifies the Authentication Context Class Reference (acr) values for the AS to use when processing an Authentication Request. Express as a space-separated string, listing the values 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 is passed 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, this parameter can be used by the client to verify that the
end user is still present for the current session or to bring attention to the
request. PingFederate supports the following values: |
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.
Parameter | Description |
---|---|
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
the request. Note:
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 which would be 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.
- Example 1: A partial match
- A resource URI of
https://app.example.local
is a partial match for the following provided URIs:- https://app.example.local/file1.ext
- https://app.example.local/path/file2.ext
- https://app.example.local/path/more
- Example 2: An exact match is a better match than a partial match
-
Access Token Management instances Resource URIs (configured) ATM1 https://localhost:9031/app1
https://localhost:9031/app2/data
https://app.example.local
ATM2 https://localhost:9031/app1/data
https://localhost:9031/app2/data/get
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, ATM2 is chosen becausehttps://localhost:9031/app1/data
(a resource URI pre-configured for ATM2) is an exact match against the provided URI. - Example 3: A more specific partial match is a better match
- Both
https://localhost:9031/app2/data
(a resource URI for ATM1) andhttps://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, ATM2 is chosen becausehttps://localhost:9031/app2/data/get
matches more specifically against the provided URI.