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

client_id

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

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 with PKCE grant 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 with PKCE grant 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

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 OAuth2 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 Adding 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 the OpenID Connect 1.0 Guide.

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

As per the OpenID Connect specification, this parameter specifies a base64url-encoded JWT whose claims are the query parameters required for the OpenID Connect flow. This JWT is called the request object.

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, but some claims/parameters must be configured and sent in a certain manner for the request to be valid. 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.

You must follow these rules as well if you're passing the request object as a reference using the request_uri parameter.

The following is an example of a request object. Note that it includes the iss and aud JWT claims in addition to the OpenID Connect claims:

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

The JWT can be signed and/or encrypted, in which case you should always include the iss and aud parameters in the JWT as shown in the example. However, AM ignores keys specified in JWT headers, such as jku and jwe.

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 "Controlling the Maximum 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 JWK URI endpoint.

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

request_uri

Specifies an array of URIs from which AM can retrieve a base64-encoded JWTs whose claims are the request parameters required for the OpenID Connect flow. 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. OIDC flows only.