Access Management 7.2.2

/oauth2/access_token

The /oauth2/access_token endpoint is the OAuth 2.0 token endpoint as defined in RFC 6749. Use this endpoint to acquire an access or refresh token when using the following flows:

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

The token endpoint supports the following parameters:

grant_type

Specifies the type of grant to send to the authorization server to acquire an access token.

The following types are supported:

  • password, for the Resource Owner Credentials grant flow.

  • authorization_code, for the Authorization Code Grant (OAuth 2.0) | OpenID Connect) grant flows.

  • client_credentials, for the Client credentials grant flow.

  • urn:ietf:params:oauth:grant-type:device_code, for the Device flow. An earlier specification, http://oauth.net/grant_type/device/1.0, is also supported.

  • urn:openid:params:grant-type:ciba, for the Client Initiated Backchannel Authentication (CIBA) flow. For more information, see Backchannel request grant.

  • urn:ietf:params:oauth:grant-type:uma-ticket, for the UMA grant flow. For more information, see UMA grant flow.

  • refresh_token, to refresh an access token. For more information, see Refresh tokens.

  • urn:ietf:params:oauth:grant-type:saml2-bearer, for the SAML v2.0 Profile for Authorization grant. For more information, see SAML v2.0 profile for authorization grant.

  • urn:ietf:params:oauth:grant-type:jwt-bearer, for the JWT Profile for OAuth 2.0 Authorization grant. For more information, see JWT profile for OAuth 2.0 authorization grant.

  • urn:ietf:params:oauth:grant-type:token-exchange, for the Token Exchange flows. For more information, see Token exchange flows.

Required: Yes

client_id

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

Required: Yes.

client_secret

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

Required: A form of password or credentials is required for confidential clients. However, the use of the client_secret parameter depends on the client authentication method used. For more information, see OAuth 2.0 client authentication.

cnf_key

Specifies either a base64-encoded JWK used to support JWK-based proof-of-possession or a base64-encoded SHA-256 hash of the DER-encoding of a full X.509 certificate to support Certificate-bound proof-of-possession.

Do not use in conjunction with the client_secret parameter.

Required: Yes, when using JWK proof-of-possession.

username

Specifies the username of the resource owner during the Resource Owner Credentials grant flow.

Required: Yes, when grant_type is set to password.

password

Specifies the password of the resource owner during the Resource Owner Credentials grant flow.

Required: Yes, when grant_type is set to password.

code

Specifies the authorization code obtained during the authorization code grant and authorization code with PKCE grant flows.

Required: Yes, when grant_type is set to authorization_code.

device_code

Specifies a device code obtained when requesting a user code during the device flow.

Required: Yes, when grant_type is set to urn:ietf:params:oauth:grant-type:device_code.

client_assertion

Specifies the signed JWT that the client uses as a credential when using the JWT bearer client authentication method.

For more information, see OAuth 2.0 client authentication.

Required: Yes, when using the JWT bearer client authentication method.

client_assertion_type

Specifies the type of assertion when the client is authenticating to the authorization server using JWT bearer client authentication. Do not use with other client authentication methods.

Set it to urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer.

For more information, see OAuth 2.0 client authentication.

Required: Yes, when using the JWT bearer client authentication method.

assertion

Specifies a SAML v2.0 assertion. The assertion must be first base64-encoded, and then URL encoded. For more information, see SAML v2.0 profile for authorization grant.

Required: Yes, when using the SAML v2.0 Profile for Authorization grant.

redirect_uri

The URI to return the resource owner to after authorization is complete. Must match the redirect_uri configured in the client profile registered with AM, and the redirect_uri set when requesting authorization.

The URI must be an absolute URI, and must not contain a fragment component. For example, https://www.example.com:443/callback/.

Required: Yes, when grant_type is set to authorization_code and it was included in the authorization code grant, and during the Implicit grant.

code_verifier

Specifies a random string that correlates the authorization request to the token request in the Authorization Code with PKCE grant flow.

Required: Yes, when requesting an access code in the Authorization Grant with PKCE flow.

subject_token

The original token to be exchanged as part of delegation or impersonation Token Exchange flows.

Required: Yes, when requesting tokens during the delegation and/or impersonation Token Exchange flows.

subject_token_type

The type of the subject token. Possible values are:

  • urn:ietf:params:oauth:token-type:access_token

  • urn:ietf:params:oauth:token-type:id_token

Required: Yes, when requesting tokens during the delegation and/or impersonation Token Exchange flows.

actor_token

The original token that acts on behalf of the subject token during delegation Token Exchange flows.

Required: Yes, when requesting a token in the delegation Token Exchange flow.

actor_token_type

The type of the actor token. Possible values are:

  • urn:ietf:params:oauth:token-type:access_token

  • urn:ietf:params:oauth:token-type:id_token

Required: Yes, when requesting a token in the delegation Token Exchange flow.

requested_token_type

The type of token requested as part of an impersonation or delegation Token Exchange flow.

If not added to the request, it defaults to access tokens.

Possible values are:

  • urn:ietf:params:oauth:token-type:access_token

  • urn:ietf:params:oauth:token-type:id_token

Required: No, but adding it is highly recommended when requesting tokens during the delegation and/or impersonation Token Exchange flows.

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.

Note that some grant flows, such as the Authorization Code grant, do not call the token endpoint with the scope. The scope is already defined in the authorization code. For details, see the specific grant flow documentation in OAuth 2.0 grant flows.

For more information, see OAuth 2.0 scopes and Claims.

Required: No.

auth_chain

Overrides the authentication tree or chain configured for the realm, and also the tree or chain configured in the OAuth 2.0 service in the realm, when supporting the Resource Owner Credentials grant flow.

By default, the Resource Owner Password Credentials grant flow uses the default authentication tree or chain in the relevant realm.

The selected tree or chain must be configured for requiring username and password only, without UI-based interaction from the resource owner. For example, using the ldapService chain or Example tree. If this is not the case, the server returns an HTTP 500 error message.

Required: No.

refresh_token

Specifies the refresh token that will be used to refresh an access token.

For more information, see Refresh tokens.

Required: No, only when refreshing access tokens.