/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)
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 theid_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
andS256
. When unset, it defaults toplain
.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, orservice
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
andprompt
parameters to be set tonone
.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
orbob@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 namedoidcLoginHint
, 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 theid_token_hint
and theresponse_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 theservice
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
andstate
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
andaud
parameters in the JWT as shown in the example. However, AM ignores the content of non-string JWT header parameters, such asjku
andjwe
.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.