PingAM 7.5.1

Configure sites and add servers

Configuring a site is a three-step process:

  1. Install the first server in the site. This will create the configuration that the site will share.

    Learn more in Install an instance.

  2. Add the first server to a site, if you did not already while installing it.

    Learn more in Configure a site with the first server.

  3. Add more servers to the site.

    Learn more in Add a server to a site.

Configure a site with the first server

The following steps show how to set up a site when AM is running:

  1. Review AM’s load balancing requirements in Load balancing.

  2. In the AM admin UI, go to Deployment > Sites.

  3. Click Add a Site to start configuring the new site.

  4. On the New Site page, enter the site name without any spaces. For example, the site name must be in the format ExampleSite, rather than Example Site.

    Set the Primary URL to the load balancer URL that is the entry point for the site, such as https://lb.example.com/am.

    The site URL is the URL to the load balancer in front of the AM servers in the site. For example, if your load balancer listens for HTTPS on host lb.example.com and port 443 with AM under /am, then your site URL is https://lb.example.com/am.

    Client applications and web or Java agents access the servers in the site through the site URL.

  5. Click Save to keep the site configuration.

  6. Configure the cookie domain of your site as required. Learn more in Change the cookie domain.

  7. Go to Deployment > Servers > Server Name > General.

  8. Set the Parent Site drop-down menu to the name of the site you just created, and save your changes.

    At this point, the first server is part of the new site you have configured.

    For all additional servers in the AM site, add them to the site at configuration time as described in Add a server to a site.

Add a server to a site

High availability requires redundant servers in case of failure. With AM, you configure an AM site with multiple servers in a pool behind a load balancing service that exposes a single URL as an entry point to the site.

Follow these steps to configure a server to an existing site:

  1. Go to the deployment URL of the new instance to display the AM configurator page.

  2. In the initial configuration screen, under Custom Configuration, click Create New Configuration.

  3. In the first screen, enter the same password you entered for the AM administrator, amAdmin, when you configured the first server in the site.

  4. Configure server settings as required.

    The cookie domain should be identical to that of the first server in the site.

    The installer may show that the Configuration Directory is not empty; it is a warning in case you are trying to use a directory that contains data not pertaining to AM.

  5. In the configuration store screen, ensure that you select the External DS option, and configure the same DS instance that is already working as the configuration store for the rest of the instances in the site, including the same encryption key.

    Ensure that you also select the Additional server for existing deployment option.

    Instances using the embedded DS cannot be part of a site.

  6. In the site configuration screen, select Yes, and enter the same Site Name and Load Balancer URL values as the existing servers in the site.

    Spaces are not allowed in the site name.

    Settings for agent information are also shared with the existing server, so the corresponding wizard screen is skipped.

  7. In the summary screen, verify the settings you chose, and click Create Configuration.

  8. When the configuration process finishes, stop the newly-installed AM instance or the container where it runs, and do not try to access it.

  9. Compare the /path/to/openam/config/boot.json bootstrap file with that of a running instance. You must ensure that the newly installed instance’s bootstrap file is appropriate for your environment.

    The boot.json file does not exist in the new instance

    Depending on the configuration of the AM keystore in the site, the installation process may not create the bootstrap file.

    If so, copy the bootstrap file from another instance and continue with the procedure.

    Unless your environment has a requirement to configure the AM keystore in a different location on each instance, it is likely that the bootstrap file should be the same across the site.

    If you are overriding the start up settings:

    • Ensure you have copied the customized bootstrap file from another instance in the site.

    • Ensure you are overwriting the existing bootstrap file with your modified file prior to every AM restart.

  10. Make the existing AM 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 instance.

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

    • In the AM admin UI of an existing instance in the site, go to Configure > Secret Stores.

    • Review the list of secret stores configured globally and 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.

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

  12. Restart the new instance.

    The instance is now configured for the site.

  13. Review AM’s load balancing requirements in Load balancing.

  14. Ensure that the cookie domain configuration is appropriate for your site. Learn more in Change the cookie domain.