/oauth2/authorize

The /oauth2/authorize endpoint is the OAuth 2.0 authorization endpoint as defined in RFC 6749. Use this endpoint to gather consent and authorization from the resource owner when using the following flows:

Authorization code grant (OAuth 2.0) | OpenID Connect)
Authorization code grant with PKCE (OAuth 2.0) | OpenID Connect)
Authorization code grant with PAR (OAuth 2.0)
Implicit grant (OAuth 2.0) | OpenID Connect)
UMA grant (UMA)

You must compose the path to the authorize endpoint addressing the specific realm where the access code will be issued. For example, https://openam.example.com:8443/openam/oauth2/realms/root/realms/alpha/authorize.

The authorization endpoint supports the following parameters:

Parameter Description Required

Parameter	Description	Required
acr_values	The OpenID Connect authentication context class reference values.	No^(*)
claims	The user attributes to be returned in the ID token.	No
client_id	Uniquely identifies the application making the request.	Yes
code_challenge	The hashed value of the code verifier generated for the PKCE flow.	Yes^(*)
code_challenge_method	The method to derive the code challenge.	Yes^(*)
csrf	Links the request to the SSO token to protect against Cross-Site Request Forgery attacks.	Yes^(*)
decision	Specifies whether the resource owner consents to the requested access.	Yes^(*)
id_token_hint	ID token previously issued by AM that is passed as a hint about the end user’s session with the client.	No^(*)
login_hint	String value that can be set to the ID the user uses to log in.	No^(*)
nonce	String value that associates the client session with the ID token.	No^(*)
prompt	Specifies whether AM should prompt the end user for authentication and consent.	No^(*)
redirect_uri	The URI to return the resource owner to after authorization is complete.	No
response_mode	Specifies the mechanism for returning response parameters.	No
response_type	The type of response expected from the authorization server.	Yes
request	The JWT request object.	Yes
request_uri	For PAR or OIDC flows, a reference to JWT request object(s).	No^(*)
save_consent	Specifies whether AM should store a resource owner’s consented scopes.	No
scope	The scopes linked to the permissions requested by the client from the resource owner.	No
service / module	The authentication `module` instance, or for `service`, the tree or chain to use when authenticating the resource owner.	No
state	The value to maintain state between the request and the callback.	No
ui_locales	The end user’s preferred languages for the user interface.	No^(*)

acr_values

The OpenID Connect authentication context class reference values.

No^(*)

claims

The user attributes to be returned in the ID token.

client_id

Uniquely identifies the application making the request.

Yes

code_challenge

The hashed value of the code verifier generated for the PKCE flow.

Yes^(*)

code_challenge_method

The method to derive the code challenge.

Yes^(*)

csrf

Links the request to the SSO token to protect against Cross-Site Request Forgery attacks.

Yes^(*)

decision

Specifies whether the resource owner consents to the requested access.

Yes^(*)

id_token_hint

ID token previously issued by AM that is passed as a hint about the end user’s session with the client.

No^(*)

login_hint

String value that can be set to the ID the user uses to log in.

No^(*)

nonce

String value that associates the client session with the ID token.

No^(*)

prompt

Specifies whether AM should prompt the end user for authentication and consent.

No^(*)

redirect_uri

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

response_mode

Specifies the mechanism for returning response parameters.

response_type

The type of response expected from the authorization server.

Yes

request

The JWT request object.

Yes

request_uri

For PAR or OIDC flows, a reference to JWT request object(s).

No^(*)

save_consent

Specifies whether AM should store a resource owner’s consented scopes.

scope

The scopes linked to the permissions requested by the client from the resource owner.

service / module

The authentication module instance, or for service, the tree or chain to use when authenticating the resource owner.

state

The value to maintain state between the request and the callback.

ui_locales

The end user’s preferred languages for the user interface.

No^(*)

^(*) Only for the scenarios specified in the parameter details.

Parameter details

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

For PAR flows, or to adhere to the JAR specification, this value must match the client_id claim in the request object.

Required: Yes.

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.

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, 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, when requesting an authorization code during the Authorization code grant with PKCE flow.

code_challenge_method: Contains the method used to derive the code challenge. Possible values are plain and S256. When unset, it defaults to plain.

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

Specifies the mechanism for returning response parameters.

Valid response mode values include:

query, to return parameters encoded in the query string. This is the default for the authorization code grant flows (response_type=code).
fragment, to return parameters encoded in the URL fragment. This is the default for the implicit grant (response_type=token).
jwt, to return parameters encoded in a JWT; in a query for the code response type, or appended to the fragment for the token response type.
JWT-based response mode
AM supports JWT-secured authorization response (JARM), which lets clients receive the authorization response parameters packaged in a signed, and optionally encrypted, JWT.

The algorithms used to secure the JWT are defined in the client configuration.

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 claims issuer (the authorization server that generated the response)
- aud, the audience (the client ID of the response destination)
- exp, the expiration of the JWT (a maximum of 10 minutes is recommended)
In the case of an error, the JWT returns an error, a state value if specified by the client, and an error description.

For more information, see JWT-Secured Authorization Response Mode for OAuth 2.0 (JARM).
fragment.jwt, to return a JWT in a fragment.
query.jwt, to return a JWT in a query parameter.

This mode must not be used with response types that contain token or id_token, unless the response JWT is encrypted to prevent leakage in the URL.

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.

For more information, see Response Modes.

To see a list of the supported response modes in AM, query /oauth2/.well-known/openid-configuration and search for response_modes_supported in the output.

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.

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.

It is strongly recommended that users are required to authenticate using trees, not chains, when prompt=login leads to reauthentication at the same level. This recreates the session and mitigates the threat of session fixation attacks.

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

Specifies a base64url-encoded JSON Web Token (JWT) whose claims are the parameters required for OpenID Connect flows or to comply with the JAR specification. This JWT is called the request object.

The validation rules applied to the request object depend upon the specification that is used to process the request.

OIDC requests that specify a request object are validated according to the specification set in the OAuth 2.0 provider configuration, OIDC or JAR. For details, see the Request Object Processing Specification configuration property.

JAR specification rules

The following rules apply if the OAuth 2.0 authorization JWT request does not contain OIDC-specific parameters, or if an Open ID Connect JWT request is configured for JAR processing:

The request object must be signed, and optionally, encrypted.
The client_id parameter must be defined in the request object. The value must match the client_id specified as a query parameter in the request itself.
Only the request object parameters are used for the authorization request, even when the same parameters are defined as query parameters.

OIDC specification rules

The following rules apply for OIDC JWT requests with default request object processing configuration (OIDC):

The request object does not need to be signed or encrypted.
You may send query string parameters and a request object in the same request to AM. This is useful to keep sensitive information protected in the request object, and to ensure that parameters whose value changes frequently, such as nonce and state, remain visible and mutable across calls.

The value of the claims included in the request object supersede the value passed as query string parameters,
You must include the value of response_type and client_id as query string parameters, regardless of whether they are included in the request object or not.

If they are included in the request object, their values must match those passed as query string parameters.
Include the openid scope as a query string parameter, regardless of whether it is included in the request object or not.

The value of the scope claim may differ from that passed as a query parameter. This is useful to protect application-related scopes inside the request object, yet allows AM to process the request as part of an OpenID Connect flow.

Regardless of which specification is adhered to, you must 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.

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

These rules also apply if you’re passing the request object as a reference using the request_uri parameter.

Example request object

The following is an example of a request object.

Note that it includes both iss and aud, as well as the nbf and exp JWT claims, in addition to the OpenID Connect claims. However, AM ignores keys specified in JWT headers, such as `jku` and `jwe`.

{
  "iss": "myClient",
  "nbf": 1594140030,
  "client_id": "myClient",
  "aud": "https://openam.example.com:8443/openam/oauth2/realms/root/realms/alpha",
  "redirect_uri": "https://www.example.com:8443",
  "exp": 1594140390,
  "scope" : "openid profile",
  "claims":
    {
      "id_token":
        {
          "acr":
            {
               "essential": true,
               "values": ["example_tree1","example_tree2"]
            }
        }
    }
}

If you are compressing the JWT, note that by default, AM rejects JWTs that expand to a size larger than 32 KiB (32768 bytes).

For more information, see Control the size of compressed JWTs

To retrieve a list of public keys clients can use to encrypt this JWT, make a request to the realm’s /oauth2/connect/jwk_uri.

The following is an example call sending the request object as value:

https://openam.example.com:8443/openam/oauth2/realms/root/authorize? \
&request=eyJhbGciOiJSUzI1NiIsImtpZCI6ImsyYmRjIn0.ew0KICJpc3MiOiAiczZCaGRSa3.... \
&client_id=myClient \
&scope=openid profile\
&response_type=code%20id_token \
&nonce=abc123 \
&state=123abc

Note that the URL is split for readability purposes.

Required: No. OIDC flows and JAR specification requests only.

request_uri

Specifies a reference to one or more base64-encoded JWTs, according to the context of the authorization flow:

For PAR flows, this parameter references the request data specified when the PAR endpoint was invoked by the client.

AM rejects the authorization request if the request URI has expired.
For OIDC flows and JAR requests, this parameter specifies an array of URIs from which AM can retrieve JWTs whose claims constitute the request parameters. For information about the JWT, see the request parameter.

The URI must be pre-registered in the Requests uris field (Realms > Realm Name > Applications > OAuth 2.0 > Clients > Client Name > Advanced).

Each of the request URIs must not exceed 512 ASCII characters and must use either HTTP or HTTPS. For example, https://www.example.com:8443/JTWs/myJWT.

AM caches the retrieved JWT to avoid fetching it too often. To force AM 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.

Required: No, only if PAR is required. PAR, OIDC and JAR specification requests only.

AM 7.2.2

/oauth2/authorize