Guide showing you how to use OpenID Connect 1.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 OAuth2 provider service with OpenID Connect defaults by using the Configure OAuth Provider wizard:

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

2. On the Configure OAuth2/OpenID Connect Service 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" in the OAuth 2.0 Guide.

7. Select Create to save your changes. If an OAuth2 provider service already exists, it will be overwritten with the new OpenID Connect parameter values.

   AM creates an OAuth2 provider service, with OpenID Connect default parameter values.

1. Log in to the AM console as an administrative user, such as amAdmin, and then navigate to Realms > Realm Name > Services.

2. Click Add a Service, select Base URL Source, and then click Create, leaving the fields empty.

3. For Base URL Source, select one of the following options:

   Base URL Source Options

   Option	Description
   Extension class	Click the Extension class to return a base URL from a provided HttpServletRequest object. In the Extension class name field, enter org.forgerock.openam.services.baseurl.BaseURLProvider.
   Fixed value	Click Fixed value to enter a specific base URL value. In the Fixed value base URL field, enter the base URL.
   Forwarded header	Click Forwarded header to retrieve the base URL from the Forwarded header field in the HTTP request. The Forwarded HTTP header field is standardized and specified in RFC 7239.
   Host/protocol from incoming request (default)	Click Host/protocol from incoming request to get the hostname, server name, and port from the HTTP request.
   X-Forwarded-* headers	Click X-Forwarded-* headers to use non-standard header fields, such as X-Forwarded-For, X-Forwarded-By, and X-Forwarded-Proto.

   
   

4. In the Context path, enter the context path for the base URL. If provided, the base URL includes the deployment context path appended to the calculated URL. For example, /openam.

5. Click Finish to save your configuration.

You configure AM as an OpenID Connect provider for Mobile Connect by changing the OAuth2 Provider configuration.

Follow the steps in this procedure to set up the OAuth2 provider service with Mobile Connect defaults by using the Configure OAuth Provider wizard.

When you create the OAuth2 provider service with the Configure OAuth Provider wizard, the wizard also creates a standard policy in the Top Level Realm (/) to protect the authorization endpoint. In this configuration, AM serves the resources to protect, and no separate application is involved. AM therefore acts both as the policy decision point and policy enforcement point that protects the OAuth 2.0 authorization endpoint used by OpenID Connect.

There is no requirement to use the wizard or to create the policy in the Top Level Realm. However, if you create the OAuth 2.0 provider service without the wizard, then you must set up the policy independently as well. The policy must appear in a policy set of type iPlanetAMWebAgentService. When configuring the policy, allow all authenticated users to perform HTTP GET and POST requests on the authorization endpoint. The authorization endpoint is described in "OAuth 2.0 Endpoints" in the OAuth 2.0 Guide. For details on creating policies, see "Implementing Authorization" in the Authorization Guide.

1. In the AM console, select Realms > Realm Name > Dashboard > Configure OAuth Provider > Configure Mobile Connect.

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

3. (Optional) If necessary, adjust the lifetimes for authorization codes, access tokens, and refresh tokens.

4. (Optional) Select Issue Refresh Tokens unless you do not want the authorization service to supply a refresh token when returning an access token.

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

6. (Optional) If you have a custom scope validator implementation, put it on 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" in the OAuth 2.0 Guide.

7. Click Create to save your changes.

   AM creates an OAuth2 provider service with Mobile Connect default parameter values, as well as a policy to protect the OAuth2 authorization endpoints.

   Warning

   If an OAuth2 provider service already exists, it will be overwritten with the new Mobile Connect parameter values.

8. To access the provider service configuration in the AM console, browse to Realms > Realm Name > Services > OAuth2 Provider.

   For Mobile Connect providers you may want to configure the following settings:

   1. Configure the following OpenID Connect authentication context settings for AM to return acr and amr claims in the ID tokens:

      • OpenID Connect acr_values to Auth Chain Mapping

      • Default ACR values

      • OpenID Connect id_token amr Values to Auth Module Mappings

      For more information, see "Adding Authentication Requirements to ID Tokens".

   2. Configure the identity Data Store attributes used to return updated_at values in the ID Token.

      For Mobile Connect clients, the user info endpoint returns updated_at values in the ID Token. If the user profile has never been updated updated_at reflects creation time.

      The updated_at values are read from the profile attributes you specify. When using DS as an identity data store, the value is read from the modifyTimestamp attribute, or the createTimestamp attribute for a profile that has never been modified.

      In addition, you must also add these attributes to the list of LDAP User Attributes for the identity store. Otherwise, the attributes are not returned when AM reads the user profile. To edit the list in the AM console, browse to Realms > Realm Name > Identity Stores > Identity Store Name > User Configuration > LDAP User Attributes.

9. Click Save to complete the process.

Perform the following steps to enable and configure ID token encryption:

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

2. On the Signing and Encryption tab, select Enable ID Token Encryption.

3. In the Id Token Encryption Algorithm field, enter the algorithm AM will use to encrypt ID tokens.

   AM supports the following encryption algorithms:

   • A128KW - AES Key Wrapping with 128-bit key derived from the client secret.

   • A192KW - AES Key Wrapping with 192-bit key derived from the client secret.

   • A256KW - AES Key Wrapping with 256-bit key derived from the client secret.

   • RSA-OAEP - RSA with Optimal Asymmetric Encryption Padding (OAEP) with SHA-1 and MGF-1.

   • RSA-OAEP-256 - RSA with OAEP with SHA-256 and MGF-1.

   • RSA1_5 - RSA with PKCS#1 v1.5 padding (not recommended).

   • dir - Direct encryption with AES using the hashed client secret.

   • ECDH-ES - Elliptic Curve Diffie-Hellman

   • ECDH-ES+A128KW - Elliptic Curve Diffie-Hellman + AES Key Wrapping with 128-bit key.

   • ECDH-ES+A192KW - Elliptic Curve Diffie-Hellman + AES Key Wrapping with 192-bit key.

   • ECDH-ES+A256KW - Elliptic Curve Diffie-Hellman + AES Key Wrapping with 256-bit key.

   Only the P-256, P-384, and P-521 curves are supported.

4. In the ID Token Encryption Method field, enter the method AM will use to encrypt ID tokens.

   AM supports the following encryption methods:

   • A128CBC-HS256 - AES 128-bit in CBC mode using HMAC-SHA-256-128 hash (HS256 truncated to 128 bits)

   • A192CBC-HS384 - AES 192-bit in CBC mode using HMAC-SHA-384-192 hash (HS384 truncated to 192 bits)

   • A256CBC-HS512 - AES 256-bit in CBC mode using HMAC-SHA-512-256 hash (HS512 truncated to 256 bits)

   • A128GCM - AES 128-bit in GCM mode

   • A192GCM - AES 192-bit in GCM mode

   • A256GCM - AES 256-bit in GCM mode

5. (Optional) If you selected an RSA encryption algorithm, perform one of the following actions:

   • Enter the public key in the Client ID Token Public Encryption Key field.

   • Enter a JWK set in the Json Web Key field.

   • Enter a URI containing the public key in the Json Web Key URI field.

6. (Optional) If you selected an ECDH-ES encryption algorithm, perform one of the following actions:

   • Enter a JWK set in the Json Web Key field.

   • Enter a URI containing the public key in the Json Web Key URI field.

7. (Optional) If you selected an algorithm different from RSA or ECDH-ES, navigate to the Core tab and store the private key/secret in the Client Secret field.

   Caution

   Several features of OAuth 2.0 use the string stored in the Client Secret field to sign/encrypt tokens or parameters when you configure specific algorithms. For example, signing ID tokens with HMAC algorithms, encrypting ID tokens with AES or direct algorithms, or encrypting OpenID Connect parameters with AES or direct algorithms.

   In this case, these features must share the key/secret stored in the Client Secret field and you must ensure that they are configured with the same algorithm.

This example shows how to obtain an ID token and an access token. It adds notes on how to obtain an ID token only, as well.

This procedure assumes the following configuration:

For more information, see "Registering OpenID Connect Relying Parties".

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

1. The client redirects the end user'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

   • scope=openid profile

   For information about the parameters supported by the /oauth2/authorize endpoint, see "/oauth2/authorize" in the OAuth 2.0 Guide.

   If the OAuth 2.0/OpenID 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/OpenID 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=openid%20profile \
   &state=abc123 \
   &nonce=123abc \
   &redirect_uri=https://www.example.com:443/callback

   Note that the URL is split and spaces have been added for readability purposes. The state and nonce parameters have been included to protect against CSRF and replay attacks.

2. The end user authenticates to AM, 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, AM presents its consent screen:

   OpenID Connect Consent Screen

   
   
   

   Note that requesting the profile scope translates into requesting access to several claims. For more information about the special profile scope, see "OpenID Connect Scopes and Claims".

3. The end user selects the Allow button to grant consent for the profile scope.

   AM redirects the end user 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 AM has issued. For example:

   https://www.example.com:443/callback?code=g5B3qZ8rWzKIU2xodV_kkSIk0F4&iss=https://openam.example.com:8443/openam/oauth2&state=abc123&client_id=myClient

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

This example shows how to obtain an ID token and an access token. It adds notes on how to obtain an ID token only, as well.

This procedure assumes the following configuration:

For more information, see "Registering OpenID Connect Relying Parties".

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

1. The end user logs in to AM, 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 AM'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

   • scope=openid profile

     You can configure the openid scope as a default scope in the client profile or the OAuth 2.0/OpenID provider to avoid including the scope parameter in your calls, if required.

     However, since the openid scope is required in OpenID Connect flows, the example specifies it.

   • decision=allow

   • csrf=demo_user_SSO_token

   For information about the parameters supported by the /oauth2/authorize endpoint, see "/oauth2/authorize" in the OAuth 2.0 Guide.

   If the OAuth 2.0/OpenID 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/OpenID 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=openid profile" \
   --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 "nonce=123abc" \
   --data "decision=allow" \
   "https://openam.example.com:8443/openam/oauth2/realms/root/authorize"

   Note that the state and nonce parameters have been included to protect against CSRF and replay attacks.

   If AM 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&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 ID/Access Token in the Authorization Code Grant Flow" to exchange the authorization code for an ID/access token.

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

1. Ensure the relying party 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 relying party makes an HTTP POST request to the token endpoint in the OpenID provider 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" in the OAuth 2.0 Guide.

   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" in the OAuth 2.0 Guide.

   If the OAuth 2.0/OpenID 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/OpenID 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 AM will not validate the code.

   AM returns an ID and an access token. For example:

   {
      "access_token":"cnM3nSpF5ckCFZOaDem2vANUdqQ",
      "scope":"openid profile",
      "id_token":"eyJ0eXAiOiJKV1QiLCJra...7r8soMCk8A7QdQpg",
      "token_type":"Bearer",
      "expires_in":3599
   }

   If the client does not require the access token, revoke it in the OAuth 2.0 Guide.

   Tip

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

3. (Optional) The relying party can request additional claims about the end user from AM.

   For more information, see "/oauth2/userinfo".

The relying party (the client) 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 relying party is now ready to request an authorization code.

2. The relying party 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 OpenID Connect Relying Parties".

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

1. The relying party redirects the end user's user-agent to the AM'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

   • scope=openid profile

   For information about the parameters supported by the /oauth2/authorize endpoint, see "/oauth2/authorize" in the OAuth 2.0 Guide.

   If the OAuth 2.0/OpenID 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/OpenID 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=openid%20profile \
   &redirect_uri=https://www.example.com:443/callback \
   &code_challenge=j3wKnK2Fa_mc2tgdqa6GtUfCYjdWSA5S23JKTTtPF8Y \
   &code_challenge_method=S256 \
   &nonce=123abc \
   &state=abc123

   Note that the URL is split and spaces have been added for readability purposes. The state and nonce parameters have been included to protect against CSRF and replay attacks.

2. The end user authenticates to AM, 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, AM presents its consent screen:

   OpenID Connect Consent Screen

   

   Note that requesting the profile scope translates into requesting access to several claims. For more information about the special profile scope, see "OpenID Connect Scopes and Claims".

   
   

3. The end user selects the Allow button to grant consent for the profile scope.

   AM redirects the end user 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 AM has issued. For example:

   https://www.example.com:443/callback?code=g5B3qZ8rWzKIU2xodV_kkSIk0F4&iss=https://openam.example.com:8443/openam/oauth2&state=abc123&client_id=myClient

5. The client performs the steps in "To Exchange an Authorization Code for an ID/Access Token in the Authorization Code Grant with PKCE Flow" to exchange the authorization code for an ID/access token.

This procedure assumes the following configuration:

For more information, see "Registering OpenID Connect Relying Parties".

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

1. The end user logs in to AM, 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 an HTTP POST request to AM's authorization endpoint, specifying in a cookie the 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

   • scope=openid profile

     You can configure the openid scope as a default scope in the client profile or the OAuth 2.0/OpenID provider to avoid including the scope parameter in your calls, if required.

     However, since the openid scope is required in OpenID Connect flows, the example specifies it.

   For information about the parameters supported by the /oauth2/authorize endpoint, see "/oauth2/authorize" in the OAuth 2.0 Guide.

   If the OAuth 2.0/OpenID 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/OpenID 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=openid profile" \
   --data "response_type=code" \
   --data "client_id=myClient" \
   --data "csrf=AQIC5wM...TU3OQ*" \
   --data "state=abc123" \
   --data "nonce=123abc" \
   --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 state and nonce parameters have been included to protect against CSRF and replay attacks.

   If AM 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&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 ID/Access Token in the Authorization Code Grant with PKCE Flow" to exchange the authorization code for an ID/access token.

Perform the steps in the following procedure to exchange an authorization code for an ID/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" in the OAuth 2.0 Guide.

   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 AM will not validate the code.

   AM returns an ID and an access token. For example:

   {
      "access_token":"cnM3nSpF5ckCFZOaDem2vANUdqQ",
      "scope":"openid profile",
      "id_token":"eyJ0eXAiOiJKV1QiLCJra...7r8soMCk8A7QdQpg",
      "token_type":"Bearer",
      "expires_in":3599
   }

   If the client does not require the access token, revoke it in the OAuth 2.0 Guide.

   Tip

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

3. (Optional) The relying party can request additional claims about the end user from AM.

   For more information, see "/oauth2/userinfo".

Perform the following steps to prepare AM for the backchannel request grant flow:

1. In AM, configure an OAuth 2.0/OpenID provider in the top-level realm.

2. Associate an authentication tree that performs push authentication with the acr_values property contained in the signed JWT.

   The authentication tree must start with a "Username Collector Node", and contain a "Push Sender Node" and "Push Result Verifier Node", and a "Polling Wait Node".

   The following is an example of a suitable authentication tree:

   

   For more information on creating authentication trees for push authentication, see "Creating Authentication Trees for Push Authentication" in the Authentication and Single Sign-On Guide.

   To associate a push authentication tree with incoming acr_values, perform the following steps:

   1. In the AM console, navigate to Realms > Realm Name > Services > OAuth2 Provider > Advanced OpenID Connect.

   2. In the OpenID Connect acr_values to Auth Chain Mapping box, enter the value of the acr_values property in the Key field, and the name of the push authentication tree to use in the Value field, for example CIBA, and then click Add.

   3. Save your changes.

      For more information, see "The Authentication Context Class Reference (acr) Claim".

   For more information, see "Configuring AM as an OpenID Connect Provider".

3. In AM, create a confidential OAuth 2.0 client with a client ID of myCIBAClient. The client ID must match the value of the iss claim in the signed JWT prepared above.

   The client profile should have the following configuration:

   • Client secret: forgerock

   • Scopes: openid profile

   • Response Types: id_token token

   • Grant Types: Back Channel Request

   • Token Endpoint Authentication Method: client_secret_basic

     Confidential OpenID Connect clients can use several methods to authenticate. For more information, see "Authenticating Clients when Using OpenID Connect 1.0" in the OAuth 2.0 Guide.

   • The client must be provided with the public key of the keypair that will be used to sign the JWT.

     On the Signing and Encryption tab, you must configure either the JWKs URI or the JWK Set fields, as follows:

     • JWKs URI: specifies a URI that exposes the public keys AM will use to validate the JWT signature.

       For example, http://www.example.com/issuer/jwk_uri.

       Note

       If you configure this field, ensure the following properties are configured with values suitable 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 public keys used to validate JWT signatures.

       The following is an example of a public elliptic curve JWK set:

       {
         "keys": [
           {
             "kty": "EC",
             "use": "sig",
             "crv": "P-256",
             "kid": "myCIBAKey",
             "x": "m0CkpWpZyGu-FLRLjCGBVGC7Fwm5vGt8Lm3HhYU4ylg",
             "y": "U8NMtO-C2c3yhu2I_ApAELttmaittfPNPQaIJxvTCHk",
             "alg": "ES256"
           }
         ]
       }

       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.

   For more information, see "Registering OpenID Connect Relying Parties".

Perform the steps in this procedure to obtain an authentication request ID, using CIBA:

1. On the client, prepare a signed JWT. The JWT must contain, at least, the following claims in the payload:

   aud

   Specifies a string or an array of strings that is the intended audience of the JWT. Must be set to the authorization server's OAuth 2.0 endpoint, for example:

   "aud": "http://openam.example.com:8080/openam/oauth2"

   exp

   Specifies the expiration time of the JWT in Unix time.

   Providing a JWT with an expiry time greater than 30 minutes causes AM to return a JWT expiration time is unreasonable error message.

   iss

   Specifies the unique identifier of the JWT issuer.

   The identifier must match the client ID of the OAuth 2.0 client in AM, for example myCIBAClient.

   login_hint

   Specifies the principal who is the subject of the JWT. It should be a string that identifies the resource owner.

   Tip

   You can provide a previously obtained ID token in a property named id_token_hint as the hint for determining the resource owner, rather than a string.

   scope

   Specifies a space-separated list of the requested scopes. Must include the openid scope.

   acr_values

   Specifies an identifier that maps to the authentication mechanism AM uses to obtain authorization from the end user.

   binding_message

   Specifies a message delivered to the user when obtaining authorization.

   Should be a short (100 characters or fewer), description of the operation the end user is authorizing, and should include an identifier to match the authorization request to the client that initiated the request.

   Note

   If the binding message is sent using push notifications, the following additional limitations apply to the value:

   1. Must begin with a letter, number, or punctuation mark.

   2. Must not include line breaks or control characters.

   For example:

   Allow ExampleBank to transfer £50 from your 'Main' account to your 'Savings' account? (EB-0246326)

   The following is an example of the payload of a basic JWT:

   {
     "login_hint": "demo",
     "scope": "openid profile",
     "acr_values": "push",
     "iss": "myCIBAClient",
     "aud": "http://openam.example.com:8080/openam/oauth2",
     "exp": 1559311511,
     "binding_message": "Allow ExampleBank to transfer £50 from your 'Main' account to your 'Savings' account? (EB-0246326)"
   }

   For more information about JWTs, see the RFC 7523 standard.

2. The client makes a POST request to the authorization server's backchannel authorization endpoint, including the signed JWT, and the client credentials in the authorization header.

   For example:

   $ curl --request POST \
   --header "authorization: Basic bXlDSUJBQ2xpZW50OmZvcmdlcm9jaw==" \
   --data "request=eyJhbGci...kfPjAfnBg" \
   "https://openam.example.com:8443/openam/oauth2/bc-authorize"

   	The basic authorization header is the base64-encoded value of your client ID, a colon character (:), and the client secret. For example myCIBAClient:forgerock. For more information about authenticating clients, see "Authenticating OAuth 2.0 Clients" in the OAuth 2.0 Guide.
   	The "request" field should contain the entire signed JWT. The value in this example has been truncated for display purposes.

   AM returns JSON containing the auth_req_id value:

   {
     "auth_req_id": "35Evy3bJXJEnhll2ebacgROYfbU",
     "expires_in": 600,
     "interval": 2
   }

   AM will also send the user a push notification message, containing the contents of the binding_message, to request authorization for the operation.

   For more information on interacting with push notifications, see "To Perform Authentication using Push Notifications" in the Authentication and Single Sign-On Guide.

3. The client performs the steps in "To Exchange an Authorization Request ID for an ID/Access Token in the Backchannel Request Grant Flow" to exchange the authentication request ID for an ID token (and an access/refresh token).

Perform the steps in the following procedure to exchange an authorization request ID for an ID/access token:

1. The client starts to poll the token endpoint in the OpenID provider with HTTP POST requests, with the client credentials in the authorization header, and specifies the following parameters:

   • grant_type=urn:openid:params:grant-type:ciba

   • auth_req_id=your_authorization_request_id

   If the OAuth 2.0/OpenID 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/OpenID provider is configured for the /customers realm, then use /oauth2/realms/root/realms/customers/access_token.

   For example:

   $ curl --request POST \
   --header "authorization: Basic bXlDSUJBQ2xpZW50OmZvcmdlcm9jaw==" \
   --data "grant_type=urn:openid:params:grant-type:ciba" \
   --data "auth_req_id=35Evy3bJXJEnhll2ebacgROYfbU" \
   "https://openam.example.com:8443/openam/oauth2/access_token"

   The basic authorization header is the base64-encoded value of your client ID, a colon character (:), and the client secret. For example myCIBAClient:forgerock. For more information about authenticating clients, see "Authenticating OAuth 2.0 Clients" in the OAuth 2.0 Guide.

   • If the user has authenticated and authorized the operation, AM returns an ID token and an access token. For example:

     {
       "access_token": "z4mWG0cxqwPwgjj7srJ2Jdxe9ag",
       "id_token": "eyJ0eXAiOi...YA9Hoqwew",
       "token_type": "Bearer",
       "expires_in": 3599
     }

     Tip

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

   • If the user has not yet authenticated and authorized the operation, AM returns an HTTP 400 response, as follows:

     {
       "error_description": "End user has not yet been authenticated",
       "error": "authorization_pending"
     }

     The client should wait the number of seconds specified by the interval value that was returned when requesting the auth_req_id, and then resend the POST request. The default value for interval is two seconds.

   • If the client does not wait for the interval before resending the request, AM returns an HTTP 400 response, as follows:

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

2. (Optional) The relying party can request additional claims about the end user from AM.

   For more information, see "/oauth2/userinfo".

This example shows how to obtain an ID token and an access token. It adds notes on how to obtain the ID token only, as well.

The procedure assumes the following configuration:

For more information, see "Registering OpenID Connect Relying Parties".

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

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

   • client_id=your_client_id

   • response_type=token id_token

     To obtain only an ID token, use response_type=id_token instead.

   • redirect_uri=your_redirect_uri

   • nonce=your_nonce

   • scope=openid profile

   For information about the parameters supported by the /oauth2/authorize endpoint, see "/oauth2/authorize" in the OAuth 2.0 Guide.

   If the OAuth 2.0/OpenID 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/OpenID 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%20id_token \
   &scope=openid%20profile \
   &redirect_uri=https://www.example.com:443/callback \
   &state=abc123 \
   &nonce=123abc

   Note that the URL is split for readability purposes and that the state parameter has been included to protect against CSRF attacks.

2. The end user logs in to AM, 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, AM presents the AM user interface consent screen:

   Consent Screen

   
   
   

   Note that requesting the profile scope translates into requesting access to several claims. For more information about the special profile scope, see "OpenID Connect Scopes and Claims".

3. The end user selects the Allow button to grant consent for the profile scope.

   AM 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 and an id_token parameter with the tokens AM has issued. For example:

   https://www.example.com:443/callback/#access_token=pRbNamsGPv1T7NfAf5Dbx4AHM2c&id_token=eyJ0eXAiOiJKV1QiLCJra...7r8soMCk8A7QdQpg&state=123&token_type=Bearer&expires_in=3599

   If you only request an ID token, the response would not include the access_token parameter.

5. (Optional) The relying party can request additional claims about the end user from AM.

   For more information, see "/oauth2/userinfo".

This example shows how to obtain an ID token and an access token. It adds notes on how to obtain the ID token only, as well.

The procedure assumes the following configuration:

For more information, see "Registering OpenID Connect Relying Parties".

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

1. The end user authenticates to AM, 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 AM'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 id_token

     To obtain only an ID token, use response_type=id_token instead.

   • redirect_uri=your_redirect_uri

   • nonce=your_nonce

   • scope=openid profile

   • decision=allow

   • csrf=demo_user_SSO_token

   For information about the parameters supported by the /oauth2/authorize endpoint, see "/oauth2/authorize" in the OAuth 2.0 Guide.

   If the OAuth 2.0/OpenID 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/OpenID 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 id_token" \
   --data "scope=openid profile" \
   --data "state=123abc" \
   --data "nonce=abc123" \
   --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 state parameter has been included to protect against CSRF attacks.

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

   HTTP/1.1 302 Found
   Server: Apache-Coyote/1.1
   X-Frame-Options: SAMEORIGIN
   Pragma: no-cache
   Cache-Control: no-store
   Date: Mon, 04 Mar 2019 16:56:46 GMT
   Accept-Ranges: bytes
   Location: https://www.example.com:443/callback#access_token=az91IvnIQ-uP3Eqw5QqaXXY_DCo&id_token=eyJ0eXAiOiJKV1QiLCJra...7r8soMCk8A7QdQpg&state=123abc&token_type=Bearer&expires_in=3599
   Vary: Accept-Charset, Accept-Encoding, Accept-Language, Accept
   Content-Length: 0

   If you only request an ID token, the response would not include the access_token parameter.

3. (Optional) The relying party can request additional claims about the end user from AM.

   For more information, see "/oauth2/userinfo".

This procedure assumes the following configuration:

For more information, see "Registering OpenID Connect Relying Parties".

Perform the steps in the following procedure to obtain an ID token and an authorization code that will later be exchanged for an access token:

1. The client redirects the end user'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 id_token

     As per the specification, you can request the following response types:

     • code id_token

     • code token

     • code id_token token

     Since AM returns the tokens in the redirection URL, requesting access tokens in this way poses a security risk.

   • redirect_uri=your_redirect_uri

   • scope=openid profile

   For information about the parameters supported by the /oauth2/authorize endpoint, see "/oauth2/authorize" in the OAuth 2.0 Guide.

   If the OAuth 2.0/OpenID 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/OpenID 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%20id_token \
   &scope=openid%20profile \
   &state=abc123 \
   &nonce=123abc \
   &redirect_uri=https://www.example.com:443/callback

   Note that the URL is split and spaces have been added for readability purposes. The state and nonce parameters have been included to protect against CSRF and replay attacks.

   Tip

   Implement the PKCE specification to mitigate against interception attacks performed by malicious users.

   For more information about the required additional parameters and an example, see "Authorization Code Grant with PKCE".

2. The end user authenticates to AM, 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, AM presents its consent screen:

   OpenID Connect Consent Screen

   
   
   

   Note that requesting the profile scope translates into requesting access to several claims. For more information about the special profile scope, see "OpenID Connect Scopes and Claims".

3. The end user selects the Allow button to grant consent for the profile scope.

   AM redirects the end user 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 and a id_token parameter with the ID token AM has issued. For example:

   https://www.example.com:443/callback?code=bOrAijEerd_YdNCUC1piL5VfNO4&id_token=eyJ0eXAiOiJKV1QiLCJra...7r8soMCk8A7QdQpg&token_type=Bearer&expires_in=3599

   The client relying party can now use the ID token as the end user's identity and store the access code for later use.

5. (Optional) The client exchanges the authorization code for an access token (and maybe, an refresh token). Perform the steps in one of the following procedures:

   • "To Exchange an Authorization Code for an ID/Access Token in the Authorization Code Grant Flow"

   • "To Exchange an Authorization Code for an ID/Access Token in the Authorization Code Grant with PKCE Flow"

This procedure assumes the following configuration:

For more information, see "Registering OpenID Connect Relying Parties".

Perform the steps in the following procedure to obtain an ID token and an authorization code that will later be exchanged for an access token:

1. The end user logs in to AM, 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 AM'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 id_token

     As per the specification, you can request the following response types:

     • code id_token

     • code token

     • code id_token token

     Since AM returns the tokens in the redirection URL, requesting access tokens in this way poses a security risk.

   • redirect_uri=your_redirect_uri

   • scope=openid profile

   • decision=allow

   • csrf=demo_user_SSO_token

   For information about the parameters supported by the /oauth2/authorize endpoint, see "/oauth2/authorize" in the OAuth 2.0 Guide.

   If the OAuth 2.0/OpenID 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/OpenID 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=openid profile" \
   --data "response_type=code id_token" \
   --data "client_id=myClient" \
   --data "csrf=AQIC5wM...TU3OQ*" \
   --data "redirect_uri=https://www.example.com:443/callback" \
   --data "state=abc123" \
   --data "nonce=123abc" \
   --data "decision=allow" \
   "https://openam.example.com:8443/openam/oauth2/realms/root/authorize"

   Note that the state and nonce parameters have been included to protect against CSRF and replay attacks.

   Tip

   Implement the PKCE specification to mitigate against interception attacks performed by malicious users.

   For more information about the required additional parameters and an example, see "Authorization Code Grant with PKCE".

   If AM 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=bOrAijEerd_YdNCUC1piL5VfNO4&id_token=eyJ0eXAiOiJKV1QiLCJra...7r8soMCk8A7QdQpg&token_type=Bearer&expires_in=3599
   Vary: Accept-Charset, Accept-Encoding, Accept-Language, Accept
   Content-Length: 0

   The client relying party can now use the ID token as the end user's identity and store the access code for later use.

3. (Optional) The client exchanges the authorization code for an access token (and maybe, a refresh token). Perform the steps in one of the following procedures:

   • "To Exchange an Authorization Code for an ID/Access Token in the Authorization Code Grant Flow"

   • "To Exchange an Authorization Code for an ID/Access Token in the Authorization Code Grant with PKCE Flow"

1. In the AM console, navigate to Realms > Realm Name > Services > OAuth2 Provider > Advanced OpenID Connect.

2. (Optional) To request acr claims using the claims parameter, enable "claims_parameter_supported".

3. In the OpenID Connect acr_values to Auth Chain Mapping box, map an identifier (the key in the map) to an authentication chain or tree. For example:

   

   The identifier is the string that AM will add in the acr claim.

4. Save your changes.

5. (Optional) In the Default ACR values field, specify the identifiers of the authentication trees or chains AM should use to authenticate end users when acr values are not specified in the request. AM treats acr values specified in this field as voluntary claims.

   Acr values specified in the request will override the default values.

   If a request does not specify acr values and the Default ACR values field is empty, AM authenticates the end user with the default authentication chain or tree defined for the realm where the OAuth 2.0 provider is configured.

   Tip

   Query the /oauth2/.well-known/openid-configuration endpoint to determine the acr values supported by the OpenID provider. Mapped acr values are returned in the acr_values_supported object.

6. Save your changes.

7. (Optional) Review the "Requesting acr Claims Example".

1. In the AM console, navigate to Realms > Realm Name > Services > OAuth2 Provider > Advanced OpenID Connect.

2. In the OpenID Connect id_token amr Values to Auth Module Mappings box, map an identifier (the key in the map) to any authentication module. The authentication module you use is not important; AM will only use its name to map the amr, and it will not show in the ID token.

   Example: Mapping Authentication Modules to amr Identifiers
   

3. Save your changes.

4. Create an authentication tree containing the "Set Session Properties Node" in the Authentication and Single Sign-On Guide.

5. On the Set Session Properties node, configure a key called AuthType. As its value, set the name of the authentication module you configured with the amr mapping. For example, LDAP.

   Example: Configuring the AuthType Session Property
   

   Tip

   To reference multiple authentication modules, separate amr values with |. For example, if both the LDAP and the DataStore modules are mapped to amr values, set the AuthType key to the value LDAP|DataStore.

6. Go to Realms > Realm Name > Services, and add a Session Property Whitelist service if one is not already available.

7. On the Whitelisted Session Property Names field, add the AuthType key. This will ensure that the property can be read, edited, or deleted, from a session.

   Save your changes.

1. In the AM console, go to Realms > Realm Name > Services > OAuth2 Provider > Advanced OpenID Connect.

2. In the OpenID Connect id_token amr Values to Auth Module Mappings box, map an identifier (the key in the map) to an authentication module.

   Example: Mapping Authentication Modules to amr Identifiers
   

3. Save your changes.

Perform the following steps to allow clients to use ID tokens in the place of session tokens:

1. Navigate to Realms > Realm Name > Services > OAuth2 Provider > Advanced OpenID Connect.

2. Add the names to the clients that will be able to use ID tokens in place of session tokens in the Authorized OIDC SSO Clients field.

   Since these clients will act with the full authority of the end user, grant this permission to trusted clients only.

3. Ensure that Save Ops Token is enabled.

4. Save your changes.

Perform the following steps to access the public keys:

1. To find the JWK URI that AM exposes, perform an HTTP GET at /oauth2/realms/root/.well-known/openid-configuration. For example:

   $ curl https://openam.example.com:8443/openam/oauth2/realms/root/.well-known/openid-configuration
   {
     "request_parameter_supported": true,
     "claims_parameter_supported": false,
     "introspection_endpoint": "https://openam.example.com:8443/openam/oauth2/introspect",
     "check_session_iframe": "https://openam.example.com:8443/openam/oauth2/connect/checkSession",
     "scopes_supported": [],
     "issuer": "https://openam.example.com:8443/openam/oauth2",
     "id_token_encryption_enc_values_supported": [
       "A256GCM",
       "A192GCM",
       "A128GCM",
       "A128CBC-HS256",
       "A192CBC-HS384",
       "A256CBC-HS512"
     ],
   ...
     "jwks_uri": "https://openam.example.com:8443/openam/oauth2/connect/jwk_uri",
     "subject_types_supported": [
       "public"
     ],
   ...
   }

   By default, AM exposes the JWK URI as an endpoint relative to the deployment URI. For example, https://openam.example.com:8443/openam/oauth2/realms/root/connect/jwk_uri.

   In environments where secrets are centralized, you may want AM to share the URI of your secrets API instead of the local AM endpoint.

   To configure it, navigate to Realms > Realm name > Services > OAuth2 Provider, and add the new URI to the Remote JSON Web Key URL field.

2. Perform an HTTP GET at the JWK URI to get the relevant public keys. For example:

   $ curl https://openam.example.com:8443/openam/oauth2/realms/root/connect/jwk_uri
   {
   "keys":[
         {
            "kty":"EC",
            "kid":"I4x/IijvdDsUZMghwNq2gC/7pYQ=",
            "use":"sig",
            "x5t":"GxQ9K-sxpsH487eSkJ7lE_SQodk",
            "x5c":[
               "MIIB/zCCAYYCCQDS7UWmBdQtETAJ0mN0TZL7/MaY..."
                  ],
            "x":"k5wSvW_6JhOuCj-9PdDWdEA4oH90RSmC2GTliiUHAhXj6rmTdE2S-_zGmMFxufuV",
            "y":"XfbR-tRoVcZMCoUrkKtuZUIyfCgAy8b0FWnPZqevwpdoTzGQBOXSNi6uItN_o4tH",
            "crv":"P-384"
         },
         ...
      ]
   }

1. On https://server.example.com:8443/openam, navigate to Realms > Realm Name.

2. On the Common Tasks Dashboard, select Configure OAuth Provider. Then, select Configure OpenID Connect.

3. On the configuration wizard, keep the default values and select Create.

4. Navigate to Realms > Realm Name > Applications > OAuth 2.0 and select Add Client.

5. Configure the client with the following settings:

   • Client ID: myClient

   • Client secret: forgerock

   • Scope(s): openid profile email

6. On https://client.example.net:8443/openam, navigate to Realms > Realm Name.

7. On the Common Tasks dashboard, select Configure Social Authentication. Then, select Configure Other Authentication.

8. Configure the social authentication provider with the following settings:

   • OpenID Discovery URL: https://server.example.com:8443/openam/oauth2/.well-known/openid-configuration

   • Provider Name: amServer

   • Image URL/Path: http://tinyurl.com/openam-logo

   • Client ID: myClient

   • Client Secret and Confirm Client Secret: forgerock

   Keep the default value of the Redirect URL field, for example, https://client.example.net:8443/openam/oauth2c/OAuthProxy.jsp, and copy it to the clipboard.

9. On https://server.example.com:8443/openam, navigate to Realms > Realm Name > Authentication > Modules and select amServerSocialAuthentication.

10. On the Account Provisioning tab, enable Create account if it does not exist.

11. Navigate to Realms > Realm Name > Applications > OAuth 2.0 > myClient.

12. Configure the following settings on the client:

    • Redirect URIs: Paste the value of the Redirect URL field from the client. For example, https://client.example.net:8443/openam/oauth2c/OAuthProxy.jsp.

    • Client Name: AM2

    • Display Name: AM2

    • Display Description: AM2 Instance Client

13. Logout from https://client.example.net:8443/openam and return to the login page.

    You should be able to log in to https://client.example.net:8443/openam with the test user by using the AM logo to start the OpenID Connect flow.