Access Management 7.2.2

/oauth2/par

The /oauth2/par endpoint is the OAuth 2.0 pushed authorization request (PAR) endpoint as defined in RFC 9126.

Use this endpoint to push an authorization request payload directly to the authorization server. The endpoint can be used in conjunction with the following grant flows:

You must compose the path to the PAR endpoint using the specific realm for the OAuth 2.0 provider. For example, if the provider is configured for the alpha subrealm, then use:

https://openam.example.com:8443/openam/oauth2/realms/root/realms/alpha/par.

The PAR endpoint supports the following parameters:

client_id

Specifies the client ID unique to the application making the request.

Required: Yes, even when it is also included in a request object.

client_secret

Specifies the password of the private client making the request. Do not use in conjunction with the cnf_key parameter.

Required: Confidential clients require some type of credential. However, the use of the client_secret parameter depends on the client authentication method used. For more information, see OAuth 2.0 client authentication.

request

A signed and optionally encrypted JWT object containing the request parameters.

The JWT must include the following claims:

  • client_id

    This must be included even though it is also a required parameter of the request itself.

  • response_type

    See response_type for details of this required parameter.

  • exp and nbf

    Include the exp and nbf claims if they are set as mandatory in the OAuth 2.0 provider configuration.

    The exp (expiration time) and nbf (not before) claims provide the timeframe within which the JWT is valid. If specified, these values are used to validate the JWT, even when they are not required.

    To ensure the values meet the requirements for the Financial-grade API (FAPI) security profile, see the OAuth2 provider configuration.

  • All other parameters that are required for the successful completion of the grant flow must be included, too. For example, you need to define code_challenge for an Authorization code grant with PKCE flow.

If a JWT request object is specified, no other parameters are permitted in the request itself except for client authentication parameters.

All other request details must be defined as claims in the JWT, otherwise the request returns an Invalid parameter scope error.

The following is an example of a request object.

{
  "client_id": "myClient",
  "nbf": 1594140030,
  "redirect_uri": "https://www.example.com:8443",
  "scope" : "write",
  "exp": 1594140390,
  "response_type" : "code",
  "code_challenge" :  "QR1D-7w1-rOQvlFe1CeqZigqaIpmZXatDMVvZ50o",
  "code_challenge_method" : "S256"
}

Required: No.

response_type

Specifies the type of response expected from the authorization server. Set this parameter to one of the following values:

  • code, to request an authorization code during the authorization code grant flow.

  • token, to request an access token during the implicit grant flow.

  • id_token, to request an ID token during the implicit grant flow

  • code token, to request an authorization code and an access token during the Hybrid grant flow.

  • code id_token, to request an authorization code and an ID token during the Hybrid grant flow.

  • code token id_token, to request an authorization code, an access token, and an ID token during the Hybrid grant flow.

  • token id_token, to request an access token and an ID token during the implicit grant flow.

  • none, to request AM not to issue any token or code in the request. Use this response type in conjunction with the id_token_hint parameter only.

Required: Yes, but as a JWT claim if a request object is specified.

csrf

When interacting with the OAuth 2.0 consent page, this parameter helps prevent against Cross-Site Request Forgery (CSRF) attacks.

The parameter duplicates the contents of the iPlanetDirectoryPro cookie, which contains the SSO token of the resource owner giving consent.

When using the AM consent pages, this parameter is set in the consent page once the resource owner has authenticated, and it is sent to AM along with the consent.

When replacing AM consent pages with your own consent pages or when trying the flows without a browser, you must set this parameter manually. For an example of a curl command, see the Authorization code grant.

Required: Yes, for calls that are submitting consent response, unless you use the Remote Consent Service to gather consent.

code_challenge

Specifies a string derived from the code verifier that is sent in the authorization request during the authorization code with PKCE grant flow.

Required: Yes, always required for clients that are registered as confidential, or when requesting an authorization code during the Authorization code grant with PKCE flow, regardless of client registration type.

code_challenge_method

Contains the method used to derive the code challenge. Possible values are plain and S256. When unset, it defaults to plain. For clients that are registered as confidential, this value must be set to S256.

Required: Yes, when requesting an authorization code during the Authorization code grant with PKCE flow and the code challenge was created using an SHA256 algorithm.

decision

Specifies whether the resource owner consents to the requested access. Set to allow to grant consent. Any other value denies consent.

Required: Yes, for calls that are submitting consent response, unless consent is already saved for the scope.

redirect_uri

The URI to return the resource owner to after authorization is complete. If not set, the redirection URI defaults to that configured in the client profile registered with AM.

Required: No.

response_mode

Set to form_post to return a self-submitting form that contains the code instead of redirecting to the redirect URL with the code as a string parameter. For more information, see the OAuth 2.0 Form Post Response Mode spec.

Required: No.

scope

Specify the scopes linked to the permissions requested by the client from the resource owner. If not specified, the default scopes specified in the client or the authorization server are requested.

Required: No.

save_consent

Updates the resource owner’s profile to avoid having to prompt the resource owner to grant authorization when the client issues subsequent authorization requests.

Set this parameter to on to save the consent.

To save the consent, you must have configured the Saved Consent Attribute Name property with a profile attribute in which to store the resource owner’s consent decision.

For more information on setting this property in the OAuth 2.0 provider service, see OAuth2 Provider.

Required: No.

service/module

Use either as described in Authentication Parameters, where module specifies the authentication module instance to use, or service specifies the authentication tree or chain to use when authenticating the resource owner.

If not specified, the resource owner authenticates using the default chain or tree configured for the realm.

Required: No.

state

Value to maintain state between the request and the callback. During authentication, the client sends this parameter to the authorization server. The authorization server must send it back unchanged in the response.

The application should use this value to ensure the response belongs to the user that initiated the requests, which mitigates CSRF attacks.

The value of state is typically a base64-encoded string that contains user state and that is unique to a user and their request.

Required: No, but it is strongly recommended.

acr_values

Authentication Context class Reference values used to communicate acceptable LoAs that users must satisfy when authenticating to the OpenID provider.

For more information, see Add authentication requirements to ID tokens.

Required: No. OIDC flows only.

claims

Specifies a JSON object containing specific attributes about users to be returned in the ID Token.

Required: No. OIDC flows only.

id_token_hint

ID token previously issued by AM that is passed as a hint about the end user’s session with the client. Using this parameter requires the response_type and prompt parameters to be set to none.

For more information about using the id_token_hint parameter, see Session Management Draft 10.

Required: No. OIDC flows only.

login_hint

String value that can be set to the ID the user uses to log in. For example, Bob or bob@example.com, depending on how the authentication node or module is configured to search for users.

When provided as part of the OIDC authentication request, the login_hint is set as the value of a cookie named oidcLoginHint, which is an HttpOnly cookie (only sent over HTTPS).

For more information, see GSMA Mobile Connect.

Required: No. OIDC flows only.

nonce

String value that associates the client session with the ID token that also mitigates against replay attacks. For more information, see OpenID Connect 1.0.

Required: No. OIDC flows only.

prompt

A space-separated, case-sensitive list of ASCII values that specifies whether AM should prompt the end user for authentication and consent. Possible values are:

  • none. AM does not display authentication or consent pages. Use with the id_token_hint and the response_type=none parameters only.

  • login. AM prompts the end user to authenticate to the default service of their realm, or to the service provided in the service parameter.

    If the user reauthenticates to a tree, AM destroys the original session and provides them with a new one that reflects the new authentication journey.

    If the user reauthenticates to a chain, AM updates the original session to reflect the new authentication journey.

  • consent. AM prompts the end user to grant consent, even if a consent response was previously saved.

Required: No. OIDC flows only.

ui_locales

Specifies a space-separated list of the end user preferred languages for the user interface, ordered by preference. For example, en fr-CA fr.

Required: No. OIDC flows only.

request_uri

PAR permits any of the parameters applicable to the /authorize endpoint, except for request_uri. It is invalid to specify this parameter in a PAR request.

Required: No.