PingOne Advanced Identity Cloud

OAuth 2.0 endpoint parameters

Requests to OAuth 2.0 endpoints use the following parameters.

Refer to the individual OAuth 2.0 endpoint pages to determine the required and optional parameters for each endpoint.

acr_values

The OpenID Connect authentication context class reference values. OpenID Connect (OIDC) flows only.

Authentication context class reference values communicate acceptable Levels of Assurance (LoAs) users must satisfy when authenticating to the OpenID provider. For details, refer to Authentication requirements.

actor_token

The token representing a delegate acting on behalf of another identity in Token exchange.

actor_token_type

The type of the actor token:

  • urn:ietf:params:oauth:token-type:access_token

  • urn:ietf:params:oauth:token-type:id_token

auth_chain

A string naming the journey to authenticate the resource owner for Resource owner password credentials grant. The journey must permit username-password authentication without UI interaction. Otherwise, the request results in an HTTP 500 Internal Server Error.

Default: The default authentication journey for the realm.

claims

A JSON object containing the user attributes to return in the ID token. OIDC flows only.

client_assertion

A signed JSON Web Token (JWT) to use as client credentials for JWT profile authentication.

client_assertion_type

The type of assertion for JWT profile authentication.

Set client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer.

client_id

A unique string identifier for the application making the request.

For a pushed authorization request or a JWT-secured authorization request (RFC 9101), this value must match the client_id claim in the request object.

client_secret

A string password credential for the confidential client application making the request.

Use this parameter for client authentication with Form parameters (HTTP POST).

Do not use with the cnf_key parameter.

cnf_key

A base64-encoded JSON Web Key (JWK) for JWK-based proof-of-possession.

Do not use with the client_secret parameter.

code_challenge

A generated code verifier string for RFC 7636 Proof Key for Code Exchange (PKCE).

For details, refer to Generate a code verifier and a code challenge.

code_challenge_method

A string specifying the method to derive the PKCE code challenge:

  • plain (default; plaintext code challenge )

  • S256 (recommended; hashed code challenge)

code_verifier

A random string correlating a PKCE authorization request with the token request.

csrf

The SSO token string linking the request to user session to protect against Cross-Site Request Forgery (CSRF) attacks.

This parameter duplicates the value of the session cookie, the resource owner’s SSO token.

Built-in consent pages include this parameter once the resource owner has authenticated, and send it with the resource owner’s consent. Custom consent pages and flows that do not use a browser must set this parameter explicitly unless you use a Remote consent service. For an example, refer to the Authorization code grant.

decision

A string indicating whether the resource owner consents to the requested access:

  • allow to grant consent

  • Any other value denies consent

grant_type

A string specifying the type of grant to acquire an access token:

authorization_code

For authorization code grants.

client_credentials

For the Client credentials grant.

password

For the Resource owner password credentials grant.

refresh_token

To refresh an access token.

urn:ietf:params:oauth:grant-type:device_code

For the Device authorization grant. PingOne Advanced Identity Cloud also supports the earlier http://oauth.net/grant_type/device/1.0 specification.

urn:ietf:params:oauth:grant-type:saml2-bearer

For the SAML 2.0 profile for authorization.

urn:ietf:params:oauth:grant-type:jwt-bearer

For the JWT profile for authorization.

urn:ietf:params:oauth:grant-type:token-exchange

For the Token exchange.

urn:openid:params:grant-type:ciba

For the Backchannel request grant.

id_token_hint

A previously issued ID token passed as a hint about the end user’s session with the client. OIDC flows only.

Set the response_type and prompt parameters to none when using this parameter. For details, refer to Session Management Draft 10.

login_hint

A string specifying the ID used to log in. OIDC flows only.

The ID depends on the authentication journey.

When provided as part of the OpenID Connect authentication request, an HttpOnly cookie (only sent over HTTPS) named oidcLoginHint gets the value of login_hint. For details, refer to GSMA Mobile Connect.

nonce

A string linking the client session with the ID token to mitigate against replay attacks. OIDC flows only.

prompt

A space-separated, case-sensitive list of ASCII strings that indicates whether to prompt the end user for authentication and consent. OIDC flows only.

consent

Prompt the end user for consent even if a consent response was previously saved.

login

Prompts the end user to authenticate using the journey specified with the service parameter. When the user re-authenticates, PingOne Advanced Identity Cloud destroys the original session and creates a new one for the new journey.

Default: The default journey for the realm.

none

Do not display authentication or consent pages. Use this only when you set id_token_hint and response_type=none.

redirect_uri

The URI to return the resource owner to after authorization is complete.

Default: A value from the client profile Sign-in URLs setting in the Advanced Identity Cloud admin UI.

response_mode

A string specifying the mechanism for returning response parameters:

form_post

Return a self-submitting form that contains the code instead of redirecting to the redirect URL with the code as a string parameter. For details, refer to OAuth 2.0 Form Post Response Mode.

fragment

Return parameters encoded in the URL fragment; default when response_type=token.

fragment.jwt

Return a JWT in a fragment.

jwt

Return parameters in a JWT; in a query string for the code response type, or appended to the fragment for the token response type.

A JWT-secured authorization response (JARM) returns authorization response parameters in a signed, optionally encrypted, JWT.

Configure the algorithms to secure the JWT in the Advanced Identity Cloud admin UI under Applications > Client ID > Sign On > General Settings > Show advanced settings > Signing and Encryption.

In addition to claims specific to the response type, such as code or access_token, the JWT contains these mandatory claims:

  • iss: the URL of the issuer—​the authorization server that generated the response

  • aud: the audience—​the client ID intended as the response recipient

  • exp: the expiration of the JWT—​10 minutes is the recommended maximum

On error, the JWT contains:

  • An error string

  • A state string if specified by the client

  • An error description

For details, refer to JWT-Secured Authorization Response Mode for OAuth 2.0 (JARM).

query

Return parameters encoded in the query string; default when response_type=code.

query.jwt

Return a JWT in a query parameter. Do not use this with id_token or token response types unless the response JWT is encrypted.

For details, refer to Response Modes. PingOne Advanced Identity Cloud publishes supported response modes as response_modes_supported through the /oauth2/.well-known/openid-configuration endpoint.

response_type

A string specifying the response expected from the authorization server:

code

An authorization code for an authorization code grant

code id_token

An authorization code and an ID token for a hybrid grant

code token

An authorization code and an access token for a hybrid grant

code token id_token

An authorization code, an access token, and an ID token for a hybrid grant

id_token

An ID token for an implicit grant

none

Do not issue any token or code in the response; for use with id_token_hint only

token

An access token for an implicit grant

token id_token

An access token and an ID token for an implicit grant

request

A base64url-encoded JWT whose claims are required for an OIDC flow, a JWT-secured authorization (JAR) request (RFC 9101), or a pushed authorization request (PAR) (RFC 9126).

This JWT is called the request object.

Request object validation rules depend on the type of request and the OAuth 2.0 provider configuration. The validation rules apply whether you pass the request object by value with the request parameter or as a reference with the request_uri parameter:

General validation rules

These rules apply for all request objects:

  • If the request object is signed or encrypted, you must include the iss and aud parameters, as shown in the Example request object.

    For the public keys to encrypt a request object JWT, make a request to the realm’s /oauth2/connect/jwk_uri endpoint.

  • The exp (expiration time) and nbf (not before) claims set the timeframe when the request object is valid.

    If the OAuth 2.0 provider settings declare them mandatory, you must include the exp and nbf claims.

    If specified, validation uses these claims even when the OAuth 2.0 provider settings do not require them.

    To ensure the values meet the requirements for the Financial-grade API (FAPI) security profile, refer to the OAuth 2.0 provider configuration reference.

  • Compressed JWTs must not be larger than 32 KiB (32768 bytes) when uncompressed.

JAR validation rules

These rules apply when the request object does not contain OIDC-specific parameters or when the OAuth 2.0 provider setting Request Object Processing Specification specifies JAR processing:

  • The request object must be signed. It may be encrypted.

  • The request object must include a client_id matching the client_id parameter of the request.

  • The authorization request uses only the request object claims, even when the request specifies the same claims in query string parameters.

OIDC validation rules

These rules apply for OIDC requests when the OAuth 2.0 provider setting Request Object Processing Specification specifies OIDC (default):

  • The request object does not require signing or encryption.

  • You may send query string parameters and a request object in the same request.

    You can keep sensitive information protected in the request object, and keep parameters that change frequently, such as nonce and state, visible and mutable across calls.

    The claims in the request object supersede the query string parameters.

  • You must include the response_type and client_id as query string parameters, even if you include them in the request object.

    Their values in the request object must match those passed as query string parameters.

  • You must include the openid scope as a query string parameter, even if you include it in the request object.

    The scope claim may differ from the scope query string parameter. Use this to protect application-related scopes in the request object, but process the request as part of an OpenID Connect flow.

PAR validation rules

These rules apply for pushed authorization request objects:

  • The request object must be signed. It may be encrypted.

  • You must include the client_id even though it is also a required query string parameter.

  • The response_type claim in the request object passed by value takes the place of the response_type query string parameter.

  • You must include claims for all other parameters required for the successful completion of the grant flow.

    For example, include the code_challenge for an Authorization code grant with PKCE flow.

  • When you include the request object, omit all other parameters except to authenticate the client.

    The request object must include claims for all other request details. Otherwise, the response is an Invalid parameter scope error.

Example request object

The following example JWT request object includes OIDC claims and iss, aud, nbf, and exp claims. Advanced Identity Cloud ignores keys specified in JWT headers, such as jku and jwe:

{
  "client_id": "myClient",
  "iss": "myClient",
  "aud": "https://<tenant-env-fqdn>/am/oauth2/realms/root/realms/alpha",
  "nbf": 1675351332,
  "exp": 1675351692,
  "redirect_uri": "https://www.example.com:8443",
  "scope": "openid profile",
  "claims": {
    "id_token": {
      "acr": {
        "essential": true,
        "values": ["example_journey1", "example_journey2"]
      }
    }
  }
}

To pass the request object by value, specify the encoded JWT as shown in this example OIDC call:

https://<tenant-env-fqdn>/am/oauth2/realms/root/authorize? \
&request=eyJhbGciOiJSUzI1NiIsImtpZCI6ImsyYmRjIn0.ew0KICJpc3MiOiAiczZCaGRSa3... \
&client_id=myClient \
&scope=openid profile \
&response_type=code%20id_token \
&nonce=abc123 \
&state=123abc

request_uri

A reference to JWT request object(s).

  • For PAR flows, this references the data at the time of the PAR request.

    The authorization request fails if the request URI has expired.

  • For OIDC flows and JAR requests, this references an array of URIs to retrieve request objects whose claims constitute the request parameters.

    You must pre-register the URIs in the client profile. In the Advanced Identity Cloud admin UI, go to Applications > Client ID > Sign On > Show advanced settings > Authentication > Request URIs. Each request URI must not exceed 512 ASCII characters and must use either HTTP or HTTPS; for example, https://www.example.com:8443/JTWs/myJWT.

    PingOne Advanced Identity Cloud caches the request objects to avoid requesting them too often. To force PingOne Advanced Identity Cloud to flush the cache, add a unique fragment to the request_uri parameter; for example, ?request_uri=https://www.example.com:8443/JTWs/myJWT#foo.

requested_token_type

The type of token requested for Token exchange:

  • urn:ietf:params:oauth:token-type:access_token (default)

  • urn:ietf:params:oauth:token-type:id_token

save_consent=on means save the scopes the resource owner’s consented to.

Saving consent requires prior configuration. For details, refer to Store consent decisions.

scope

A string specifying the permissions the client application requests from the resource owner. Separate scopes with spaces.

Some grants, such as the authorization code grant, do not call the token endpoint with the scope. The scope is defined in the authorization code. For details, refer to the documentation for the flow under OAuth 2.0 grant flows.

Default: The default scopes specified in the client profile or the OAuth 2.0 provider configuration.

service

A string naming the journey to authenticate the resource owner.

Default: The default authentication journey for the realm.

For details, refer to Authentication parameters.

state

A string value to maintain state between the request and the callback.

During authentication, the client sends this parameter to the authorization server. The authorization server sends it back unchanged in the response.

Use the value to ensure the response belongs to the user who initiated the requests. This mitigates against CSRF attacks.

Use a base64-encoded string of data that is unique to a user and to this request.

subject_token

The original token to exchange in Token exchange.

subject_token_type

The type of the subject token:

  • urn:ietf:params:oauth:token-type:access_token

  • urn:ietf:params:oauth:token-type:id_token

ui_locales

A string indicating the end user’s preferred languages for the user interface. OIDC flows only.

The ui_locales parameter is a space-separated list ordered by preference; for example, en fr-CA fr.

Copyright © 2010-2024 ForgeRock, all rights reserved.