Install AM with Amster

Amster can configure a deployed AM as a single, stand-alone instance, or as an instance that is part of a site.

Amster can configure AM to use an embedded DS server as the configuration and identity store, for evaluation purposes.

For production environments, you can specify an external configuration store. Configuring AM to use an external configuration store also requires an external identity store, which will use the specified configuration store by default, unless otherwise specified.

Install AM configuration with Amster by using the install-openam command:

Usage:

am> install-openam \
   --serverUrl protocol://FQDN:port/URI \
   --adminPwd amAdmin_password \
   [options]

--adminPwd amAdmin_password

Specifies the password of the amAdmin user. If the --cfgStoreDirMgrPwd option is not specified, this value is also the password of the configuration store's directory manager user.

The password must be at least 8 characters in length.

--serverUrl protocol://FQDN:port/URI

Specifies the protocol, URL, port, and deployment URI of the AM instance. For example, https://openam.example.com:8443/openam.

Options:

[options]

Specifies optional parameters to configure properties such as the cookie domain, ports and passwords for the configuration store, and others.

For more information about the possible options, run the :help install-openam command or see the install-openam reference section.

Examples

Before trying the following examples, make sure the AM instance is deployed and running but not yet configured. For more information, see the ForgeRock Access Management Installation Guide.

For more information about options available to the install-openam command, see the install-openam reference section.

Tip

Amster also supports scripting the installation process. For more information, see "Scripting".

You can find the following examples in this section:

Installing AM Instances for Evaluation (Embedded Configuration Store)

The following examples show you how to install AM for evaluation, demo, or test purposes. The embedded configuration store is not supported for production environments, and instances configured with it cannot be part of a site.

Example 1

This example installs a single AM instance with the default values:

am> install-openam \
> --serverUrl https://openam.example.com:8443/openam \
> --adminPwd forgerock \
> --acceptLicense

02/22/2017 05:16:20:932 AM GMT: Checking license acceptance...
02/22/2017 05:16:20:934 AM GMT: License terms accepted.
02/22/2017 05:16:20:936 AM GMT: Checking configuration directory /tomcat/openam.
02/22/2017 05:16:20:936 AM GMT: ...Success.
02/22/2017 05:16:20:936 AM GMT: Extracting OpenDJ, please wait...
02/22/2017 05:16:21:265 AM GMT: Complete
02/22/2017 05:16:21:265 AM GMT: Running OpenDJ setup
02/22/2017 05:16:21:265 AM GMT: Setup command: --cli --adminConnectorPort 4444
--baseDN dc=openam,dc=forgerock,dc=org --rootUserDN uid=admin
--ldapPort 50389 --skipPortCheck --rootUserPassword xxxxxxx --jmxPort 1689
--no-prompt --doNotStart --hostname openam.example.com --noPropertiesFile
--backendType je
%0AConfiguring+Directory+Server+.....+Done.
0A%0ATo+see+basic+server+configuration+status+and+configuration%2C+you+can+launch%
0A%2Ftomcat_b%2Fopenam%2Fopends%2Fbin%2Fstatus%0A%0A02/22/2017 05:16:24:531 AM GMT: ...Success.
02/22/2017 05:16:24:531 AM GMT: ...Success
02/22/2017 05:16:24:531 AM GMT: Installing OpenAM configuration store in /tomcat/openam/opends
...
02/22/2017 05:16:53:123 AM GMT: Configuring server instance.
02/22/2017 05:16:53:176 AM GMT: ...Done
02/22/2017 05:16:55:918 AM GMT: Creating demo user.
02/22/2017 05:16:55:942 AM GMT: ...Done
02/22/2017 05:16:55:943 AM GMT: Setting up monitoring authentication file.
Configuration complete!

Notes:

If only the required parameters are supplied, Amster installs AM in a similar way the web configurator does when using the defaults.
This example installs a single AM instance with an embedded configuration store.
When installing AM locally to Amster, Amster stores AM's configuration in the home directory of the user that is running the amster command. For example, for the tomcat user, the configuration is stored in /path/to/tomcat_home/openam.
To modify this behavior, use the --cfgDir option.
If the default ports for the configuration store are already in use, the installer uses the next available free ports.
The demo user is created in the embedded store.

Example 2

This example installs a single AM instance and specifies the configuration directory:

am> install-openam \
> --serverUrl https://openam.example.com:8443/openam \
> --adminPwd forgerock \
> --acceptLicense \
> --cfgDir /tomcat/openam2

02/22/2017 05:34:32:007 AM GMT: Checking license acceptance...
02/22/2017 05:34:32:007 AM GMT: License terms accepted.
02/22/2017 05:34:32:009 AM GMT: Checking configuration directory /tomcat/openam2.
02/22/2017 05:34:32:010 AM GMT: ...Success.
02/22/2017 05:34:32:010 AM GMT: Extracting OpenDJ, please wait...
02/22/2017 05:34:32:280 AM GMT: Complete
02/22/2017 05:34:32:280 AM GMT: Running OpenDJ setup
02/22/2017 05:34:32:265 AM GMT: Setup command: --cli --adminConnectorPort 4444
--baseDN dc=openam,dc=forgerock,dc=org --rootUserDN uid=admin
--ldapPort 389 --skipPortCheck --rootUserPassword xxxxxxx --jmxPort 1689
--no-prompt --doNotStart --hostname openam.example.com --noPropertiesFile
--backendType je
%0AConfiguring+Directory+Server+.....+Done.
...
02/22/2017 05:35:03:509 AM GMT: ...Done
02/22/2017 05:35:03:509 AM GMT: Setting up monitoring authentication file.
Configuration complete!

Notes:

This example installs a single AM instance with an embedded configuration store.
Amster will create the directory specified in the --cfgDir option.
The demo user is created in the embedded store.

Installing AM Instances (External Configuration Store)

Installing AM with an external configuration store requires manual configuration of the directory server. This is also true when specifying a separate identity store.

Note that you cannot install AM with an external configuration store that already contains configuration data, unless you are adding an instance to the existing site.

Example 1

This example installs AM with an external configuration store, which is also used as the identity store.

Before running the amster command, create a truststore for AM and prepare the external configuration store, as detailed in the ForgeRock Access Management Installation Guide.

am> install-openam \
> --serverUrl https://openam.example.com:8443/openam \
> --adminPwd forgerock \
> --acceptLicense \
> --cfgStoreDirMgrPwd mypassword \
> --cfgStore dirServer \
> --cfgStoreHost opendj.example.com \
> --cfgStoreAdminPort 4444 \
> --cfgStorePort 1636 \
> --cfgStoreRootSuffix dc=example,dc=com
> --cfgStoreSsl SSL

09/27/2017 03:37:29:345 PM BST: Checking license acceptance...
09/27/2017 03:37:29:989 PM BST: License terms accepted.
09/27/2017 03:37:29:991 PM BST: Checking configuration directory /Users/forgerock/openam.
09/27/2017 03:37:29:991 PM BST: ...Success.
09/27/2017 03:37:30:997 PM BST: Tag swapping schema files.
09/27/2017 03:37:30:002 PM BST: ...Success.
09/27/2017 03:37:30:004 PM BST: Loading Schema odsee_config_schema.ldif
09/27/2017 03:37:30:040 PM BST: ...Success.
...
09/27/2017 03:37:38:520 PM BST: Loading Schema /Users/forgerock/openam/opendj_pushdevices.ldif
09/27/2017 03:37:38:703 PM BST: ...Success.
09/27/2017 03:37:38:811 PM BST: Installing new plugins...
09/27/2017 03:37:39:401 PM BST: Plugin installation complete.
09/27/2017 03:37:43:252 PM BST: Setting up monitoring authentication file.
Configuration complete!

Notes:

This example installs the configuration store and the identity store in the opendj.example.com host. Both the configuration and identity data use the same DS instance.

The DS instance in the example requires secure connections; therefore, the amster command specifies the 1636 port for LDAPS, and SSL.
For different options, see the install-openam reference section.
Failure to create a truststore and configuring it in the container where AM runs will cause the install process to fail.
When installing AM locally to Amster, Amster stores AM's configuration in the home directory of the user that is running the amster command. For example, for the tomcat user, the configuration is stored in /path/to/tomcat_home/openam.
To modify this behavior, use the --cfgDir option.
If there is any problem setting up the configuration store, the installation process will exit with an error, and navigating to the AM will open the configuration page.
The demo user is not created in the identity store.

Example 2

This example installs AM with external configuration and identity stores.

Before running the amster command, create a truststore for AM and prepare the external configuration and identity stores, as detailed in the ForgeRock Access Management Installation Guide.

am> install-openam \
> --serverUrl https://openam.example.com:8443/openam \
> --adminPwd forgerock \
> --acceptLicense \
> --cfgStoreDirMgrPwd mypassword \
> --cfgStore dirServer \
> --cfgStoreHost opendj.example.com \
> --cfgStoreAdminPort 4444 \
> --cfgStorePort 1636 \
> --cfgStoreSsl SSL \
> --cfgStoreRootSuffix dc=example,dc=com \
> --userStoreDirMgrPwd mypassword2 \
> --userStoreHost ldap.example.com \
> --userStoreType LDAPv3ForOpenDS \
> --userStorePort 1636 \
> --userStoreSsl SSL \
> --userStoreRootSuffix dc=example,dc=com

09/27/2017 03:33:47:989 PM BST: Checking license acceptance...
09/27/2017 03:33:47:989 PM BST: License terms accepted.
09/27/2017 03:33:47:991 PM BST: Checking configuration directory /Users/forgerock/openam.
09/27/2017 03:33:47:991 PM BST: ...Success.
09/27/2017 03:33:47:994 PM BST: Tag swapping schema files.
09/27/2017 03:33:48:006 PM BST: ...Success.
09/27/2017 03:33:48:006 PM BST: Loading Schema odsee_config_schema.ldif
09/27/2017 03:33:48:050 PM BST: ...Success.
...
09/27/2017 03:33:54:691 PM BST: Loading Schema /Users/forgerock/openam/opendj_pushdevices.ldif
09/27/2017 03:33:54:800 PM BST: ...Success.
09/27/2017 03:33:54:847 PM BST: Installing new plugins...
09/27/2017 03:33:55:535 PM BST: Plugin installation complete.
09/27/2017 03:33:56:330 PM BST: Setting up monitoring authentication file.
Configuration complete!

Notes:

When installing AM locally to Amster, Amster stores AM's configuration in the home directory of the user that is running the amster command. For example, for the tomcat user, the configuration is stored in /path/to/tomcat_home/openam.
To modify this behavior, use the --cfgDir option.
The DS instances in the example require secure connections; therefore, the amster command specifies the 1636 port for both stores, and SSL.
For different options, see the install-openam reference section.
Failure to create a truststore and configuring it in the container where AM runs will cause the install process to fail.
If there is any problem setting up the configuration store, the installation process will exit with an error, and navigating to the AM will open the configuration page.
The demo user is not created in the identity store.

Example 3

This example installs two AM instances within a site that use an external configuration store, which is also used as the identity store.

Before running the amster command, create a truststore for each AM instance and prepare the external configuration store, as detailed in the ForgeRock Access Management Installation Guide. Both instances will share the configuration and identity store and, therefore, their truststores should contain the same certificates.

First instance:

am> install-openam \
> --serverUrl https://openam1.example.com:8443/openam \
> --adminPwd forgerock \
> --acceptLicense \
> --cookieDomain example.com \
> --lbSiteName TestSite01 \
> --cfgDir /tomcat/openam1 \
> --lbPrimaryUrl http://site.example.com:80/openam \
> --cfgStore dirServer \
> --cfgStoreHost opendj.example.com \
> --cfgStoreAdminPort 3444 \
> --cfgStorePort 1636 \
> --cfgStoreSsl SSL \
> --cfgStoreRootSuffix dc=examplecfg1,dc=com \
> --cfgStoreDirMgr uid=admin \
> --cfgStoreDirMgrPwd mySecretPassword

11/01/2018 14:37:40:221 AM GMT: Checking license acceptance...
11/01/2018 14:37:40:221 AM GMT: License terms accepted.
11/01/2018 14:37:40:221 AM GMT: Checking configuration directory /tomcat/openam1.
11/01/2018 14:37:40:221 AM GMT: ...Success.
...
11/01/2018 14:38:46:070 PM BST: ...Success.
11/01/2018 14:38:46:070 PM BST: Loading Schema odsee_config_schema.ldif
11/01/2018 14:38:46:079 PM BST: ...Success.
...
11/01/2018 14:41:36:387 PM BST: ...Success.
11/01/2018 14:41:36:388 PM BST: Installing new plugins...
11/01/2018 14:41:38:390 PM BST: Plugin installation complete.
11/01/2018 14:41:43:392 PM BST: Setting up monitoring authentication file.
Configuration complete!

Notes:

Amster will create the directory specified in the --cfgDir option.
Since an identity store is not specified, Amster reuses the configuration store for identities.
The DS instance in the example requires secure connections; therefore, the amster command specifies the 1636 port to connect to the store, and SSL.
For different options, see the install-openam reference section.
Failure to create a truststore and configuring it in the container where AM runs will cause the install process to fail.
Amster will create a site with the name specified in the --lbSiteName option, which can be accessed using the URL specified in the --lbPrimaryUrl option.
The cookie domain is specified in the --cookieDomain. If not specified, Amster sets the cookie domain to the URL of the AM instance, which is not optimal when having multiple instances in a site.

Second instance:

am> install-openam \
> --serverUrl https://openam2.example.com:8443/openam \
> --adminPwd forgerock \
> --acceptLicense \
> --cookieDomain example.com \
> --lbSiteName TestSite01 \
> --cfgDir /tomcat/openam2 \
> --lbPrimaryUrl http://site.example.com:80/openam \
> --cfgStore dirServer\ 
> --cfgStoreHost opendj.example.com \
> --cfgStoreAdminPort 3444 \
> --cfgStorePort 1636 \
> --cfgStoreSsl SSL \
> --cfgStoreRootSuffix dc=examplecfg1,dc=com \
> --cfgStoreDirMgr uid=admin \
> --cfgStoreDirMgrPwd mySecretPassword \
> --pwdEncKey MneLwkkOokJx58znp7QyvGmiawmc2vl4

11/01/2018 14:53:22:773 PM: Checking license acceptance...
11/01/2018 14:53:22:773 PM GMT: License terms accepted.
11/01/2018 14:53:22:773 PM GMT: Checking configuration directory /tomcat/openam2.
11/01/2018 14:53:22:773 PM GMT: ...Success.
11/01/2018 14:53:22:773 PM GMT:Reinitializing system properties.
11/01/2018 14:53:22:773 PM GMT:...Done
11/01/2018 14:54:04:773 PM GMT:Configuring server instance.
11/01/2018 14:54:04:773 PM GMT: ...Done
11/01/2018 14:54:04:123 PM BST: Installing new plugins...
11/01/2018 14:54:04:124 PM BST: Plugin installation complete.
11/01/2018 14:54:10:322 PM BST: Setting up monitoring authentication file.
Configuration complete!

Important

To complete the installation of the second instance, follow the steps in "Post-Installation Steps for Site Deployments".

Notes:

This example installs an AM instance with as part of the TestSite01 site. Note that the configuration store details are the same as those used for the first server, since they are sharing the same DS instance.
The password specified in the --adminPwd option must be the same password used across the site.
Since an identity store is not specified, Amster reuses the configuration store for identities.
Amster will create the directory specified in the --cfgDir option.
The DS instance in the example requires secure connections; therefore, the amster command specifies the 1636 port to connect to the store, and SSL.
For different options, see the install-openam reference section.
Failure to create a truststore and configuring it in the container where AM runs will cause the install process to fail.
The cookie domain is specified in the --cookieDomain option. The cookie domain must be the same as the one used when installing the first instance, in this case, example.com. When unspecified, Amster sets the cookie domain to the URL of the AM instance, which is not optimal when having multiple instances in a site.
Failure to set this option correctly may result in login failure to the new instance.
The --pwdEncKey specifies the encryption key used by the servers already in the site. To locate the encryption key value, navigate to Deployment > Servers > Server Name > Security > Encryption.
Failure to set this option to the appropriate value will cause the original encryption key to be overwritten, which will render the site unable to read the configuration and identity stores.

Post-Installation Steps for Site Deployments

Keystore and secret store infrastructure is shared across all the AM instances in the site. This is so that every instance in the site can encrypt, decrypt, and verify messages, JWTs, and others, with the same keys.

The install process creates the required keystores and secret stores on the first instance in the site only. You must configure the keystore and secret store infrastructure in the rest of the instances manually.

The following steps assume you have an AM site composed of one or more instances, and that you installed a new instance and added it to the site using Amster:

Make the site keystore infrastructure available to the new instance:
1. Back up the new instance's default keystore and password files in the following locations:
  - /path/to/openam/security/keystores/
  - /path/to/openam/security/secrets/default/
2. Ensure that the existing keystores in the site are available in the same location to the new instance. This may mean copying the keystores and their password files, mounting a volume, or others.
3. Ensure that the keystore files configured in the /path/to/openam/config/boot.json file are available to the new instance.
Make the secret store infrastructure in the site available to the new instance:
1. Log in to the AM console of an existing instance in the site and navigate to Configure > Secret Stores.
2. Review the list of secret stores configured globally and make sure to provide the relevant stores to the new instance. For example:
  - For keystore-type secret stores, copy the keystores to the same path on the new instance.
  - For filesystem-type secret stores, copy the contents of the directories to the same path, or make the filesystem available on the same mount point on the new instance.
  - For HSM-type stores, ensure the new instance can access it.
  - For secrets configured as environment variables accessible by the container where AM runs, ensure they are also accessible by the container of the new instance.
3. Navigate to Realms > Realm Name > Secret Stores.
4. Review the list of secret stores configured per realm and make sure to provide the relevant stores to the new instance.
Restart the new instance.
The instance is now configured for the site.

Troubleshoot AM Installations

The following table describes possible errors when installing AM with the install-openam command:

Error	Solution
`Invalid Suffix for directory server ds.example.com:1389. No Base Entity dc=incorrectsuffix,dc=com found.`	Review that the suffix you are trying to use exists in DS.
`Cannot connect to Directory Server. Invalid Credentials.`	Review the credentials to connect to DS.
`Cannot connect to Directory Server. Connect Error: Connection refused.`	Review DS's host and/or connection port.
`Unexpected LDAP exception occurred.`	Review DS logs. DS may be stopped, or may have become unreachable during install.
`Cannot connect to Directory Server. Connect Error: The LDAP connection has failed because an error occurred during the SSL handshake...`	Review that the container where AM will be installed trusts DS's SSL certificates.