Guide showing you how to use OAuth 2.0 with ForgeRock® Access Management (AM). ForgeRock Access Management provides intelligent authentication, authorization, federation, and single sign-on functionality.

Perform the steps in this procedure to set up the service with the Configure OAuth Provider wizard:

1. In the AM console, navigate to Realms > Realm Name > Dashboard > Configure OAuth Provider > Configure OAuth 2.0.

2. On the Configure OAuth2 page, select the Realm for the provider service.

3. (Optional) If necessary, adjust the lifetimes for authorization codes (a lifetime of 10 minutes or less is recommended in RFC 6749), access tokens, and refresh tokens.

4. (Optional) Select Issue Refresh Tokens if you want the provider to supply a refresh token when returning an access token.

5. (Optional) Select Issue Refresh Tokens on Refreshing Access Tokens if you want the provider to supply a new refresh token when refreshing an access token.

6. (Optional) Keep the default scope implementation, whereby scopes are taken to be resource owner profile attribute names, unless you have a custom scope validator implementation.

   If you have a custom scope validator implementation, copy it to the AM classpath, for example /path/to/tomcat/webapps/openam/WEB-INF/lib/, and specify the class name in the Scope Implementation Class field. For an example, see "Customizing OAuth 2.0 Scope Handling".

7. Select Create to save your changes. If an OAuth2 provider service already exists, it will be overwritten.

   AM creates an OAuth2 provider service.

If you use an external identity repository where resource owners log in not with their user ID, but instead with their mail address or some other profile attribute, you must configure AM authentication to allow it.

For example, to configure AM so OAuth 2.0 resource owners can log in using their email address, stored on the LDAP profile attribute, mail, perform the following steps:

1. In the OAuth2 provider Advanced tab, add the LDAP profile attribute to the User Profile Attribute(s) the Resource Owner is Authenticated On list, and save your changes.

2. Navigate to Realms > Realm Name > Identity Stores > Identity Store Name > Authentication Configuration.

3. Set the value of the Authentication Naming Attribute field to the LDAP attribute required. For example, mail.

4. Create an LDAP authentication module or an LDAP decision node to use with the identity repository.

   In both cases, configure the following fields:

   1. In the Attribute Used to Retrieve User Profile field, set the attribute to mail.

   2. In the Attributes Used to Search for a User to be Authenticated list, add the mail attribute.

   3. Save your changes.

5. Ensure the resource owners use the authentication tree or chain where you configured the LDAP module or node.

   Specify the chain or tree by using one or more of the methods below. AM checks for the configured value in the following order, using the first value found:

   1. For a specific access token REST request.

      Set the auth_chain parameter.

   2. Individually for a realm, overriding the realm-level setting below.

      Navigate to Realms > Realm Name > Services > OAuth2 Provider > Advanced, and set the Password Grant Authentication Service property.

   3. Individually for a realm.

      Navigate to Realms > Realm Name > Authentication > Settings > Core, and set the Organization Authentication Configuration property.

   4. Globally, for all realms.

      Navigate to Configure > Authentication > Core Attributes > Core, and set the Organization Authentication Configuration property.

   For more information, see "Configuring the Default Authentication Tree or Chain" in the Authentication and Single Sign-On Guide.

   For more information about authentication trees and chains, see "Implementing Authentication" in the Authentication and Single Sign-On Guide.

Use the following procedure to create an OAuth 2.0 client profile:

• In the AM console, navigate to Realms > Realm Name > Applications > OAuth 2.0. Click Add Client, and then provide the Client ID, client secret, redirection URIs, scope(s), and default scope(s). Finally, click Create to create the profile.

  To configure the client, see "To Configure an OAuth 2.0 Client Profile".

1. In the AM console, navigate to Realms > Realm Name > Applications > OAuth 2.0 > Client Name to open the OAuth 2.0 Client page.

2. Adjust the configuration as needed using the inline help for hints, and also the documentation section "OAuth 2.0 and OpenID Connect 1.0 Client Settings".

   Examine the client type option. An important decision to make at this point is whether your client is a confidential client or a public client. This depends on whether your client can keep its credentials confidential, or whether its credentials can be exposed to the resource owner or other parties. If your client is a web-based application running on a server, such as the AM OAuth 2.0 client, then you can keep its credentials confidential. If your client is a user-agent based client, such as a JavaScript client running in a browser, or a native application installed on a device used by the resource owner, then the credentials can be exposed to the resource owner or other parties.

3. When finished, save your work.

1. In the AM console, navigate to Realms > Realm Name > Applications > OAuth 2.0.

   • To create a new OAuth 2.0 client profile group:

     On the Groups tab, select Add Group, and then provide the Group ID. Finally, select Create.

   • To configure a OAuth 2.0 client profile group:

     On the Groups tab, select the group to configure.

2. Adjust the configuration as needed using the inline help for hints, and also the documentation section "OAuth 2.0 and OpenID Connect 1.0 Client Settings".

3. When finished, save your work.

   If the group is assigned to one or more OAuth 2.0 client profiles, changes to inherited properties in the group are also applied to the client profile.

   To assign a group to an OAuth 2.0 client profile, see "To Assign a Group to an OAuth 2.0 Client Profile and Inherit Properties".

1. In the AM console, navigate to Realms > Realm Name > Applications > OAuth 2.0. On the Clients tab, select the client ID to which a group is to be assigned.

2. On the Core tab, select the group to assign to the client from the Group drop-down.

   Warning

   Adding or changing an assigned group will refresh the settings page. Unsaved property values will be lost.

   The inheritance (padlock) icons appear next to properties that support inheriting their value from the assigned group. Not all properties can inherit their value, for example, the Client secret property.

   OAuth 2.0 Client Profile Group Inheritance

   
   
   

3. Inherit a property value from the group by selecting the inheritance button (the open padlock icon) next to the property.

   The value will be inherited from the group and the field will be locked.

   Note

   If you change the group, properties with inheritance enabled will inherit the value from the new group.

   If you remove the group, inherited property values are written to the OAuth 2.0 client profile, and become editable.

4. When finished, save your work.

This procedure assumes the following configuration:

For more information, see "Registering OAuth 2.0 Clients With the OAuth 2.0 Provider Service".

Perform the steps in this procedure to obtain an authorization code using a browser:

1. The client redirects the resource owner's user-agent to the authorization server's authorization endpoint specifying, at least, the following form parameters:

   • client_id=your_client_id

   • response_type=code

   • redirect_uri=your_redirect_uri

   For information about the parameters supported by the /oauth2/authorize endpoint, see "/oauth2/authorize".

   If the OAuth 2.0 provider is configured for a subrealm rather than the top-level realm, you must specify it in the endpoint. For example, if the OAuth 2.0 provider is configured for the /customers realm, then use /oauth2/realms/root/realms/customers/authorize.

   For example:

   https://openam.example.com:8443/openam/oauth2/realms/root/authorize \
   ?client_id=myClient \
   &response_type=code \
   &scope=write \
   &state=abc123 \
   &redirect_uri=https://www.example.com:443/callback

   Note that the URL is split and spaces have been added for readability purposes and that the scope and state parameters have been included. Scopes are not required, since they can be configured by default in the authorization server and the client, and have been added only as an example. The state parameter is added to protect against CSRF attacks.

2. The resource owner authenticates to the authorization server, for example, using the credentials of the demo user. In this case, they log in using the default chain or tree configured for the realm.

   After logging in, the authorization server presents the AM consent screen:

   OAuth 2.0 Consent Screen

   
   
   

3. The resource owner selects the Allow button to grant consent for the write scope.

   The authorization server redirects the resource owner to the URL specified in the redirect_uri parameter.

4. Inspect the URL in the browser. It contains a code parameter with the authorization code the authorization server has issued. For example:

   http://www.example.com/?code=g5B3qZ8rWzKIU2xodV_kkSIk0F4&scope=write&iss=https%3A%2F%2Fopenam.example.com%3A8443%2Fopenam%2Foauth2&state=abc123&client_id=myClient

5. The client performs the steps in "To Exchange an Authorization Code for an Access Token" to exchange the authorization code for an access token.

This procedure assumes the following configuration:

For more information, see "Registering OAuth 2.0 Clients With the OAuth 2.0 Provider Service".

Perform the steps in this procedure to obtain an authorization code without using a browser:

1. The resource owner logs in to the authorization server, for example, using the credentials of the demo user. For example:

   $ curl \
   --request POST \
   --header "Content-Type: application/json" \
   --header "X-OpenAM-Username: demo" \
   --header "X-OpenAM-Password: changeit" \
   --header "Accept-API-Version: resource=2.0, protocol=1.0" \
   'https://openam.example.com:8443/openam/json/realms/root/authenticate'
   {
       "tokenId":"AQIC5wM...TU3OQ*",
       "successUrl":"/openam/console",
       "realm":"/"
   }

2. The client makes a POST call to the authorization server's authorization endpoint, specifying the SSO token of the demo in a cookie and, at least, the following parameters:

   • client_id=your_client_id

   • response_type=code

   • redirect_uri=your_redirect_uri

   • decision=allow

   • csrf=demo_user_SSO_token

   For information about the parameters supported by the /oauth2/authorize endpoint, see "/oauth2/authorize".

   If the OAuth 2.0 provider is configured for a subrealm rather than the top-level realm, you must specify it in the endpoint. For example, if the OAuth 2.0 provider is configured for the /customers realm, then use /oauth2/realms/root/realms/customers/authorize.

   For example:

   $ curl --dump-header - \
   --request POST \
   --Cookie "iPlanetDirectoryPro=AQIC5wM...TU3OQ*" \
   --data "scope=write" \
   --data "response_type=code" \
   --data "client_id=myClient" \
   --data "csrf=AQIC5wM...TU3OQ*" \
   --data "redirect_uri=https://www.example.com:443/callback" \
   --data "state=abc123" \
   --data "decision=allow" \
   "https://openam.example.com:8443/openam/oauth2/realms/root/authorize"

   Note that the scope and the state parameters have been included. Scopes are not required, since they can be configured by default in the authorization server and the client, and have been added only as an example. The state parameter is added to protect against CSRF attacks.

   If the authorization server is able to authenticate the user and the client, it returns an HTTP 302 response with the authorization code appended to the redirection URL:

   HTTP/1.1 302 Found
   Server: Apache-Coyote/1.1
   X-Frame-Options: SAMEORIGIN
   Pragma: no-cache
   Cache-Control: no-store
   Date: Mon, 30 Jul 2018 11:42:37 GMT
   Accept-Ranges: bytes
   Location: https://www.example.com:443/callback?code=g5B3qZ8rWzKIU2xodV_kkSIk0F4&scope=write&iss=https%3A%2F%2Fopenam.example.com%3A8443%2Fopenam%2Foauth2&state=abc123&client_id=myClient
   Vary: Accept-Charset, Accept-Encoding, Accept-Language, Accept
   Content-Length: 0

3. Perform the steps in "To Exchange an Authorization Code for an Access Token" to exchange the authorization code for an access token.

Perform the steps in the following procedure to exchange an authorization code for an access token:

1. Ensure the client has obtained an authorization code by performing the steps in either "To Obtain an Authorization Code Using a Browser in the Authorization Code Grant Flow" or "To Obtain an Authorization Code Without Using a Browser in the Authorization Code Grant Flow".

2. The client creates a POST request to the token endpoint in the authorization server specifying, at least, the following parameters:

   • grant_type=authorization_code

   • code=your_authorization_code

   • redirect_uri=your_redirect_uri

   For information about the parameters supported by the /oauth2/access_token endpoint, see "/oauth2/access_token".

   Confidential clients can authenticate to the OAuth 2.0 endpoints in several ways. This example uses the following form parameters:

   • client_id=your_client_id

   • client_secret=your_client_secret

   For more information, see "Authenticating OAuth 2.0 Clients".

   If the OAuth 2.0 provider is configured for a subrealm rather than the top-level realm, you must specify it in the endpoint. For example, if the OAuth 2.0 provider is configured for the /customers realm, then use /oauth2/realms/root/realms/customers/access_token.

   For example:

   $ curl --request POST \
   --data "grant_type=authorization_code" \
   --data "code=g5B3qZ8rWzKIU2xodV_kkSIk0F4" \
   --data "client_id=myClient" \
   --data "client_secret=forgerock" \
   --data "redirect_uri=https://www.example.com:443/callback" \
   "https://openam.example.com:8443/openam/oauth2/realms/root/access_token"

   The client_id and the redirection_uri parameters specified in this call must match those used as part of the authorization code request, or the authorization server will not validate the code.

   The authorization server returns an access token in the access_token property. For example:

   {
     "access_token": "sbQZuveFumUDV5R1vVBl6QAGNB8",
     "scope": "write",
     "token_type": "Bearer",
     "expires_in": 3599
   }

   Tip

   The authorization server can also issue refresh tokens at the same time the access tokens are issued. For more information, see "Managing OAuth 2.0 Refresh Tokens".

The client application must be able to generate a code verifier and a code challenge. For details, see the PKCE standard (RFC 7636). The information contained in this procedure is for example purposes only:

1. The client generates the code challenge and the code verifier. Creating the challenge using a SHA-256 algorithm is mandatory if the client supports it, as per the RFC 7636 standard.

   The following is an example of a code verifier and code challenge written in JavaScript:

   function base64URLEncode(words) {
      return CryptoJS.enc.Base64.stringify(words)
      .replace(/\+/g, '-')
      .replace(/\//g, '_')
      .replace(/=/g, '');
   }
   var verifier = base64URLEncode(CryptoJS.lib.WordArray.random(50));
   var challenge = base64URLEncode(CryptoJS.SHA256(verifier));

   This example generates values such as ZpJiIM_G0SE9WlxzS69Cq0mQh8uyFaeEbILlW8tHs62SmEE6n7Nke0XJGx_F4OduTI4 for the code verifier and j3wKnK2Fa_mc2tgdqa6GtUfCYjdWSA5S23JKTTtPF8Y for the code challenge. These values will be used in subsequent procedures.

   The client is now ready to request an authorization code.

2. The client performs the steps in one of the following procedures to request an authorization code:

   • "To Obtain an Authorization Code Using a Browser in the Authorization Code Grant with PKCE Flow"

   • "To Obtain an Authorization Code Without Using a Browser in the Authorization Code Grant with PKCE Flow"

This procedure assumes the following configuration:

For more information, see "Registering OAuth 2.0 Clients With the OAuth 2.0 Provider Service".

Perform the steps in this procedure to obtain an authorization code using a browser:

1. The client redirects the resource owner's user-agent to the authorization server's authorization endpoint specifying, at least, the following query parameters:

   • client_id=your_client_id

   • response_type=code

   • redirect_uri=your_redirect_uri

   • code_challenge=your_code_challenge

   • code_challenge_method=S256

   For information about the parameters supported by the /oauth2/authorize endpoint, see "/oauth2/authorize".

   If the OAuth 2.0 provider is configured for a subrealm rather than the top-level realm, you must specify it in the endpoint. For example, if the OAuth 2.0 provider is configured for the /customers realm, then use /oauth2/realms/root/realms/customers/authorize.

   For example:

   https://openam.example.com:8443/openam/oauth2/realms/root/authorize \
   ?client_id=myClient \
   &response_type=code \
   &scope=write \
   &redirect_uri=https://www.example.com:443/callback \
   &code_challenge=j3wKnK2Fa_mc2tgdqa6GtUfCYjdWSA5S23JKTTtPF8Y \
   &code_challenge_method=S256 \
   &state=abc123

   Note that the URL is split and spaces have been added for readability purposes and that the scope and state parameters have been included. Scopes are not required, since they can be configured by default in the authorization server and the client, and have been added only as an example. The state parameter is added to protect against CSRF attacks.

2. The resource owner authenticates to the authorization server, for example, using the credentials of the demo user. In this case, they log in using the default chain or tree configured for the realm.

   After logging in, the authorization server presents the AM consent screen:

   OAuth 2.0 Consent Screen

   
   
   

3. The resource owner selects the Allow button to grant consent for the write scope.

   The authorization server redirects the resource owner to the URL specified in the redirect_uri parameter.

4. Inspect the URL in the browser. It contains a code parameter with the authorization code the authorization server has issued. For example:

   http://www.example.com/?code=ZNSDo8LrsI2w-6NOCYKQgvDPqtg&scope=write&iss=https%3A%2F%2Fopenam.example.com%3A8443%2Fopenam%2Foauth2&state=abc123&client_id=myClient

5. The client performs the steps in "To Exchange an Authorization Code for an Access Token" to exchange the authorization code for an access token.

This procedure assumes the following configuration:

For more information, see "Registering OAuth 2.0 Clients With the OAuth 2.0 Provider Service".

Perform the steps in this procedure to obtain an authorization code:

1. The resource owner logs in to the authorization server, for example, using the credentials of the demo user. For example:

   $ curl \
   --request POST \
   --header "Content-Type: application/json" \
   --header "X-OpenAM-Username: demo" \
   --header "X-OpenAM-Password: changeit" \
   --header "Accept-API-Version: resource=2.0, protocol=1.0" \
   'https://openam.example.com:8443/openam/json/realms/root/authenticate'
   {
       "tokenId":"AQIC5wM...TU3OQ*",
       "successUrl":"/openam/console",
       "realm":"/"
   }

2. The client makes a POST call to the authorization server's authorization endpoint specifying in a cookie SSO token of the demo and, at least, the following parameters:

   • client_id=your_client_id

   • response_type=code

   • redirect_uri=your_redirect_uri

   • decision=allow

   • csrf=demo_user_SSO_token

   • code_challenge=your_code_challenge

   • code_challenge_method=S256

   For information about the parameters supported by the /oauth2/authorize endpoint, see "/oauth2/authorize".

   If the OAuth 2.0 provider is configured for a subrealm rather than the top-level realm, you must specify it in the endpoint. For example, if the OAuth 2.0 provider is configured for the /customers realm, then use /oauth2/realms/root/realms/customers/authorize.

   For example:

   $ curl --dump-header - \
   --request POST \
   --Cookie "iPlanetDirectoryPro=AQIC5wM...TU3OQ*" \
   --data "redirect_uri=https://www.example.com:443/callback" \
   --data "scope=write" \
   --data "response_type=code" \
   --data "client_id=myClient" \
   --data "csrf=AQIC5wM...TU3OQ*" \
   --data "state=abc123" \
   --data "decision=allow" \
   --data "code_challenge=j3wKnK2Fa_mc2tgdqa6GtUfCYjdWSA5S23JKTTtPF8Y" \
   --data "code_challenge_method=S256" \
   "https://openam.example.com:8443/openam/oauth2/realms/root/authorize"

   Note that the scope and the state parameters have been included. Scopes are not required, since they can be configured by default in the authorization server and the client, and have been added only as an example. The state parameter is added to protect against CSRF attacks.

   If the authorization server is able to authenticate the user and the client, it returns an HTTP 302 response with the authorization code appended to the redirection URL:

   HTTP/1.1 302 Found
   Server: Apache-Coyote/1.1
   X-Frame-Options: SAMEORIGIN
   Pragma: no-cache
   Cache-Control: no-store
   Date: Mon, 30 Jul 2018 11:42:37 GMT
   Accept-Ranges: bytes
   Location: http://www.example.com?code=g5B3qZ8rWzKIU2xodV_kkSIk0F4&scope=write&iss=https%3A%2F%2Fopenam.example.com%3A8443%2Fopenam%2Foauth2&state=abc123&client_id=myClient
   Vary: Accept-Charset, Accept-Encoding, Accept-Language, Accept
   Content-Length: 0

3. Perform the steps in "To Exchange an Authorization Code for an Access Token in the Authorization Code Grant Flow with PKCE Flow" to exchange the authorization code for an access token.

Perform the steps in the following procedure to exchange an authorization code for an access token:

1. Ensure the client has obtained an authorization code by performing the steps in either "To Obtain an Authorization Code Using a Browser in the Authorization Code Grant with PKCE Flow" or "To Obtain an Authorization Code Without Using a Browser in the Authorization Code Grant with PKCE Flow".

2. The client creates a POST request to the token endpoint in the authorization server specifying, at least, the following parameters:

   • grant_type=authorization_code

   • code=your_authorization_code

   • client_id=your_client_id

   • redirect_uri=your_redirect_uri

   • code_verifier=your_code_verifier

   For information about the parameters supported by the /oauth2/access_token endpoint, see "/oauth2/access_token". For information about private client authentication methods, see "Authenticating OAuth 2.0 Clients".

   For example:

   $ curl --request POST \
   --data "grant_type=authorization_code" \
   --data "code=g5B3qZ8rWzKIU2xodV_kkSIk0F4" \
   --data "client_id=myClient" \
   --data "redirect_uri=https://www.example.com:443/callback" \
   --data "code_verifier=ZpJiIM_G0SE9WlxzS69Cq0mQh8uyFaeEbILlW8tHs62SmEE6n7Nke0XJGx_F4OduTI4" \
   "https://openam.example.com:8443/openam/oauth2/realms/root/access_token"

   The client_id and the redirection_uri parameters specified in this call must match those used as part of the authorization code request, or the authorization server will not validate the code.

   The authorization server returns an access token in the access_token property. For example:

   {
     "access_token": "sbQZuveFumUDV5R1vVBl6QAGNB8",
     "scope": "write",
     "token_type": "Bearer",
     "expires_in": 3599
   }

   Tip

   The authorization server can also issue refresh tokens at the same time the access tokens are issued. For more information, see "Managing OAuth 2.0 Refresh Tokens".

This procedure assumes the following configuration:

For more information, see "Registering OAuth 2.0 Clients With the OAuth 2.0 Provider Service".

Perform the steps in this procedure to obtain an access token using the Implicit grant:

1. The client makes a GET call to the authorization server's authorization endpoint specifying, at least, the following parameters:

   • client_id=your_client_id

   • response_type=token

   • redirect_uri=your_redirect_uri

   For information about the parameters supported by the /oauth2/authorize endpoint, see "/oauth2/authorize".

   If the OAuth 2.0 provider is configured for a subrealm rather than the top-level realm, you must specify it in the endpoint. For example, if the OAuth 2.0 provider is configured for the /customers realm, then use /oauth2/realms/root/realms/customers/authorize.

   For example:

   https://openam.example.com:8443/openam/oauth2/realms/root/authorize \
   ?client_id=myClient \
   &response_type=token \
   &scope=write \
   &redirect_uri=https://www.example.com:443/callback \
   &state=abc123

   Note that the URL is split for readability purposes and that the scope and state parameters have been included. Scopes are not required, since they can be configured by default in the authorization server and the client, and have been added only as an example. The state parameter is added to protect against CSRF attacks. Also, the redirection URI was not specified, and the URI defined in the client profile is used by default.

2. The resource owner logs in to the authorization server, for example, using the credentials of the demo user. In this case, they log in using the default chain or tree configured for the realm.

   After logging in, the authorization server presents the AM user interface consent screen:

   OAuth 2.0 Consent Screen

   
   
   

3. The resource owner selects the Allow button to grant consent for the write scope.

   The authorization server redirects the resource owner to the URL specified in the redirect_uri parameter.

4. Inspect the URL in the browser. It contains an access_token parameter with the access token the authorization server has issued. For example:

   https://www.example.com:443/callback#access_token=1i5IfaebiLnpyxFM4mcTSZSegb4&scope=write&redirect_uri%3Dhttps%3A%2F%2Fwww.example.com%3A8443%2Fcallback&iss=https%3A%2F%2Fopenam.example.com%3A8443%2Fopenam%2Foauth2&state=abc123&client_id=myClient

This procedure assumes the following configuration:

For more information, see "Registering OAuth 2.0 Clients With the OAuth 2.0 Provider Service".

Perform the steps in this procedure to obtain an access token using the Implicit grant:

1. The resource owner authenticates to the authorization server, for example, using the credentials of the demo user. For example:

   $ curl \
   --request POST \
   --header "Content-Type: application/json" \
   --header "X-OpenAM-Username: demo" \
   --header "X-OpenAM-Password: changeit" \
   --header "Accept-API-Version: resource=2.0, protocol=1.0" \
   'https://openam.example.com:8443/openam/json/realms/root/authenticate'
   {
       "tokenId":"AQIC5wM...TU3OQ*",
       "successUrl":"/openam/console",
       "realm":"/"
   }

2. The client makes a POST call to the authorization server's authorization endpoint, specifying the SSO token of the demo in a cookie and, at least, the following parameters:

   • client_id=your_client_id

   • response_type=token

   • decision=allow

   • csrf=demo_user_SSO_token

   • redirect_uri=your_redirect_uri

   For information about the parameters supported by the /oauth2/authorize endpoint, see "/oauth2/authorize".

   If the OAuth 2.0 provider is configured for a subrealm rather than the top-level realm, you must specify it in the endpoint. For example, if the OAuth 2.0 provider is configured for the /customers realm, then use /oauth2/realms/root/realms/customers/authorize.

   For example:

   curl --dump-header - \
   --Cookie "iPlanetDirectoryPro=AQIC5wM...TU3OQ*" \
   --request POST \
   --data "client_id=myClient" \
   --data "response_type=token" \
   --data "scope=write" \
   --data "state=123abc" \
   --data "decision=allow" \
   --data "csrf=AQIC5wM...TU3OQ*" \
   --data "redirect_uri=https://www.example.com:443/callback" \
   "https://openam.example.com:8443/openam/oauth2/realms/root/authorize"

   Note that the scope and state parameters have been included. Scopes are not required, since they can be configured by default in the authorization server and the client, and have been added only as an example. The state parameter is added to protect against CSRF attacks.

   If the authorization server is able to authenticate the user, it returns an HTTP 302 response with the access token appended to the redirection URI:

   1.1 302 Found
   Server: Apache-Coyote/1.1
   X-Frame-Options: SAMEORIGIN
   Pragma: no-cache
   Cache-Control: no-store
   Date: Wed, 22 Aug 2018 11:19:54 GMT
   Accept-Ranges: bytes
   Location: https://www.example.com:443/callback#access_token=PAsODWCvnb5W8uuBT12H62Rvmro&scope=write&redirect_uri%3Dhttps%3A%2F%2Fwww.example.com%3A8443%2Fcallback&iss=https%3A%2F%2Fopenam.example.com%3A8443%2Fopenam%2Foauth2&state=123abc&token_type=Bearer&expires_in=3599&client_id=myClient
   Vary: Accept-Charset, Accept-Encoding, Accept-Language, Accept
   Content-Length: 0

   In this case, the redirection URI was not specified in the command, and the URI defined in the client profile is used by default.

This procedure assumes the following configuration:

For more information, see"Registering OAuth 2.0 Clients With the OAuth 2.0 Provider Service".

Perform the following steps to obtain an access token using the ROPC grant flow:

1. The resource owner provides their credentials to the client. This is done outside the scope of this procedure.

2. The client creates a POST request to the authorization server's token endpoint specifying, at least, the following parameters:

   • username= your_resource_owner_username

   • password= your_resource_owner_password

   • grant_type=password

   For information about the parameters supported by the /oauth2/access_token endpoint, see "/oauth2/access_token".

   Private clients can authenticate to the OAuth 2.0 endpoints in several ways. This example uses the following form parameters:

   • client_id= your_client_id

   • client_secret= your_client_secret

   For more information, see"Authenticating OAuth 2.0 Clients".

   If the OAuth 2.0 provider is configured for a subrealm rather than the top-level realm, you must specify it in the endpoint. For example, if the OAuth 2.0 provider is configured for the /customers realm, then use /oauth2/realms/root/realms/customers/access_token.

   For example:

   $ curl --request POST \
   --data "grant_type=password" \
   --data "username=demo" \
   --data "password=changeit" \
   --data "scope=write" \
   --data "client_id=myClient" \
   --data "client_secret=forgerock" \
   "https://openam.example.com:8443/openam/oauth2/realms/root/access_token"

   Note that the scope parameter has been included. Scopes are not required, since they can be configured by default in the authorization server and the client, and have been added only as an example.

   The authorization server returns an access token in the access_token property. For example:

   {
     "access_token": "sbQZuveFumUDV5R1vVBl6QAGNB8",
     "scope": "write",
     "token_type": "Bearer",
     "expires_in": 3599
   }

   Tip

   The authorization server can also issue refresh tokens at the same time the access tokens are issued. For more information, see"Managing OAuth 2.0 Refresh Tokens".

This procedure assumes the following configuration:

For more information, see "Registering OAuth 2.0 Clients With the OAuth 2.0 Provider Service".

Perform the steps in this procedure to obtain an access token using the Client Credentials grant:

• The client makes a POST call to the authorization server's token endpoint specifying, at least, the following parameters:

  • grant_type=client_credentials

  For information about the parameters supported by the /oauth2/access_token endpoint, see "/oauth2/access_token".

  Private clients can authenticate to the OAuth 2.0 endpoints in several ways. This example uses the following form parameters:

  • client_id=your_client_id

  • client_secret=your_client_secret

  For more information, see "Authenticating OAuth 2.0 Clients".

  If the OAuth 2.0 provider is configured for a subrealm rather than the top-level realm, you must specify it in the endpoint. For example, if the OAuth 2.0 provider is configured for the /customers realm, use /oauth2/realms/root/realms/customers/access_token.

  For example:

  $ curl --request POST \
  --data "grant_type=client_credentials" \
  --data "client_id=myClient" \
  --data "client_secret=forgerock" \
  --data "scope=write" \
  "https://openam.example.com:8443/openam/oauth2/realms/root/access_token"

  Note that the scope parameter has been included. Scopes are not required, since they can be configured by default in the authorization server and the client, and have been added only as an example.

  The authorization server returns an access token in the access_token property. For example:

  {
    "access_token": "sbQZuveFumUDV5R1vVBl6QAGNB8",
    "scope": "write",
    "token_type": "Bearer",
    "expires_in": 3599
  }

Devices can display a user code and instructions for a user, which can be used on a separate client to provide consent, allowing the device to access resources.

As user codes may be displayed on lower resolution devices, the list of possible characters used has been optimized to reduce ambiguity. User codes consist of a random selection of eight of the following characters:

234567ABCDEFGHIJKLMNOPQRSTVWXYZabcdefghijkmnopqrstvwxyz

This procedure assumes the following configuration:

For more information, see "Registering OAuth 2.0 Clients With the OAuth 2.0 Provider Service".

Perform the following steps to request a user code in the OAuth 2.0 device flow:

1. The client creates a POST request to the /oauth2/device/code endpoint specifying, at least, the following parameters:

   • response_type=device_code

   • client_id=your_client_ID

   For information about the parameters supported by the /oauth2/device/code endpoint, see "/oauth2/device/code". For information about private client authentication methods, see "Authenticating OAuth 2.0 Clients".

   For example:

   $ curl \
   --request POST \
   --data "response_type=device_code" \
   --data "client_id=myClient" \
   --data "scope=write" \
   "https://openam.example.com:8443/openam/oauth2/realms/root/device/code"
   {
       "interval": 5,
       "device_code": "7a95a0a4-6f13-42e3-ac3e-d3d159c94c55...",
       "verification_uri": "https://openam.example.com:8443/openam/oauth2/device/user",
       "verification_url": "https://openam.example.com:8443/openam/oauth2/device/user",
       "user_code": "VAL12e0v",
       "expires_in": 300
   }

   On success, AM returns a verification URI (the verification_url output is included to support earlier versions of the draft), and a user code to enter at that URL. AM also returns an interval, in seconds, that the client device must wait for in between requests for an access token.

   Tip

   You can configure the returned values by navigating to Realms > Realm Name > Services > OAuth2 Provider > Device Flow.

2. The client device should now provide instructions to the user to enter the user code and grant access to the OAuth 2.0 device. The client may choose an appropriate method to convey the instructions, for example, text instructions on screen, or a QR code. Perform the steps in one of the following procedures:

   • To grant access to the client using a browser, see "To Grant Consent with a User Code Without Using a Browser in the Device Flow".

   • To grant access to the client without using a browser, see "To Grant Consent with a User Code Using a Browser in the Device Flow".

3. The client device should also begin polling the authorization server for the access token using the interval and device code information obtained in the previous step. For more information, see "To Poll for Authorization in the OAuth 2.0 Device Flow".

OAuth 2.0 Device Flow requires that the user grants consent to allow the client device to access the resources. The authorization server would then provide the client with an access token.

To grant consent with a user code without using a browser, perform the following steps:

1. The resource owner logs in to the authorization server, for example, using the credentials of the demo user. For example:

   $ curl \
   --request POST \
   --header "Content-Type: application/json" \
   --header "X-OpenAM-Username: demo" \
   --header "X-OpenAM-Password: changeit" \
   --header "Accept-API-Version: resource=2.0, protocol=1.0" \
   'https://openam.example.com:8443/openam/json/realms/root/authenticate'
   {
       "tokenId":"AQIC5wM...TU3OQ*",
       "successUrl":"/openam/console",
       "realm":"/"
   }

2. The client makes a POST call to the authorization server's authorization device user endpoint specifying in a cookie SSO token of the demo and, at least, the following parameters:

   • user_code=resource_owner_user_code

   • decision=allow

   • csrf=demo_user_SSO_token

   For information about the parameters supported by the /oauth2/device/user endpoint, see "/oauth2/device/user".

   The iPlanetDirectoryPro cookie is required and should contain the SSO token of the user granting access to the client. For example:

   $ curl \
   --request POST \
   --header "Cookie: iPlanetDirectoryPro=AQIC5wM...TU3OQ*" \
   --data "user_code=VAL12e0v" \
   --data "decision=allow" \
   --data "csrf=AQIC5wM...TU3OQ*" \
   "https://openam.example.com:8443/openam/oauth2/realms/root/device/user"

   The scope and the client_id parameters have not been included because the user code already contains that information.

   AM returns HTML containing a JavaScript fragment named pageData, with details of the result.

   Successfully allowing or denying access returns:

   pageData = {
       locale: "en_US",
       baseUrl : "https://openam.example.com:8443/openam/XUI/",
       realm : "/\",
       done: true
   }

   done: true means that the flow can now continue.

   If the supplied user code has already been used, or is incorrect, AM returns the following:

   pageData = {
       locale: "en_US",
       errorCode: "not_found",
       realm : "/\",
       baseUrl : "https://openam.example.com:8443/openam/XUI/"
       oauth2Data: {
             csrf: "ErFIk8pMraJ1rvKbloTgpp6b7GZ57kyk9HaIiKMVK3g=",
             userCode: "VAL12e0v",
       }
   }

   Important

   As per Section 4.1.1 of the OAuth 2.0 authorization framework, it is required that the authorization server legitimately obtains an authorization decision from the resource owner.

   Any client using the endpoints to register consent is responsible for ensuring this requirement, AM cannot assert that consent was given in these cases.

OAuth 2.0 Device Flow requires that the user grants consent to allow the client device to access the resources. The authorization server would then provide the client with an access token.

To grant consent with a user code using a browser, perform the following steps:

1. The resource owner navigates to the verification URL acquired with the user code, for example, https://openam.example.com:8443/openam/oauth2/device/user.

2. The resource owner logs in to the authorization server using, for example, the demo user credentials.

3. The resource owner enters their user code:

   OAuth 2.0 User Code

   
   
   

   Note

   If the user is not logged in to AM when they provide the code, AM redirects them to the login page.

   After authenticating successfully, the user is prompted to enter the code again. The user code is pre-populated with the code they entered before.

4. The resource owner authorizes the device flow client by allowing the requested scopes:

   OAuth 2.0 Consent Page

   
   
   

   Note

   If the client is allowed to skip consent, the user will not see this screen.

5. AM adds the OAuth 2.0 client to the user's profile page in the Authorized Apps section and displays that the user is done with the flow:

   OAuth 2.0 Done Page

   
   
   

   The device now can request an access token from AM.

The client device must poll the authorization server for an access token, since it cannot know whether the resource owner has already given consent or not.

Perform the following steps to poll for an access token:

• On the client device, create a POST request to poll the /oauth2/access_token endpoint to request an access token specifying, at least, the following parameters:

  • client_id=your_client_id

  • grant_type=urn:ietf:params:oauth:grant-type:device_code

  • device_code=your_device_code

  For information about the parameters supported by the /oauth2/access_token endpoint, see "/oauth2/access_token".

  The client device must wait for the number of seconds previously provided as the value of interval between polling AM for an access token. For example:

  $ curl \
  --request POST \
  --data "client_id=myClient" \
  --data "grant_type=urn:ietf:params:oauth:grant-type:device_code" \
  --data "device_code=7a95a0a4-6f13-42e3-ac3e-d3d159c94c55..." \
  "https://openam.example.com:8443/openam/oauth2/realms/root/access_token"

  If the user has authorized the client device, an HTTP 200 status code is returned, with an access token that can be used to request resources:

  {
      "expires_in": 3599,
      "token_type": "Bearer",
      "access_token": "c1e9c8a4-6a6c-45b2-919c-335f2cec5a40"
  }

  If the user has not yet authorized the client device, an HTTP 403 status code is returned, with the following error message:

  {
      "error": "authorization_pending",
      "error_description": "The user has not yet completed authorization"
  }

  If the client device is polling faster than the specified interval, an HTTP 400 status code is returned, with the following error message:

  {
      "error": "slow_down",
      "error_description": "The polling interval has not elapsed since the last request"
  }

  Tip

  The authorization server can also issue refresh tokens at the same time the access tokens are issued. For more information, see "Managing OAuth 2.0 Refresh Tokens".

Perform the steps in this procedure to configure a trusted JWT issuer agent:

1. Log in to the AM console as an administrative user, for example, amAdmin.

2. Navigate to Realms > Realm Name > Applications > Agents > Trusted JWT Issuer.

3. Add a new trusted JWT issuer agent.

4. Complete the following fields to create the agent:

   1. In the Agent ID field, give the trusted JWT issuer agent a name. For example, myJWTAgent.

   2. In the JWT Issuer field, provide the URI of the JWT issuer. This URI must match the value of the issuer (the iss claim) in the JWTs.

   3. Select Create.

      You are presented with a screen with additional information regarding the agent.

5. Review the trusted JWT issuer agent information. You must, configure either the JWKs URI or the JWK Set fields, as follows:

   • JWKs URI: specifies a URI in the JWT issuer that exposes the verification keys AM will use to validate the JWT signature. For example, http://www.example.com/issuer/jwk_uri.

     If you configure this field, ensure the following properties are configured with sensible values for your environment:

     • JWKs URI content cache timeout in ms

     • JWKs URI content cache miss cache time

   • JWK set: Specifies a JWK set containing the verification keys to validate the JWT signature. The following is an example of an elliptic curve JWK set:

     {
       "keys": [{
          "kty": "EC",
          "crv": "P-256",
          "x": "i-rdOmi5lC3pn3y5sTgYiLLFVFY7XxDLinWneHEaAXA",
          "y": "mxmqqauiq44INgyyPP2vATt3IkDL_6W5CAcfAMSZl8k",
          "kid": "signing_key",
          "x5c": [
              "MIIBSjCB76ADAgEC.....955PByPrflZkQOC/g==" ]
       }]
     }

     For more information about the contents of the JWK set, see the JSON Web Key (JWK) specification.

   You can store more than one key in the JWK set. However, it is easier to implement key rotation exposing the validation keys on the URI instead.

6. (Optional) Configure the following values to suit your environment:

   • Consented Scopes Claim. The name of a JWT claim that indicates which scopes the resource owner consented to. The claim in the JWT can contain either a JSON array or a space-separated whitelist of scopes that the resource owner has consented to.

     For example, if you configure the scp claim name in this field and the JWT contains the claim "scp":"read", but you request both the read and write scopes, AM will only grant the read scope.

     Leave this field blank to allow any scope.

     The following are example JWTs containing a claim that specifies scopes:

     {
        "aud": [
            "https://openam.example.com:8443/openam/oauth2/realms/root/access_token
        ],
        "iss": "https://www.example.com/issuer",
        "exp": 1555530663,
        "sub": "demo",
        "scope": ["read", "write"]
     }

     In this case, the scope claim is a JSON array of scopes.

     {
        "aud": [
            "https://openam.example.com:8443/openam/oauth2/realms/root/access_token
        ],
        "iss": "https://www.example.com/issuer",
        "exp": 1555530663,
        "sub": "demo",
        "scp": "read write"
     }

     In this case, the scp claim is a space-separated list of scopes.

   • Resource Owner Identity Claim. Claim in the JWT that identifies the resource owner in AM. By default, the sub claim.

     Note that even if you configure the trusted JWT issuer agent to verify a different claim, such as the preferred_username claim, the sub claim must still exist in the JWT.

   • Allowed Subjects. List of subjects this JWT issuer is allowed to provide consent for.

     For example, if you configure the demo user in this field but the JWT subject value is demo2, AM will not grant the access token.

     Leave it blank to provide consent to any user.

7. Save your changes.

   The trusted JWT issuer agent is ready for use.

Perform the steps in this procedure to obtain an access token using OAuth 2.0 proof-of-possession:

1. Generate a JSON web key pair for the OAuth 2.0 client.

   AM supports both RSA and elliptic curve (EC) key types. For testing purposes, you can use an online JSON web key generator, such as https://mkjwk.org/, to generate a key pair in JWK format. Be sure to store the full key pair, including the private key, in a secure location that is accessible by your OAuth 2.0 client.

   Your OAuth 2.0 client should never reveal the private key.

2. Represent the public key of the key pair in JWK format. For example:

   {
      "jwk":{
         "alg":"RS256",
         "e":"AQAB",
         "n":"xea7Tb7rbQ4ZrHNKrg...QFXtJ-didSTtXWCWU1Qrcj0hnDjvkuUFWoSQ_7Q",
         "kty":"RSA",
         "use":"enc",
         "kid":"myPublicJSONWebKey"
      }
   }

   Note

   The jwe and jku formats are not supported, the public key must be represented in jwk format.

3. Base64-encode the JWK. For example:

   ew0KICAgICJKV0siOiB7DQogICAgICAgICJhbGciOiAiUlMyNTYiLA0KICAgICAgICAiZSI6IC
   JBUUFCIiwNDQogICAgICAgICJraWQiOiAibXlQdWJsaWNKU09OV2ViS2V5Ig0KICAgIH0NCn0=

4. The client includes the base64-encoded JWK as the value of the cnf_key parameter in the request to the authorization server for an access token.

   For example, in the Client Credentials grant, the client makes a POST call to the authorization server's token endpoint specifying, at least, the following parameters:

   • grant_type=client_credentials

   • cnf_key=your_base64-encoded-JWK

   Private clients can authenticate to the OAuth 2.0 endpoints in several ways. This example uses the following form parameters:

   • client_id=your_client_id

   • client_secret=your_client_secret

   For more information, see "Authenticating OAuth 2.0 Clients".

   For example:

   $ curl \
   --request POST \
   --data "grant_type=client_credentials"\
   --data "client_id=myClient" \
   --data "client_secret=forgerock" \
   --data "cnf_key=ew0KICAgICJKV0siOiB7DQogICAgICAgICJhb
                GciOiAiUlMyNTYiLA0KICAgICAgICAiZSI6IC
                JBUUFCIiwNDQogICAgICAgICJraWQiOiAibXl
                QdWJsaWNKU09OV2ViS2V5Ig0KICAgIH0NCn0=" \
   "https://openam.example.com:8443/openam/oauth2/realms/root/access_token"

   For more information about how to use the different OAuth 2.0 grant flows, see "Implementing OAuth 2.0 Grant Flows".

   The authorization server returns the access token:

   • If the authorization server is configured to use CTS-based OAuth 2.0 tokens, the response will include an access token ID in the access_token property, which identifies the access token data stored on the server. For example:

     {
         "access_token":"f08f1fcf-3ecb-4120-820d-fb71e3f51c04",
         "scope":"profile",
         "token_type":"Bearer",
         "expires_in":3599
     }

   • If the authorization server is configured to use client-based OAuth 2.0 tokens, the response will be a JSON web token in the access_token, which has the JWK embedded within. The following example has shortened the access token for display purposes:

     {
         "access_token": "eyJ0eXAiOiJKV1QiLCHi51zbE3t...zc2NjI3NDgsInNjb3zUOCVKCX0Se0",
         "scope": "profile",
         "token_type": "Bearer",
         "expires_in": 3599
     }

5. The client now requests access to the protected resources from the resource server.

   If CTS-based OAuth 2.0 tokens are enabled, the resource server can make a POST request to the /oauth2/introspect endpoint to acquire the public key. The public key from the original JWK is returned in the cnf element:

   $ curl \
   --request POST \
   --header "Authorization: Basic bXlDbGllbnQ6Zm9yZ2Vyb2Nr" \
   --data "token=f08f1fcf-3ecb-4120-820d-fb71e3f51c04" \
   "https://openam.example.com:8443/openam/oauth2/realms/root/introspect"
   {
       "active": true,
       "scope": "profile",
       "client_id": "myClient",
       "user_id": "myClient",
       "username": "myClient",
       "token_type": "access_token",
       "exp": 1477666348,
       "sub": "myClient",
       "iss": "https://openam.example.com:8443/openam/oauth2/realms/root",
       "cnf": {
           "jwk": {
               "alg": "RS256",
               "e": "AQAB",
               "n": "xea7Tb7rbQ4ZrHNKrg...QFXtJ-didSTtXWCWU1Qrcj0hnDjvkuUFWoSQ_7Q",
               "kty": "RSA",
               "use": "enc",
               "kid": "myPublicJSONWebKey"
           },
       "auth_level": 0
       }
   }

6. The resource server should now use the public key to cryptographically confirm proof-of-possession of the token by the presenter; for example with a challenge-response interaction.

   Successful completion of the challenge-response means that the client must possess the private key that matches the public key presented in the original request, and access to resources can be granted.

Perform the following steps to configure the OAuth 2.0 service and an OAuth 2.0 client to skip consent:

1. Log in to the AM console with an administrative user. For example, amAdmin.

2. Configure the OAuth 2.0 provider to allow clients to skip consent:

   1. Navigate to Realms > Realm Name > Services > OAuth 2.0 provider > Consent.

   2. Enable Allow Clients to Skip Consent.

   3. Click Save Changes.

3. Configure the OAuth 2.0 client to skip consent:

   1. Navigate to Realms > Realm Name > Applications > OAuth 2.0 > Client Name > Advanced.

   2. Enable Implied consent.

   3. Save your changes.

   AM will now treat the requests from this client as if the resource owner/end user has already consented, and will not display consent pages during the flow.

Perform the following steps to configure AM to save consent:

1. Create a multi-valued string syntax attribute in your identity store to save consent entries. For example, oauth2Consent.

   To create the attribute and configure it in AM, see "To Update the Identity Repository for the New Attribute" in the Setup and Maintenance Guide.

2. Log in to the AM console with an administrative user. For example, amAdmin.

3. Navigate to Realms > Realm Name > Services > OAuth 2.0 provider > Consent.

4. In the Saved Consent Attribute field, add the name of the attribute you created in the identity store.

5. Save your changes.

   AM will now save the consented scopes in the identity repository and will only request consent when it cannot find the requested scopes.