Installing an Instance

You can customize several AM parameters during installation, such as the cookie domain and the settings of the configuration store.

Perform the steps in the following procedure to install a single AM instance, or to install the first instance on a site.

  • 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 in order to communicate using SSL.

  • AM authentication can depend on information about the user to authenticate, 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. Refer to "Handling HTTP Request Headers" for details.

To Configure an Instance
  1. Navigate to your deployment URL. For example, https://openam.example.com:8443/openam.

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

  3. Read the license agreement. If you agree to the license, click "I agree to the license agreement", and then click Continue.

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

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

    AM server settings
    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 openam openam.example.com
    Cookie Domain

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

    Platform Locale

    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

    Location on server for AM configuration files. AM must be able to write to this directory.

  6. In the Configuration Data Store screen, you make choices related to AM configuration data.

    AM configuration store
    Configuration Store
    • Embedded DS

      The configurator process spins an embedded DS instance to store AM configuration data, the default users, and the CTS store. Use on demo or test environments only.

      Instances using the embedded DS server cannot be added to a site.

      If you choose the embedded DS, you can leave the rest of the values by default.

    • External DS

      The configurator process stores AM configuration data in an existing DS server. You must have prepared the server as explained in "Preparing Configuration Stores".

      Choose this option if you intend to add this instance to an existing deployment.

      An external DS instance is required in non-evaluation deployments.

      If you choose the external DS, you must configure the rest of the fields.

    SSL/TLS Enabled

    Whether AM must use LDAPS to communicate with the configuration store.

    For security reasons, the configuration store should communicate with AM using LDAPs.

    DS 7 is configured for LDAPS by default. If you are using this version, enable this option and share the DS certificate with the container where AM is running before continuing. For more information, refer to "Securing Directory Server Communication".

    If you are using a different version, you can configure DS and AM to use LDAPS after the installation.

    Host Name

    The FQDN of the external DS.

    Port

    The LDAP or LDAPS port of the external DS. The default values are:

    • LDAP: 1389

    • LDAPS: 1636

    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; you can leave the value by default.

    Root Suffix

    The root suffix of the external DS store.

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

    Login ID

    The bind DN that AM should use to connect to the external DS store.

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

    Do not use cn=admin as the bind account.

    Password

    The password of the bind DN.

    Server configuration

    Note that this option only appears when you specify an external configuration store.

    • New deployment

      Specifies that 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

      Specifies that the installation is an additional server for an existing deployment and will use 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.

      For more information, refer to "To Add a Server to a Site".

  7. (Optional) If you specified New deployment in the previous step, the User Store screen appears as the next step. Use the page to configure where AM looks for user identities.

    AM must have write access to the directory service you choose, as it adds to the directory schema needed to allow AM to manage access for users in the user store.

    AM user store settings
    User Data Store Type

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

    SSL/TLS Enabled

    To use a secure connection, check this box, then make sure the port you define corresponds to the port the directory server listens to for StartTLS or SSL connections. When using this option, you also need to make sure the trust store used by the JVM running AM has the necessary certificates installed.

    Directory Name

    FQDN for the host housing the directory service.

    Port

    LDAP directory port. The default for LDAP and LDAP with StartTLS to protect the connection is port 389. The default for LDAP over SSL is port 636. Your directory service might use a different port.

    Root Suffix

    Base distinguished name (DN) where user data is stored.

    Login ID

    Directory administrator user DN. The administrator must be able to update the schema and user data.

    Password

    Password for the directory administrator user.

  8. In the Site Configuration screen, 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.[2] 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 does not have to log in again.

    AM site configuration

    It is possible to set up a site after initial installation and configuration. See Deployment Configuration for more information.

  9. Check the summary screen, and if necessary, click Previous to return to earlier screens to fix any configuration errors as needed.

    AM configuration summary

    After you click Create Configuration in the summary screen, configuration proceeds, logging progress that you can read in your browser, and later, in the installation log. The process ends, and AM shows the Proceed to Login prompt.

    AM proceed to login prompt
  10. When the configuration completes, click Proceed to Login, and then log in as the AM administrator, amAdmin.

    AM first login

    After logging in, AM redirects you to the AM Realms page.

    The AM console home page

    You can also access the AM console by going to the console URL; for example https://openam.example.com:8443/openam/console.

  11. Restrict permissions to the configuration directory (by default, $HOME/openam, where $HOME corresponds to the user who runs the web container). Prevent other users from accessing files in the configuration directory.

  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.

  13. Review the suggested next steps after installing AM. See Next Steps.



[2] You can configure AM to store sessions in the Core Token Service (CTS) token store or on the client. Because client-based sessions reside in HTTP cookies, they do not need to be retrieved from a persistent data store. In the event of a server failure, they can be retrieved from the cookies. AM does not store client-based sessions in the CTS token store. For more information about sessions, see Introducing Sessions.

Read a different version of :