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 Access Management.
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 ForgeRock Access Management installation guide.
For more information about options available to the install-openam
command,
see install-openam - Install Access Management.
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 thetomcat
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
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 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 the1636
port for LDAPS, andSSL
.For different options, see install-openam - Install Access Management.
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 thetomcat
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
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 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 thetomcat
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 the1636
port for both stores, andSSL
.For different options, see install-openam - Install Access Management.
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 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 the1636
port to connect to the store, andSSL
.For different options, see install-openam - Install Access Management.
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 the1636
port to connect to the store, andSSL
.For different options, see install-openam - Install Access Management.
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:
-
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.
-
-
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.
-
-
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 |
---|---|
|
Review that the suffix you are trying to use exists in DS. |
|
Review the credentials to connect to DS. |
|
Review DS’s host and/or connection port. |
|
Review DS logs. DS may be stopped, or may have become unreachable during install. |
|
Review that the container where AM will be installed trusts DS’s SSL certificates. |