PingFederate Server

Authorization endpoint

The OAuth OAuth authorization server (OAuth 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.

Endpoint: /as/authorization.oauth2

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.

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.

response_type

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

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 value is code. Mandatory if the client is required to do so. For more information, see Require Proof Key for Code Exchange (PKCE) in Configuring OAuth clients.

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 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:

  • plain, which indicates the code_challenge parameter value is that of the code_verifier parameter.

  • S256, which indicates the code_challenge parameter is derived from the code_verifier parameter value as follows

[.parmname]code_challenge=Base64Url-encode(SHA256(ASCII([.parmname]code_verifier))), where:

  • ASCII([.parmname]code_verifier) denotes the octets of the ASCII representation of the code_verifier value.

  • SHA256(octets) denotes the SHA 256-bit hash of the octets.

  • Base64Url-encode(octets) denotes the base64url encoding of octets; the output is URL-safe.

    For detailed information about the transformation method, see Proof Key for Code Exchange (PKCE) by OAuth Public Clients.

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 plain.

redirect_uri

The URI to which PingFederate redirects the resource owner’s user-agent after an authorization is obtained.

For OpenID Connect (OIDC) 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 identity provider (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 authentication.

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 JSON Web Token (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.

PingFederate can decrypt encrypted request objects, which are described in the OpenID Connect 1.0 specification. Request objects with asymmetric encryption must be encrypted using the public keys that PingFederate exposes at /pf/JWKS. Request objects with symmetric encryption need a key derived from the client’s configured client secret and the client secret must be stored in a reversible format with, for example, symmetric encrypted ID tokens or hash-based message authentication code (HMAC) ID tokens. You can configure PingFederate to accept only request objects that are encrypted by enabling the front-channel-encryption-required setting in jwt-request-object-options.xml.

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 RFC 9101: JWT Secured Authorization Request (JAR).

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 single sign-on (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.

PolicyAction

(optional)

The HTML Form Adapter immediately returns the value of this parameter in the policy.action attribute, allowing the policy to bypass the adapter in favor of an alternative authentication source, provided a rule matching the action is configured. When this parameter is set to identity.registration and the adapter is followed by a local identity profile, the user is directed to the registration page for the profile.

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.

Parameter Description

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 none, login, and consent.

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.

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.

Example

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