Amster

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 install-openam - Install PingAM.

Examples

Before trying the following examples, make sure the AM instance is deployed and running but not yet configured. For more information, refer to the ${am.name.full} installation guide.

For more information about options available to the install-openam command, see install-openam - Install PingAM.

Amster also supports scripting the installation process. For more information, refer to Scripts.

Install AM 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
timestamp: Checking license acceptance…​
timestamp: License terms accepted.
timestamp: Checking configuration directory /tomcat/openam.
timestamp: …​Success.
timestamp: Extracting OpenDJ, please wait…​
timestamp: Complete
timestamp: Running OpenDJ setup
timestamp: 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%0Atimestamp: …​Success.
timestamp: …​Success
timestamp: Installing OpenAM configuration store in /tomcat/openam/opends
…​
timestamp: Configuring server instance.
timestamp: …​Done
timestamp: Creating demo user.
timestamp: …​Done
timestamp: Setting up monitoring authentication file.
Configuration complete!

Notes:

  • If only the required parameters are supplied, Amster installs AM like 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
timestamp: Checking license acceptance…​
timestamp: License terms accepted.
timestamp: Checking configuration directory /tomcat/openam2.
timestamp: …​Success.
timestamp: Extracting OpenDJ, please wait…​
timestamp: Complete
timestamp: Running OpenDJ setup
timestamp: 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.
…​
timestamp: …​Done
timestamp: 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.

Install AM (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 ${am.name.full} 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
timestamp: Checking license acceptance…​
timestamp: License terms accepted.
timestamp: Checking configuration directory /Users/forgerock/openam.
timestamp: …​Success.
timestamp: Tag swapping schema files.
timestamp: …​Success.
timestamp: Loading Schema odsee_config_schema.ldif
timestamp: …​Success.
…​
timestamp: Loading Schema /Users/forgerock/openam/opendj_pushdevices.ldif
timestamp: …​Success.
timestamp: Installing new plugins…​
timestamp: Plugin installation complete.
timestamp: 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 install-openam - Install PingAM.

    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 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 ${am.name.full} 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
timestamp: Checking license acceptance…​
timestamp: License terms accepted.
timestamp: Checking configuration directory /Users/forgerock/openam.
timestamp: …​Success.
timestamp: Tag swapping schema files.
timestamp: …​Success.
timestamp: Loading Schema odsee_config_schema.ldif
timestamp: …​Success.
…​
timestamp: Loading Schema /Users/forgerock/openam/opendj_pushdevices.ldif
timestamp: …​Success.
timestamp: Installing new plugins…​
timestamp: Plugin installation complete.
timestamp: 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 install-openam - Install PingAM.

    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 ${am.name.full} 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
timestamp: Checking license acceptance…​
timestamp: License terms accepted.
timestamp: Checking configuration directory /tomcat/openam1.
timestamp: …​Success.
…​
timestamp: …​Success.
timestamp: Loading Schema odsee_config_schema.ldif
timestamp: …​Success.
…​
timestamp: …​Success.
timestamp: Installing new plugins…​
timestamp: Plugin installation complete.
timestamp: 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 install-openam - Install PingAM.

    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
timestamp: Checking license acceptance…​
timestamp: License terms accepted.
timestamp: Checking configuration directory /tomcat/openam2.
timestamp: …​Success.
timestamp:Reinitializing system properties.
timestamp:…​Done
timestamp:Configuring server instance.
timestamp: …​Done
timestamp: Installing new plugins…​
timestamp: Plugin installation complete.
timestamp: Setting up monitoring authentication file.
Configuration complete!

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 install-openam - Install PingAM.

    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:

  1. Make the site keystore infrastructure available to the new instance:

    • 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/

    • 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.

    • Ensure that the keystore files configured in the /path/to/openam/config/boot.json file are available to the new instance.

  2. Make the secret store infrastructure in the site available to the new instance:

    • Log in to the AM console of an existing instance in the site and navigate to Configure > Secret Stores.

    • 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.

    • Navigate to Realms > Realm Name > Secret Stores.

    • Review the list of secret stores configured per realm, and make sure to provide the relevant stores to the new instance.

  3. 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.
Copyright © 2010-2024 ForgeRock, all rights reserved.