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

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/subrealm1/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.

  • token, to request an access token.

  • id_token, to request an ID token.

  • code token, to request an authorization code and an access token.

  • token id_token, to request an access token and an ID token.

  • code id_token, to request an authorization code and an ID token.

  • code token id_token, to request an authorization code, an access token, and an ID token.

  • 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, 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, 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, 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 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 "Retrieving Session State without the Check Session Endpoint".

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.

  • 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 OIDC specification, this parameter specifies a base64url-encoded JWT whose claims are the request parameters required for the OpenID Connect flow. When this parameter is used, the contents of the JWT supersede those passed as HTTP parameters. However, you can use a combination of the request parameter and HTTP parameters in the same request to AM.

This combination is useful when the contents of the JWT are not expected to change, but parameters like nonce and state are. For example:

https://openam.example.com:8443/openam/oauth2/realms/root/authorize? \
&request=eyJhbGciOiJSUzI1NiIsImtpZCI6ImsyYmRjIn0.ew0KICJpc3MiOiAiczZCaGRSa3.... \
&nonce=abc123 \
&state=123abc

Note that the URL is split for readability purposes. The request parameter specifies the JWT containing, at least, all required parameters for the OIDC request. For example:

{
  "iss": "myClient",
  "aud": "https://openam.example.com:8443/openam",
  "response_type": "code id_token",
  "client_id": "myClient",
  "redirect_uri": "https://www.example.com:8443",
  "scope": "openid",
  "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 the content of non-string JWT header parameters, such as jku and jwe.

To retrieve a list of public keys clients can use to encrypt this JWT, make a request to the realm's JWK URI endpoint.

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.

Read a different version of :