Set up AM

This is not a comprehensive platform implementation guide. These sample setup instructions show a minimal integration of platform components to get you started.

The ForgeRock Identity Platform offers maximum extensibility and flexibility in self-managed deployments. The platform includes many features and options these sample setup instructions do not cover. If you don’t need maximum extensibility and flexibility, there are simpler alternatives:

To consume the platform as a service, use ForgeRock Identity Cloud.
To deploy in Kubernetes, start with the ForgeOps reference implementation.

For help with your deployment and to validate your plans before deploying in production, contact ForgeRock.

When your external data stores are configured, follow these procedures to configure AM with the ForgeRock Identity Platform:

Install AM

Follow the instructions in the AM documentation to download AM. Make sure you download the .zip file, not just the .war file.
Copy the AM .war file to deploy in Apache Tomcat as am.war:
```
cp AM-7.5.0.war /path/to/tomcat/webapps/am.war
```
Start Tomcat if it is not already running.
Navigate to the deployed AM application; for example, http://am.example.com:8081/am/.
Select Create New Configuration to create a custom configuration.
Accept the license agreement, and click Continue.
Set a password for the default user, amAdmin.

These instructions assume that the amAdmin password is Passw0rd.
On the Server Settings screen, enter your AM server settings; for example:
- Server URL: http://am.example.com:8081
- Cookie Domain: example.com
- Platform Locale: en_US
- Configuration Directory: /path/to/am
On the Configuration Data Store Settings screen, select External DS, and enter the details for the DS instance that you set up as a configuration store.

This list reflects the DS configuration store installed with the listed server settings.
- SSL/TLS: Enabled (DS requires TLS.)
- Host Name: directory.example.com
- Port: 1636
- Encryption Key: (generated encryption key)
- Root Suffix: ou=am-config
- Login ID: uid=am-config,ou=admins,ou=am-config
- Password: 5up35tr0ng
- Server configuration: New deployment
On the User Data Store Settings screen, select External User Data Store, and enter the details for the DS instance that you set up as an identity store.

The AM setup process requires that you configure an identity store.

You will use this store later in an alpha realm for non-administrative identities.

This list reflects the DS identity store installed with the listed server settings.
- User Data Store Type: ForgeRock Directory Services (DS)
- SSL/TLS: Enabled (DS requires TLS.)
- Host Name: directory.example.com
- Port: 1636
- Root Suffix: ou=identities
- Login ID: uid=am-identity-bind-account,ou=admins,ou=identities
- Password: 5up35tr0ng
On the Site Configuration screen, select No, then click Next.
Review the Configurator Summary Details, then click Create Configuration.

Use the external CTS store

Update the AM configuration to use DS as an external token store:

Log in to the AM admin UI as the amAdmin user.
Browse to Configure > Server Defaults > CTS.

Make the following changes, saving your work before switching tabs:

Setting Choice

Setting	Choice
CTS Token Store > Store Mode	External Token Store
CTS Token Store > Root Suffix	`ou=famrecords,ou=openam-session,ou=tokens`
External Store Configuration > SSL/TLS Enabled	Selected
External Store Configuration > Connection String(s)	`localhost:1636`
External Store Configuration > Login Id	`uid=openam_cts,ou=admins,ou=famrecords,ou=openam-session,ou=tokens`
External Store Configuration > Password	`5up35tr0ng`

CTS Token Store > Store Mode

External Token Store

CTS Token Store > Root Suffix

ou=famrecords,ou=openam-session,ou=tokens

External Store Configuration > SSL/TLS Enabled

Selected

External Store Configuration > Connection String(s)

localhost:1636

External Store Configuration > Login Id

uid=openam_cts,ou=admins,ou=famrecords,ou=openam-session,ou=tokens

External Store Configuration > Password

5up35tr0ng

Keep the defaults for all other settings.

Create a realm

The AM Top Level Realm should serve administration purposes only.

These steps create an alpha realm for non-administrative identities:

If you’re not currently logged in to the AM admin UI as the amAdmin user, log in.
Click + New Realm, and create the new realm with the following settings:
- Name: alpha
- Keep the defaults for all other settings.

For background information, see Realms in the AM documentation.

Configure OAuth clients

The deployment depends on the following OAuth 2.0 clients:

Client ID Description In Top Level Realm? In subrealms?

Client ID	Description	In Top Level Realm?	In subrealms?
`idm-resource-server`	IDM uses this confidential client to introspect access tokens through the `/oauth2/introspect` endpoint to obtain information about users. This client is not used for OAuth 2.0 flows, only to introspect tokens. It is not a real OAuth 2.0 client, in the traditional sense. Rather, it is an OAuth 2.0 Resource Server account, used exclusively for token introspection. As such, you do not need to specify redirect URIs or grant types. When you configure the client, AM adds the `Authorization Code` grant type to the client profile by default. This client does not use it, but there’s no requirement to remove it from the client profile.
`idm-provisioning`	AM nodes in authentication journeys (trees) use this confidential client to authenticate through AM and provision identities through IDM. This client uses the client credentials flow, and does not authenticate resource owners other than itself.
`idm-admin-ui`	The Platform Admin UI uses this public client to access platform configuration features, such as identity management and journey (tree) editing. The client uses the implicit flow, and authenticates administrator users who are authorized to perform administrative operations.
`end-user-ui`	The End User UI uses this public client to access and present end-user profile data. The client uses the implicit flow, and authenticates end users who are authorized to view and edit their profiles.

idm-resource-server

IDM uses this confidential client to introspect access tokens through the /oauth2/introspect endpoint to obtain information about users.

This client is not used for OAuth 2.0 flows, only to introspect tokens. It is not a real OAuth 2.0 client, in the traditional sense. Rather, it is an OAuth 2.0 Resource Server account, used exclusively for token introspection. As such, you do not need to specify redirect URIs or grant types.

When you configure the client, AM adds the Authorization Code grant type to the client profile by default. This client does not use it, but there’s no requirement to remove it from the client profile.

idm-provisioning

AM nodes in authentication journeys (trees) use this confidential client to authenticate through AM and provision identities through IDM.

This client uses the client credentials flow, and does not authenticate resource owners other than itself.

idm-admin-ui

The Platform Admin UI uses this public client to access platform configuration features, such as identity management and journey (tree) editing.

The client uses the implicit flow, and authenticates administrator users who are authorized to perform administrative operations.

end-user-ui

The End User UI uses this public client to access and present end-user profile data.

The client uses the implicit flow, and authenticates end users who are authorized to view and edit their profiles.

When configuring a client in more than one realm, make sure that the client configurations are identical.

Follow these steps to configure the OAuth 2.0 clients:

If you’re not currently logged in to the AM admin UI as the amAdmin user, log in.
In the Top Level Realm, configure an idm-resource-server client to introspect access tokens:
- Select Applications > OAuth 2.0 > Clients, and click Add Client.
- Enter the following details:
  - Client ID: idm-resource-server
  - Client secret: password
    
    The value of this field must match the clientSecret that you will set in the rsFilter module in the IDM authentication configuration (/path/to/openidm/conf/authentication.json) during your IDM setup.
  - Scopes:
    am-introspect-all-tokens
    am-introspect-all-tokens-any-realm
- Click Create.
In the Top Level Realm and the alpha realm, configure identical idm-provisioning clients to make calls to IDM:
- Select Applications > OAuth 2.0 > Clients, and click Add Client.
- Enter the following details:
  - Client ID: idm-provisioning
  - Client secret: openidm
  - Scopes: fr:idm:*
- Click Create.
- On the Advanced tab:
  - Response Types: Check that token is present (it should be there by default).
  - Grant Types: Remove Authorization Code and add Client Credentials.
- Click Save Changes.

In the Top Level Realm and the alpha realm, configure identical idm-admin-ui clients that will be used by the Platform Admin UI:

Select Applications > OAuth 2.0 > Clients, and click Add Client.

Enter the following details:

Client ID: idm-admin-ui
Client Secret: (no client secret is required)
Redirection URIs:

http://openidm.example.com:8080/platform/appAuthHelperRedirect.html
http://openidm.example.com:8080/platform/sessionCheck.html
http://openidm.example.com:8080/admin/appAuthHelperRedirect.html
http://openidm.example.com:8080/admin/sessionCheck.html
http://admin.example.com:8082/appAuthHelperRedirect.html
http://admin.example.com:8082/sessionCheck.html

Scopes:

openid
fr:idm:*

At a minimum, the scopes that you set here must include the scopes that you will set in the rsFilter authentication configuration (/path/to/openidm/conf/authentication.json) during your IDM setup.

Click Create.
On the Core tab:
- Client type: Select Public.
- Click Save Changes.
On the Advanced tab:
- Grant Types: Add Implicit.
- Token Endpoint Authentication Method: Select none.
- Implied consent: Enable.
- Click Save Changes.

In the Top Level Realm and the alpha realm, configure identical end-user-ui clients that will be used by the Platform End User UI:

Select Applications > OAuth 2.0 > Clients , and click Add Client.

Enter the following details:

Client ID: end-user-ui
Client Secret: (no client secret is required)
Redirection URIs:

http://enduser.example.com:8888/appAuthHelperRedirect.html
http://enduser.example.com:8888/sessionCheck.html

Scopes:

openid
fr:idm:*

Click Create.
On the Core tab:
- Client type: Select Public.
- Click Save Changes.
On the Advanced tab:
- Grant Types: Add Implicit.
- Token Endpoint Authentication Method: Select none.
- Implied Consent: Enable.
- Click Save Changes.

Configure OAuth 2.0 providers

If you’re not currently logged in to the AM admin UI as the amAdmin user, log in.
Configure a provider for the Top Level Realm:
1. In the Top Level Realm, select Services, and click Add a Service.
2. Under Choose a service type, select OAuth2 Provider.
3. For Client Registration Scope Allowlist, add the following scopes:
  am-introspect-all-tokens
  am-introspect-all-tokens-any-realm
  fr:idm:*
  openid
4. Click Create.
5. On the Advanced tab, make sure that Response Type Plugins includes the following values:
  id_token|org.forgerock.openidconnect.IdTokenResponseTypeHandler
  code|org.forgerock.oauth2.core.AuthorizationCodeResponseTypeHandler
6. Click Save Changes.
7. On the Consent tab, enable Allow Clients to Skip Consent.
8. Click Save Changes.
Configure a provider for the alpha realm:
1. In the alpha realm, select Services, and click Add a Service.
2. Under Choose a service type, select OAuth2 Provider.
3. For Client Registration Scope Allowlist, add the following scopes:
  fr:idm:*
  openid
4. Click Create.
5. On the Advanced tab, make sure that Response Type Plugins includes the following values:
  id_token|org.forgerock.openidconnect.IdTokenResponseTypeHandler
  code|org.forgerock.oauth2.core.AuthorizationCodeResponseTypeHandler
6. Click Save Changes.
7. On the Consent tab, enable Allow Clients to Skip Consent.
8. Click Save Changes.

Configure an IDM provisioning service

If you’re not currently logged in to the AM admin UI as the amAdmin user, log in.
From the top menu, select Configure > Global Services > IDM Provisioning.

The AM admin UI does not let you configure an IDM provisioning service in a realm.
Set the following fields:
- Enabled
- Deployment URL: http://openidm.example.com:8080
- Deployment Path: openidm
- IDM Provisioning Client: idm-provisioning
Click Save Changes.

If some resource strings in the AM admin UI do not resolve properly at setup time, the UI labels mentioned will show internal keys instead of the labels shown in the steps above. Use the following table to check that you have the correct service and fields:

UI label Internal label

IDM Provisioning

IdmIntegrationService

Enabled

enabled

Deployment URL

idmDeploymentUrl

Deployment Path

idmDeploymentPath

IDM Provisioning Client

idmProvisioningClient

Configure a validation service

The Platform UIs need this validation service allow listing for goto redirection.

If you’re not currently logged in to the AM admin UI as the amAdmin user, log in.
In the alpha realm, select Services, and click Add a Service.
Under Choose a service type, select Validation Service.
For Valid goto URL Resources, add the URLs for the Platform UI:

http://admin.example.com:8082/*
http://admin.example.com:8082/*?*
http://login.example.com:8083/*
http://login.example.com:8083/*?*
http://enduser.example.com:8888/*
http://enduser.example.com:8888/*?*
Click Create.

Enable CORS support

Cross-origin resource sharing (CORS) lets user agents make requests across domains.

If you’re not currently logged in to the AM admin UI as the amAdmin user, log in.
From the top menu, select Configure > Global Services > CORS Service.
On the Secondary Configurations tab, click Add a Secondary Configuration.
On the New Configuration screen, enter the following values:
- Name : Cors Configuration
- Accepted Origins :
  
  http://login.example.com:8083
  http://admin.example.com:8082
  http://enduser.example.com:8888
  http://openidm.example.com:8080
  https://openidm.example.com:8443
  
  List only the origins that will be hosting OAuth 2.0 clients (such as the platform-enduser and IDM admin UIs).
- Accepted Methods:
  
  DELETE
  GET
  HEAD
  PATCH
  POST
  PUT
- Accepted Headers:
  
  accept-api-version
  authorization
  cache-control
  content-type
  if-match
  if-none-match
  user-agent
  x-forgerock-transactionid
  x-openidm-nosession
  x-openidm-password
  x-openidm-username
  x-requested-with
- Exposed Headers: WWW-Authenticate
Click Create.
On the Cors Configuration screen, set the following values:
- Enable the CORS filter: Enable
- Max Age: 600
- Allow Credentials: Enable
Click Save Changes.

Configure authentication trees

The platform deployment relies on three authentication trees to enable authentication through AM. When you extract the AM .zip file, you will get a sample-trees-7.5.0.zip file that contains a number of sample authentication trees, in JSON files. Use the Amster command-line utility to import the platform authentication trees into your AM configuration:

Extract the sample-trees-7.5.0.zip file, and list the sample trees in the root/AuthTree directory:

ls /path/to/openam-samples/root/AuthTree
Agent.json                         PlatformForgottenUsername.json
Example.json                       PlatformLogin.json
Facebook-ProvisionIDMAccount.json  PlatformProgressiveProfile.json
Google-AnonymousUser.json          PlatformRegistration.json
Google-DynamicAccountCreation.json PlatformResetPassword.json
HmacOneTimePassword.json           PlatformUpdatePassword.json
PersistentCookie.json              RetryLimit.json

In all the sample tree files, replace "realm" : "/" with "realm" : "/alpha".
Download and install Amster.

Start Amster, then connect to your AM instance:

./amster
Amster OpenAM Shell (version build build, JVM: version)
Type ':help' or ':h' for help.
---------------------------------------------------------------------------
am> connect --interactive http://am.example.com:8081/am
Sign in
User Name: amAdmin
Password: Passw0rd
amster am.example.com:8081> :exit

Import the sample authentication trees and nodes:

amster am.example.com:8081>import-config --path /path/to/openam-samples/root
Importing directory /path/to/openam-samples/root/AcceptTermsAndConditions
...
Import completed successfully

If you’re not currently logged in to the AM admin UI as the amAdmin user, log in.
Configure the PlatformRegistration tree:
- In the alpha realm, select Authentication > Trees, and click PlatformRegistration.
- On the PlatformRegistration tree, add a Success URL node between Increment Login Count and Success, and set its value to http://enduser.example.com:8888/?realm=alpha.
  
  Show me
- Click Save.
Configure the PlatformLogin tree:
- In the alpha realm, select Authentication > Trees, and click PlatformLogin.
- On the PlatformLogin tree, add a Success URL node between Inner Tree Evaluator and Success, and set its value to http://enduser.example.com:8888/?realm=alpha.
  
  Show me
- Click Save.
Configure the PlatformResetPassword tree:
- In the alpha realm, select Authentication > Trees, and click PlatformResetPassword.
- On the PlatformResetPassword tree, add a Success URL node between Patch Object and Success, and set its value to http://enduser.example.com:8888/?realm=alpha.
  
  Show me
- Click Save.
Configure the PlatformUpdatePassword tree:
- In the alpha realm, select Authentication > Trees, and click PlatformUpdatePassword.
- On the PlatformUpdatePassword tree, select the Patch Object node, and make sure Patch As Object is disabled.
  
  Show me
- Click Save.
For the authentication trees that require email, set the External Login Page URL.
- In the alpha realm, select Authentication > Settings, and click the General tab.
- Set External Login Page URL to http://login.example.com:8083, then click Save Changes.

Map authentication trees

Map the platform authentication trees to the corresponding Self-Service endpoints. For more information about this step, refer to Configure self-service trees endpoints.

In the alpha realm, select Services, and click Add a Service.
Under Choose a service type, select Self Service Trees, and click Create.
Add the following tree mappings:

Key Value

registration

PlatformRegistration

login

PlatformLogin

resetPassword

PlatformResetPassword
Click Save Changes.

Key	Value
`registration`	`PlatformRegistration`
`login`	`PlatformLogin`
`resetPassword`	`PlatformResetPassword`

Additional AM configuration

The AM configuration shown is sufficient for this sample deployment. Read the AM documentation when using additional features.

For example, if AM runs behind a load balancer or a reverse proxy, configure a base URL source service. Adapt the AM configuration to use this service when you protect AM with IG.

Restart Tomcat

Restart Tomcat to take all the configuration changes into account:

$ /path/to/tomcat/bin/shutdown.sh
# Wait a moment for Tomcat to shut down cleanly before starting it again.
$ /path/to/tomcat/bin/startup.sh

ForgeRock Identity Platform 7.5