PingAM 8.0.0

Interactive install

During interactive installation, you customize the parameters of the AM deployment, such as the cookie domain and the settings of the configuration and datastores.

  • Installing the first instance creates the required configuration that the site will share.

    You can specify the site configuration when you install the first instance or configure the site when the first instance is running.

  • By default, the cookie domain is set to the full URL of the first instance; for example, server.west.example.com.

    You can change the cookie domain when you’re installing the first instance or later.

  • You can use a load balancer layer to protect AM services. The load balancer can restrict access to AM services, throttle traffic, offload HTTPS encryption, and so forth.

    As an alternative, or in addition, you can use a separate reverse proxy.

  • When you are protecting AM with a load balancer or proxy service, configure your container so that AM can trust the load balancer or proxy service.

  • The container for each instance in the site must trust any certificate authorities (CA) used to sign certificates used by other instances in the site to communicate using SSL.

  • Successful authentication can depend on information about the authenticating user, such as the IP address where the request originated. When AM is accessed through a load balancer or proxy layer, pass this information along using request headers. Also, configure AM to consume and to forward the headers as necessary. Learn more in Handle HTTP request headers.

Follow these steps to install a single AM instance, or to install the first instance on a site.

  1. Go to your deployment URL. For example, https://am.example.com:8443/am.

  2. On the initial configuration page, click Create New Configuration.

  3. Read the license agreement. Agree to the license agreement and click Continue.

  4. On the Default User Password page, provide a password with at least eight characters for the AM Administrator, amAdmin.

  5. Verify that the server settings are valid for your configuration.

    Server URL

    Provide a valid URL to the base of your AM web container, including an FQDN.

    In a test or QA environment, you can simulate the FQDN by adding it to your /etc/hosts as an alias. The following example shows lines from the /etc/hosts file on a Linux system where AM is installed:

    127.0.0.1 localhost.localdomain localhost
::1 localhost6.localdomain6 localhost6
127.0.1.1 am am.example.com
    Cookie Domain

    The domain for which created cookies will be valid. For example example.com.

    Platform Locale

    The platform locale of your server. Supported locales include en_US (English), de (German), es (Spanish), fr (French), ja (Japanese), ko (Korean), zh_CN (Simplified Chinese), and zh_TW (Traditional Chinese).

    Configuration Directory

    The directory to use for configuration files. AM must be able to write to this directory.

    By default, the configuration directory is located in $HOME/am, where $HOME corresponds to the user who runs the web container.

  6. On the Configuration Data Store page, you can configure options related to AM configuration data.

    The installation process stores AM configuration data in an existing DS server. You must have prepared the server as explained in Prepare a configuration store.

    SSL/TLS Enabled

    Select this option to use LDAPS to communicate with the configuration store. DS is configured for LDAPS by default.

    Before proceeding, make sure you have shared the DS certificate with the container where AM is running. Learn more in Prepare the truststore.

    Host Name

    The FQDN of the DS server.

    Port

    The LDAPS port of the DS server.

    Encryption Key

    A randomly generated key that AM uses for different purposes. All the servers in the site must have the same encryption key.

    The installer creates a random key automatically, which you can use.

    Root Suffix

    The root suffix of the DS store.

    The default base DN of a DS store when you configure it with the am_config profile is ou=am-config.

    Login ID

    The bind DN to use to connect to the DS store.

    The default bind DN of a DS store when you configure it with the am_config profile is uid=am-config,ou=admins,ou=am-config.

    Don’t use cn=admin as the bind account.

    Password

    The password for the bind DN.

    Server configuration

    • New deployment

      The installation is a new deployment, with its own configuration and identity stores.

      If you choose this option, the next step is to configure the identity store.

    • Additional server for existing deployment

      The installation is an additional server for an existing deployment, which uses the existing configuration and identity stores.

      If you choose this option, you don’t need to configure the identity store. The installation uses the same stores as those of the existing deployment.

      Learn more in Add a server to a site.

  7. If you specified New deployment in the previous step, the User Data Store page appears as the next step. Use this page to configure where AM looks for identities.

    AM must have write access to the directory service you choose, because it adds to the directory schema needed to allow AM to manage identity profiles in the identity store.

    User Data Store Type

    If you have already provisioned a directory service with identities in a supported identity store, then select that type of directory from the options available.

    SSL/TLS Enabled

    Select this option to use a secure connection. When using this option, make sure the trust store used by the JVM running AM has the necessary certificates installed. Learn more in Prepare the truststore.

    Directory Name

    The FQDN of the identity store.

    Port

    The LDAPS port of the identity store. Make sure the port you define corresponds to the port the directory server listens to for StartTLS or SSL connections.

    Root Suffix

    The base DN of the identity store.

    If you installed PingDS with the am-identity-store profile, the base DN is ou=identities.

    Login ID

    The directory administrator user DN. The administrator must be able to update the schema and identity profiles.

    If you installed PingDS with the am-identity-store profile, the bind DN to use here is uid=am-identity-bind-account,ou=admins,ou=identities.

    Password

    The password for the directory administrator user.

    If you installed PingDS with the am-identity-store profile, this password is the one you set with am-identity-store/amIdentityStoreAdminPassword.

  8. On the Site Configuration page, you can set up AM as part of a site where the load is balanced across multiple AM servers.

    When you deploy multiple servers, AM automatically enables session high availability.(1) AM stores session data in a directory service that is shared by multiple AM servers. The shared storage means that if an AM server fails, other AM servers in the deployment have access to the user’s session data and can serve requests about that user. As a result, the user doesn’t have to log in again.

    You can also set up a site after initial installation and configuration. Learn more in Configure a site with the first server.

  9. Check the details on the Configurator Summary page.

    • If anything needs changing, click Previous to return to earlier pages and update as needed.

    • If everything is correct, click Create Configuration to proceed. The configuration progress is shown in the browser and also output to the installation log.

  10. When the configuration process completes, click Proceed to Login, and log in as the amAdmin administrator.

    After logging in, the Realms page is displayed.

  11. Restrict permissions to the configuration directory to prevent other users accessing configuration files.

  12. The AM install wizard uses three libraries that should be removed after installation for security reasons.

    When your installation is complete, remove the following .jar files from the WEB-INF/lib directory:

    • click-extras-2.3.0.jar

    • click-nodeps-2.3.0.jar

    • velocity-1.7.jar

      These files are used only by the install and upgrade wizards. Removing them will have no effect on your installed instance.

    You must also remove the references to click-servlet from the deployment descriptor file. Edit /path/to/tomcat/webapps/am/WEB-INF/web.xml to remove the following mappings:

    <servlet>
    <servlet-name>click-servlet</servlet-name>
    <servlet-class>org.apache.click.ClickServlet</servlet-class>
</servlet>

...

<servlet-mapping>
    <servlet-name>click-servlet</servlet-name>
    <url-pattern>*.htm</url-pattern>
</servlet-mapping>

  13. Review the suggested next steps after installing AM.

(1) You can configure AM to store sessions in the Core Token Service (CTS) token store or on the client. Because client-side sessions reside in HTTP cookies, they don’t need to be retrieved from a persistent datastore. In the event of a server failure, they can be retrieved from the cookies. AM doesn’t store client-side sessions in the CTS token store. You can find details about sessions in Introduction to sessions.