PingAM

Configure AM with Amster

Use Amster to configure a deployed AM instance as either a single, stand-alone server or as a server within a site.

Amster configures AM to use an external configuration store and identity store.

You can’t use Amster to install PingAM in file-based configuration (FBC) mode. Instead, follow the instructions in Passive install with FBC.

To configure AM with Amster, run the install-openam command:

Usage:

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

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

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

Options:

[options]

Use these optional parameters to configure properties like the cookie domain, ports, and passwords for the configuration store.

To see all available options, run the :help install-openam command or read install-openam - install PingAM.

Examples

Before you start, make sure your AM instance is deployed and running, but not yet configured. Learn more in Deploy AM.

Before you run the amster command, you must create a truststore for AM, and prepare the external configuration and identity stores. Learn more in Prepare datastores.

You can’t install AM with an external configuration store that already contains configuration data, unless you’re adding a server to an existing site.

Amster also supports scripting the installation process. Learn more in Scripts.

Example 1: Stand-alone server

This example installs AM with external configuration and identity stores.

am> install-openam \
 --serverUrl https://am.example.com:8443/am \
 --adminPwd password \
 --acceptLicense \
 --cfgStoreDirMgrPwd myPassword \
 --cfgStore dirServer \
 --cfgStoreHost ds.example.com \
 --cfgStoreAdminPort 4444 \
 --cfgStorePort 1636 \
 --cfgStoreSsl SSL \
 --cfgStoreRootSuffix ou=am-config \
 --userStoreDirMgrPwd myPassword2 \
 --userStoreHost ds.example.com \
 --userStoreType LDAPv3ForOpenDS \
 --userStorePort 1636 \
 --userStoreSsl SSL \
 --userStoreRootSuffix ou=identities
timestamp: Checking license acceptance…​
timestamp: License terms accepted.
timestamp: Checking configuration directory /Users/Ping/am.
timestamp: …​Success.
timestamp: Tag swapping schema files.
timestamp: …​Success.
…​
timestamp: Loading Schema /Users/Ping/am/opendj_pushdevices.ldif
timestamp: …​Success.
timestamp: Installing new plugins…​
timestamp: Plugin installation complete.
timestamp: Setting up monitoring authentication file.
Configuration complete!

  • When you install AM locally, Amster stores the AM configuration in the home directory of the user running the amster command. For example, for the tomcat user, the configuration is stored in /path/to/tomcat_home/am . To change this location, use the --cfgDir option.

  • The DS instances in this example require secure connections, so the amster command specifies port 1636 and SSL for both stores.

    Find information about other options in install-openam - Install PingAM.

    You must create a truststore and configure it in the AM container. If you don’t, the installation will fail.

  • If a problem occurs while setting up the configuration store, the installation process exits with an error. When this happens, going to the AM URL opens the configuration page.

Example 2: Two servers in a site

This example shows how to install two AM servers in a site with external configuration and identity stores.

Before you start, create a truststore for each AM server and prepare the external stores. Because both servers share the configuration and identity store, their truststores must contain the same certificates.

First instance:

am> install-openam \
 --serverUrl https://am1.example.com:8443/am \
 --adminPwd password \
 --acceptLicense \
 --cookieDomain example.com \
 --lbSiteName TestSite01 \
 --cfgDir /tomcat/am1 \
 --lbPrimaryUrl https://site.example.com:8443/am \
 --cfgStoreDirMgr uid=am-config,ou=admins,ou=am-config \
 --cfgStoreDirMgrPwd myPassword
 --cfgStore dirServer \
 --cfgStoreHost ds.example.com \
 --cfgStoreAdminPort 3444 \
 --cfgStorePort 1636 \
 --cfgStoreSsl SSL \
 --cfgStoreRootSuffix ou=am-config \
 --userStoreDirMgrPwd myPassword2 \
 --userStoreHost ds.example.com \
 --userStoreType LDAPv3ForOpenDS \
 --userStorePort 1636 \
 --userStoreSsl SSL \
 --userStoreRootSuffix ou=identities
timestamp: Checking license acceptance…​
timestamp: License terms accepted.
timestamp: Checking configuration directory /tomcat/am1.
timestamp: …​Success.
…​
timestamp: …​Success.
…​
timestamp: …​Success.
timestamp: Installing new plugins…​
timestamp: Plugin installation complete.
timestamp: Setting up monitoring authentication file.
Configuration complete!

  • Amster creates the directory specified with the --cfgDir option.

  • The --lbSiteName option creates a site with that name, accessible at the URL specified with --lbPrimaryUrl.

  • Use the --cookieDomain option to set the cookie domain. If you don’t specify it, Amster uses the server’s URL, which isn’t optimal for a site with multiple servers.

Second instance:

am> install-openam \
 --serverUrl https://am2.example.com:8443/am \
 --adminPwd password \
 --acceptLicense \
 --cookieDomain example.com \
 --lbSiteName TestSite01 \
 --cfgDir /tomcat/am2 \
 --lbPrimaryUrl https://site.example.com:8443/am \
 --cfgStoreDirMgr uid=am-config,ou=admins,ou=am-config \
 --cfgStoreDirMgrPwd myPassword \
 --cfgStore dirServer\
 --cfgStoreHost ds.example.com \
 --cfgStoreAdminPort 3444 \
 --cfgStorePort 1636 \
 --cfgStoreSsl SSL \
 --cfgStoreRootSuffix ou=am-config \
--userStoreDirMgrPwd myPassword2 \
 --userStoreHost ds.example.com \
 --userStoreType LDAPv3ForOpenDS \
 --userStorePort 1636 \
 --userStoreSsl SSL \
 --userStoreRootSuffix ou=identities
 --pwdEncKey MneLwkkOokJx58znp7QyvGmiawmc2vl4**
timestamp: Checking license acceptance…​
timestamp: License terms accepted.
timestamp: Checking configuration directory /tomcat/am2.
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 finish adding the second server to the site, you must follow the steps in Post-installation steps for site deployments.

  • This command adds a new AM server to the TestSite01 site. The configuration store details are identical to the first server’s, as they share the same DS instance.

  • The password for --adminPwd must be the same one used for all other servers in the site.

  • The --cookieDomain must be the same as the one used for the first server (example.com).

    If this option isn’t set correctly, you might not be able to sign in to the new server.

  • The --pwdEncKey option specifies the encryption key used by the existing servers in the site. To find this key, sign in to an existing server and go to Deployment > Servers > Server Name > Security > Encryption.

    You must set this option to the correct value. If you don’t, the original encryption key will be overwritten, which will prevent the site from reading the configuration and identity stores.

Post-installation steps for site deployments

All AM servers in a site share the same keystore and secret store infrastructure. This sharing ensures every server in the site can encrypt, decrypt, and verify items like messages and JWTs with the same keys.

The installation process creates these stores only on the first server in the site. You must manually configure them on all other servers you add to the site.

After you’ve used Amster to add a new server to your site, follow these steps:

  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/am/security/keystores/

      • /path/to/am/security/secrets/default/

    • Make the existing site keystores available to the new server in the same location. For example, you might copy the keystores and their password files, or mount a shared volume.

    • Make sure the keystore files configured in the /path/to/am/config/boot.json are available to the new instance.

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

    • Sign in to the AM admin UI of an existing server in the site and go to Configure > Secret Stores.

    • Review the list of globally configured secret stores and make sure the new server has access to the required stores. For example:

      • For keystore-type secret stores, copy the keystores to the same path on the new server.

      • For filesystem-type secret stores, copy the directory contents to the same path, or make the filesystem available on the same mount point.

      • For HSM-type stores, make sure the new server can access the HSM.

      • For secrets configured as environment variables, make sure the new server’s container can access them.

    • Go to Realms > Realm Name > Secret Stores.

    • Review the list of realm-specific secret stores and provide access to the new server as needed.

  3. Restart the new server.

    The server is now fully configured and part of 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.

Check that the suffix you are trying to use exists in DS.

Cannot connect to Directory Server. Invalid Credentials.

Check the credentials you’re using to connect to DS.

Cannot connect to Directory Server. Connect Error: Connection refused.

Check the DS host and connection port.

Unexpected LDAP exception occurred.

Check the DS logs. DS may be stopped or may have become unreachable during the installation.

Cannot connect to Directory Server. Connect Error: The LDAP connection has failed because an error occurred during the SSL handshake…​

Make sure the container where AM is installed trusts the DS SSL certificates.