Guide showing you how to install ForgeRock® Access Management. ForgeRock Access Management provides authentication, authorization, entitlement, and federation software.

1. Stop JBoss or WildFly.

2. The default JVM settings do not allocate sufficient memory to AM. This step shows one method that you can use to modify the JVM settings. For other methods, see either the JBoss Application Server Official Documentation Page or the JVM Settings page in the WildFly documentation

   1. Open the standalone.conf file in the /path/to/jboss/bin directory for JBoss or WildFly in standalone mode.

   2. Check the JVM settings associated with JAVA_OPTS.

      Change the JVM heap size to -Xmx1g. The default JVM heap size for some versions of JBoss might already exceed the recommended value. If you are using the embedded version of DS, the minimum heap size may be higher. For details on the JVM options to use, see "Preparing a Java Environment".

      Change the metaspace size to -XX:MaxMetaspaceSize=256m if the default size does not exceed this amount.

   3. Set the following JVM JAVA_OPTS setting in the same file:

      -Dorg.apache.tomcat.util.http.ServerCookie.ALWAYS_ADD_EXPIRES=true

      Verify that the headers include the Expires attribute rather than only Max-Age, as some versions of Internet Explorer and Microsoft Edge do not support Max-Age.

3. Set up Wildfly for Social Authentication, by performing the following steps:

   1. Ensure the Wildfly server is running.

   2. Go to the Wildfly Path.

   3. In the $JBOSS_HOME/bin directory, run the jboss-cli.sh script file:

      $ ./bin/jboss-cli.sh

   4. Type "connect" to connect to the server.

   5. Enable use of the equals (=) symbol in cookies by running the following command:

      For example:

      [standalone@localhost:9990 /] /subsystem=undertow/server=default-server/
      http-listener=default:write-attribute(name=allow-equals-in-cookie-value,
      value=true)
      {
         "outcome" => "success",
         "response-headers" => {
            "operation-requires-reload" => true,
            "process-state" => "reload-required"
          }
      }
             

   6. Restart Wildfly.

4. Now deploy the openam.war file into the appropriate deployment directory. The directory varies depending on whether you are running in standalone or domain mode.

To prepare AM to run with JBoss or WildFly, you should make some changes to the default AM war file. JBoss and WildFly deploy applications from different temporary directories every time you restart the container, which would require reconfiguring AM. To avoid problems, change the AM war file as follows:

1. If you have not already done so, create a temporary directory and expand the AM-6.5.5.war file. For example:

   $ cd /tmp
   $ mkdir /tmp/openam ; cd /tmp/openam
   $ jar xvf ~/Downloads/AM-6.5.5.war

2. Locate the bootstrap.properties file in the WEB-INF/classes directory of the expanded war archive. Update the # configuration.dir= line in this file to specify a path with read and write permissions, and then save the change.

   # This property should also be used when the system user that
   # is running the web/application server process does not have
   # a home directory. i.e. System.getProperty("user.home") returns
   # null.
   
   configuration.dir=/my/readwrite/config/dir

3. If you are deploying AM on JBoss AS or JBoss EAP, remove the jboss-all.xml file from the WEB-INF directory of the expanded war archive.

   Be sure not to remove this file if you are deploying AM on WildFly.

4. If you are deploying AM on Wildfly 12, remove the jul-to-slf4j-1.7.21.jar file from the WEB-INF/lib directory of the expanded war archive.

5. Rebuild the openam.war file.

   $ jar cvf ../openam.war *

6. If you plan to deploy multiple cookie domains with WildFly, you must configure the com.sun.identity.authentication.setCookieToAllDomains property after you have installed the AM server. See "Handling Multiple Cookie Domains When Using Wildfly" for more information.

To prepare AM to run in Oracle WebLogic, you must change the AM war file. Be sure to make these changes whenever you deploy a new war file, or as part of an AM upgrade.

Prepare for deployment in Oracle WebLogic as follows:

1. Create a temporary directory and expand the AM-6.5.5.war file. For example:

   $ cd /tmp
   $ mkdir /tmp/openam ; cd /tmp/openam
   $ jar xvf ~/Downloads/AM-6.5.5.war

2. Ensure the installer is able to locate configuration files by specifying a folder which the user running Oracle WebLogic can read and write:

   1. Locate the bootstrap.properties file in the WEB-INF/classes directory of the expanded war file.

   2. Update the # configuration.dir= line in the bootstrap.properties file to specify a path with read and write permissions. For example:

      # This property should also be used when the system user that
      # is running the web/application server process does not have
      # a home directory. i.e. System.getProperty("user.home") returns
      # null.
      
      configuration.dir=/my/readwrite/config/dir

      If installing on Windows, the specified path should have slashes / and not backslashes \.

3. Rebuild the AM-6.5.5.war file:

   $ jar cvf ../Edited-AM-6.5.5.war *

4. Ensure Oracle WebLogic passes responsibility for account management over to AM, as follows:

   1. Ensure Oracle WebLogic is not running.

   2. Navigate to the Oracle WebLogic config.xml configuration file for the domain in which AM runs.

      For example, $HOME/Oracle/Middleware/Oracle_Home/user_projects/domains/base_domain/config/config.xml.

   3. In the <security-configuration> section, add the following line before the closing </security-configuration> tag:

      <enforce-valid-basic-auth-credentials>false</enforce-valid-basic-auth-credentials>

      For example:

          <enforce-valid-basic-auth-credentials>false</enforce-valid-basic-auth-credentials>
      </security-configuration>

5. Configure the Oracle WebLogic domain to use the canonical path of resource files by performing the following steps:

   1. In the Oracle WebLogic console, in the Domain Structure panel, click the name of the domain. For example, base_domain.

   2. On the Configuration tab, click the Web Applications tab, and then enable the Archived Real Path Enabled property.

   3. Save your changes, and restart Oracle WebLogic for them to take effect.

6. You can now deploy your Edited-AM-6.5.5.war in Oracle WebLogic.

To prepare AM to run in WebSphere, change the AM war file to ensure that the AM upgrade process is able to find the AM configuration files. Be sure to make this change whenever you deploy a new war file as part of an AM upgrade.

Change the AM war file as follows:

1. Create a temporary directory and expand the AM-6.5.5.war file. For example:

   $ cd /tmp
   $ mkdir /tmp/openam ; cd /tmp/openam
   $ jar xvf ~/Downloads/AM-6.5.5.war

2. Locate the bootstrap.properties file in the WEB-INF/classes directory of the expanded war file.

   Update the # configuration.dir= line in the bootstrap.properties file to specify a path with read and write permissions. For example:

   # This property should also be used when the system user that
   # is running the web/application server process does not have
   # a home directory. i.e. System.getProperty("user.home") returns
   # null.
   
   configuration.dir=/my/readwrite/config/dir

3. (Optional) If you are using an IBM JDK, replace the default WEB-INF/template /keystore/keystore.jceks keystore file with one generated using the IBM JDK, by performing the following steps:

   1. Generate a new, empty keystore.jceks keystore file in IBM JDK format:

      $ keytool -genkey -storetype jceks -keystore keystore.jceks -storepass changeit -keypass changeit

   2. Copy the new keystore.jceks keystore file into the expanded .war file, overwriting the existing WEB-INF/template/keystore/keystore.jceks keystore file:

      $ cp keystore.jceks /tmp/openam/WEB-INF/template/keystore/keystore.jceks

4. Rebuild the AM-6.5.5.war file:

   $ jar cvf ../AM-6.5.5.war *

In addition to preparing the AM .war file, perform the following steps to configure WebSphere for AM after you deploy AM into WebSphere:

1. Load classes from AM bundled libraries before loading classes from libraries delivered with WebSphere:

   1. In the WebSphere administration console, navigate to Application > Application Type > WebSphere enterprise applications > AM Name > Class loading and update detection.

   2. Set Class loader order > Classes loaded with local class loader first (parent last).

   3. Ensure that the value of the WAR class loader policy property is set to the default value: Class loader for each WAR file in application.

   4. Save your work.

2. (Optional) If your environment uses SOAP, perform the following steps to add SOAP-related properties to the JVM:

   1. In the WebSphere administration console, select Servers.

   2. Expand Server Type, and select WebSphere application servers.

   3. Select your WebSphere server name.

   4. Expand Java and Process Management, and select Process Definition.

   5. Under the Additional Properties section, select Java Virtual Machine.

   6. Locate the Generic JVM argument box and add the following properties:

      -Djavax.xml.soap.MessageFactory=com.sun.xml.internal.messaging.saaj.soap.ver1_1.SOAPMessageFactory1_1Impl
      -Djavax.xml.soap.SOAPFactory=com.sun.xml.internal.messaging.saaj.soap.ver1_1.SOAPFactory1_1Impl
      -Djavax.xml.soap.SOAPConnectionFactory=com.sun.xml.internal.messaging.saaj.client.p2p.HttpSOAPConnectionFactory
      -Djavax.xml.soap.MetaFactory=com.sun.xml.internal.messaging.saaj.soap.SAAJMetaFactoryImpl
      -Dcom.ibm.websphere.webservices.DisableIBMJAXWSEngine=true

   7. Save your work.

1. If you have not yet deployed AM:

   1. Unpack the AM .war file. For example:

      $ mkdir /tmp/openam
      $ cd /tmp/openam/
      $ jar -xf ~/Downloads/openam/AM-6.5.5.war

   2. Open the deployment descriptor file WEB-INF/web.xml in a text editor.

2. If you have already deployed AM:

   1. Open the deployment descriptor file web.xml in a text editor. The location of the file depends on your web application container, for example in Tomcat it might be located at: /path/to/tomcat/webapps/openam/WEB-INF/web.xml.

3. In the deployment descriptor file, add a <filter-mapping> element containing the name and a URL pattern for the filter. The URL pattern specifies the endpoints to which AM applies the CORS filter.

   To enable CORS support for all endpoints, use the following example:

   <filter-mapping>
       <filter-name>CORSFilter</filter-name>
       <url-pattern>/*</url-pattern><!-- CORS support for all endpoints -->
   </filter-mapping>
   

   To enable CORS support for individual endpoints instead of all endpoints, add multiple <filter-mapping> elements, one for each endpoint:

   <filter-mapping>
     <filter-name>CORSFilter</filter-name>
     <url-pattern>/uma/*</url-pattern>
   </filter-mapping>
   
   <filter-mapping>
     <filter-name>CORSFilter</filter-name>
     <url-pattern>/json/*</url-pattern>
   </filter-mapping>
   
   <filter-mapping>
     <filter-name>CORSFilter</filter-name>
     <url-pattern>/oauth2/*</url-pattern>
   </filter-mapping>
   

4. In the deployment descriptor file, add a <filter> element to configure the filter.

   The available parameters for the <filter> element are as follows:

   <filter-name>

   Specifies the name for the filter. Must match the name specified in the <filter-mapping> elements.

   <filter-class>

   Specifies the Java class the implements the CORS filter. Should be set to the default org.forgerock.openam.cors.CORSFilter.

   methods (required)

   A comma-separated list of HTTP methods allowed when making CORS requests to AM.

   Example: GET,POST,PUT,PATCH,OPTIONS,DELETE

   origins (required)

   A comma-separated list of the origins allowed when making CORS requests to AM. Wildcards are not supported - each value should be an exact match for the origin of the CORS request.

   Example: http://example.com,https://example.org:8433

   Tip

   During development you may not be using fully-qualified domain names as the origin of a CORS request, for example using the file:// protocol locally. If so, you can add these non-FQDN origins to the list. For example, http://example.com,https://example.org:8433,file://,null.

   allowCredentials (optional)

   Whether to take allow requests with credentials in either HTTP cookies or HTTP authentication information. Accepts false (the default) or true.

   Set to true if you send Authorization headers as part of the CORS requests, or need to include information in cookies when making requests.

   headers (optional)

   A comma-separated list of request header names allowed when making CORS requests to AM.

   Example: iPlanetDirectoryPro,X-OpenAM-Username,X-OpenAM-Password,Accept-API-Version,Content-Type,If-Match,If-None-Match

   By default, the following simple headers are explicitly allowed:

   • Cache-Control

   • Content-Language

   • Expires

   • Last-Modified

   • Pragma

   If you do not specify a value for this property, the presence of any header in the CORS request, other than the simple headers listed above, will cause the request to be rejected.

   Headers commonly used when accessing an AM server include the following:

   Commonly Used Headers

   Header	Information
   iPlanetDirectoryPro	Used for session information. See "Implementing Client-Based Sessions" in the Authentication and Single Sign-On Guide.
   X-OpenAM-Username,X-OpenAM-Password	Used to pass credentials in REST calls that use the HTTP POST method. See "Authentication and Logout using REST" in the Authentication and Single Sign-On Guide.
   Accept-API-Version	Used to request a specific AM endpoint version. See "REST API Versioning" in the Authentication and Single Sign-On Guide.
   Content-Type	Required for cross-origin calls to AM REST API endpoints.
   If-Match,If-None-Match	Used to ensure the correct version of a resource will be affected when making a REST call, for example when updating an UMA resource. See "To Update an UMA Resource" in the User-Managed Access (UMA) 2.0 Guide .

   
   

   Caution

   If you need to accept all origins by allowing the use of Access-Control-Allowed-Origin=* headers, do not allow Content-Type headers. Allowing the use of both types of headers exposes AM to cross-site request forgery (CSRF) attacks.

   expectedHostname (optional)

   The name of the host expected in the Host header of CORS requests to AM. The request will be refused if the specified value does not match.

   If not specified, any host value is accepted.

   If the AM server is behind a load-balancer, specify the public name of the load balancer.

   Example: openam.example.com:8080

   exposeHeaders (optional)

   A comma-separated list of response header names that AM returns in the Access-Control-Expose-Headers header.

   User agents can make use of any headers that are listed in this property, as well as the simple response headers, which are as follows:

   • Cache-Control

   • Content-Language

   • Expires

   • Last-Modified

   • Pragma

   • Content-Type

   User agents must filter out all other response headers.

   Example: Access-Control-Allow-Origin,Access-Control-Allow-Credentials,Set-Cookie

   maxAge (optional)

   The maximum length of time that the browser is allowed to cache the pre-flight response, in seconds.

   The default is 600.

   The following is an example excerpt from a configured web.xml file that could be used during testing and development:

   <filter-mapping>
     <filter-name>CORSFilter</filter-name>
     <url-pattern>/uma/*</url-pattern>
   </filter-mapping>
   
   <filter-mapping>
     <filter-name>CORSFilter</filter-name>
     <url-pattern>/json/*</url-pattern>
   </filter-mapping>
   
   <filter-mapping>
     <filter-name>CORSFilter</filter-name>
     <url-pattern>/oauth2/*</url-pattern>
   </filter-mapping>
   
   <filter>
     <filter-name>CORSFilter</filter-name>
     <filter-class>org.forgerock.openam.cors.CORSFilter</filter-class>
     <init-param>
       <param-name>methods</param-name>
       <param-value>POST,PUT,OPTIONS</param-value>
     </init-param>
     <init-param>
       <param-name>origins</param-name>
       <param-value>http://localhost:8000,null,file://,https://example.org:8433</param-value>
     </init-param>
     <init-param>
       <param-name>allowCredentials</param-name>
       <param-value>true</param-value>
     </init-param>
     <init-param>
       <param-name>headers</param-name>
       <param-value>X-OpenAM-Username,X-OpenAM-Password,X-Requested-With,Accept,iPlanetDirectoryPro</param-value>
     </init-param>
     <init-param>
       <param-name>expectedHostname</param-name>
       <param-value>openam.example.com:8080</param-value>
     </init-param>
     <init-param>
       <param-name>exposeHeaders</param-name>
       <param-value>Access-Control-Allow-Origin,Access-Control-Allow-Credentials,Set-Cookie</param-value>
     </init-param>
     <init-param>
       <param-name>maxAge</param-name>
       <param-value>1800</param-value>
     </init-param>
   </filter>
   

5. Save your changes.

6. If you have not yet deployed AM:

   1. Pack up the AM .war file to deploy.

      $ jar -cf ../openam.war *

   2. Deploy the new .war file.

      In this example, the .war file to deploy is /tmp/openam.war.

      For more information, see "Deploying".

7. If you have already deployed AM:

   1. Restart AM or the web container where it runs.

• Edit your container startup scripts, for example setenv.sh, to set the following JVM system properties in Tomcat:

  JAVA_OPTS="$JAVA_OPTS -Dcom.iplanet.security.encryptor=org.forgerock.openam.shared.security.crypto.AESWrapEncryption"
  JAVA_OPTS="$JAVA_OPTS -Dorg.forgerock.openam.encryption.key.iterations=10000"
  JAVA_OPTS="$JAVA_OPTS -Dorg.forgerock.openam.encryption.key.size=256"
  JAVA_OPTS="$JAVA_OPTS -Dorg.forgerock.openam.encryption.key.digest=SHA512"
  JAVA_OPTS="$JAVA_OPTS -Dorg.forgerock.openam.encryption.padshortinputs"

  Only the first line in the example is required. The other lines are configurable to meet the needs of your deployment. Key sizes greater than 128 bits require that the JCE Unlimited Strength policy files be installed in your system. PBKDF2 using SHA256, SHA384, and SHA512 is only available on Java 8.

  For systems running Java 17, the org.forgerock.openam.encryption.padshortinputs property pads short inputs (less than 8 bytes). If you are using Java 17 with AES Key Wrap Encryption, enable this system property and re-encrypt any short system passwords that have already been encrypted. If you do not do this, AM will be unable to decrypt the short values.

  Note

  You cannot change these configuration parameters once AM has been installed.

After you enable AES key wrap encryption, update the ssoadm command to work with the new encryption settings.

• Add the following properties to the /path/to/ssoadm/setup and /path/to/ssoadm/bin/ssoadm commands:

  -Dcom.iplanet.security.encryptor=org.forgerock.openam.shared.security.crypto.AESWrapEncryption
  -Dorg.forgerock.openam.encryption.key.iterations=10000
  -Dorg.forgerock.openam.encryption.key.size=256
  -Dorg.forgerock.openam.encryption.key.digest=SHA512

The AM-6.5.5.war file contains the AM server. How you deploy the .war file depends on your web application container.

1. Deploy the .war file on your container.

   For example, copy the file to deploy on Apache Tomcat.

   $ cp AM-6.5.5.war /path/to/tomcat/webapps/openam.war

   During trials or development, you can change the file name to openam.war when deploying in Tomcat, so that the deployment URI is /openam.

   When installing AM in a production environment, do not use a predictable deployment URI such as /openam or /opensso.

   Note

   You change the file name to something other than openam.war when deploying in Tomcat so that the deployment URI is not /openam. For helpful hints on avoiding obvious deployment defaults, see "Avoiding Obvious Defaults".

   Important

   To properly configure AM, AM requires a deployment URI with a non-empty string after /. Do not deploy AM at the root context. Do not rename the .war file to ROOT.war before deploying on Tomcat, for example.

   It can take several seconds for AM to be deployed in your container.

2. Navigate to the initial configuration screen, for example https://openam.example.com:8443/openam.

   

   AM is now ready for installation. To proceed, take on of the following actions:

   • Configure external data stores using the files created during deployment. See "Preparing External Stores".

   • Use the embedded data stores for evaluation purposes, and skip ahead to installing AM. See "Installing a Single Server".

Directory Services 6.5 added support for setup profiles to greatly simplify initial configuration.

Using a setup profile will create the backend, schema, bind user, and indexes required for use with identity data.

1. To install DS using a setup profile, follow the steps in To Use DS for AM Identity Data in the Directory Services 6.5 Installation Guide.

2. The following steps update the permissions in an external Directory Services identity repository. For other directory servers, apply the relevant LDIF files using the appropriate tools.

   1. Edit the opendj_userinit.ldif LDIF file in the /path/to/openam/WEB-INF/template/ldif/opendj directory, replacing all variables that are surrounded by at (@) symbols with a value specific to your directory server.

      For example, in the opendj_userinit.ldif LDIF file you must replace all instances of @userStoreRootSuffix@ with the root suffix you specified when configuring the external DS identity store, the default being ou=identities.

      Tip

      For information on downloading and deploying the AM .war file, see "Downloading and Deploying".

   2. Use the ldapmodify command to add the updated LDIF data to the external instance. For example:

      $ ./ldapmodify \
      --hostname 'id.example.com' \
      --port 1389 \
      --useStartTLS \
      --trustAll \
      --continueOnError \
      --bindDN uid=admin \
      --bindPassword 'str0ngEx4mplePa55word' \
      /path/to/tomcat/webapps/openam/WEB-INF/template/ldif/opendj/opendj_userinit.ldif

      For more information on this LDIF file, and equivalent files for supported directory servers, see "Supported LDIF Files".

3. (Optional) If you intend to use push or web authentication, you may need to update the directory server schema. You can ensure the correct parameters are available by applying the following LDIF files:

   • /path/to/openam/WEB-INF/template/ldif/opendj/push_2fa.ldif

   • /path/to/openam/WEB-INF/template/ldif/opendj/opendj_webauthndevices.ldif

   For example:

   $ ./ldapmodify \
   --hostname 'id.example.com' \
   --port 1389 \
   --useStartTLS \
   --trustAll \
   --continueOnError \
   --bindDN 'cn=Directory Manager' \
   --bindPassword 'str0ngEx4mplePa55word' \
   /path/to/tomcat/webapps/openam/WEB-INF/template/ldif/opendj/push_2fa.ldif \
   /path/to/tomcat/webapps/openam/WEB-INF/template/ldif/opendj/opendj_webauthndevices.ldif

   For more information on these LDIF files, and the equivalent files for supported directory servers, see "Supported LDIF Files".

4. Proceed to configuring the identity store in AM. See "Setting Up Identity and Data Stores" in the Setup and Maintenance Guide.

   The bind account to use when configuring the identity store in AM is uid=am-identity-bind-account,ou=admins,ou=identities.

Directory Services 6.5 added support for setup profiles to greatly simplify initial configuration.

Using a setup profile will create the backend, schema, bind user, and indexes required for use with policy and/or application data. Note that policy and application data has the same schema requirements as configuration data.

1. To install DS using a setup profile, follow the steps in To Use DS for AM Configuration Data in the Directory Services 6.5 Installation Guide.

   Important

   Ensure that you specify the same base DN value as your configuration store (whether it is embedded or external) when using a setup profile to create a policy or application store. For example:

   --set am-config/baseDn:"dc=example,dc=com"

   Creating a separate DS backend for policies and/or applications in the configuration store is not supported.

2. You have successfully installed and prepared the DS directory server for use as an external policy or application store.

   You can use the instance created in these procedures for both policy and application data simultaneously. To have separate instances for policies and applications, repeat the previous step to create an additional external policy or application store.

   Proceed to configuring AM to use the prepared DS directory servers as external policy or application stores, see "Setting Up External Data Stores" in the Setup and Maintenance Guide.

   The default bind account to use when configuring AM to use the external store takes the format:

   uid=am-config,ou=admins,Base DN

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. Navigate to the deployment URL of the new instance. You should see 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 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.

   Note

   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, select Add to Existing Deployment, and enter the URL of the first AM server in the site.

   The directory used to store configuration data should use the same directory service used for this purpose by other AM servers in the site. If you use the embedded DS server, for example, you can set up the configurator for data replication with embedded directory servers used by other servers in the site.

   Settings for the user store are then shared with the existing server, so the corresponding wizard screen is skipped.

6. In the site configuration screen, select Yes and enter the same site configuration details as for the first server in the site.

   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 then 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/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.

   Depending on the configuration of the AM keystore in the site, the installation process may not create the bootstrap file. If this is your case,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:

    1. Back up the new instance's default keystore and password files. By default, they are located in the /path/to/openam/openam directory.

    2. 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.

    3. Ensure that the keystore files configured in the /path/to/openam/boot.json file are available to the instance.

       If this keystore and its files are not accessible, the AM instance will not start.

       For more information about the boot.json file, see "Startup Settings in the Bootstrap File".

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

    1. Log in to the AM console of an existing instance in the site and navigate to Configure > Secret Stores.

    2. 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.

    3. Navigate to Realms > Realm Name > Secret Stores.

    4. 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. Ensure that the cookie domain configuration is appropriate for your site. For more information, see "Changing the Cookie Domain" in the Setup and Maintenance Guide.

The following steps show how to set up the site for the first AM server.

1. Log in to the AM console as administrator, by default amadmin, and then navigate to Deployment > Sites.

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

3. On the New Site page enter the site name, and set the Primary URL to the load balancer URL that is the entry point for the site, such as https://lb.example.com/openam.

   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 /openam, then your site URL is https://lb.example.com/openam.

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

4. Click Save to keep the site configuration.

5. Configure the cookie domain of your site as required. For more information, see "Changing the Cookie Domain" in the Setup and Maintenance Guide.

6. Navigate to Deployment > Servers > Server Name > General.

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

   At this point, the 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 "To Add a Server to a Site".

1. Verify that AM is installed and running before proceeding.

2. Verify that the JAVA_HOME environment variable is set properly:

   $ echo $JAVA_HOME
   /path/to/jdk

3. Create a file system directory to unpack the tools:

   $ mkdir -p /path/to/openam-tools/admin

4. Unpack the tools:

   $ cd /path/to/openam-tools/admin
   $ unzip ~/Downloads/openam/SSOAdminTools-5.1.2.24.zip

5. Add --acceptLicense to the java command at the end of the setup or setup.bat script if you want to auto-accept the license agreement and suppress the license acceptance screen to the user:

   $JAVA_HOME/bin/java -D"load.config=yes" \
                       -D"help.print=$help_print" \
                       -D"path.AMConfig=$path_AMConfig" \
                       -D"path.debug=$path_debug" \
                       -D"path.log=$path_log" \
                       -cp "$CLASSPATH" com.sun.identity.tools.bundles.Main \
                       --acceptLicense

6. (Optional) If you use IBM Java, add -D"amCryptoDescriptor.provider=IBMJCE" and -D"amKeyGenDescriptor.provider=IBMJCE" options to the setup or setup.bat script before you install the tools.

   The options should be set for the java command at the end of the script:

   $ tail setup
   CLASSPATH="$CLASSPATH:resources"
   
   $JAVA_HOME/bin/java -D"load.config=yes" \
                       -D"help.print=$help_print" \
                       -D"path.AMConfig=$path_AMConfig" \
                       -D"path.debug=$path_debug" \
                       -D"path.log=$path_log" \
                       -D"amCryptoDescriptor.provider=IBMJCE" \
                       -D"amKeyGenDescriptor.provider=IBMJCE" \
                       -cp "$CLASSPATH" \
                       com.sun.identity.tools.bundles.Main

7. Run the setup utility (setup.bat on Windows), providing paths to the directories where AM configuration files are located, and where debug and log information will be located:

   $ ./setup
   Path to config files of OpenAM server [/home/user/openam]:
   Debug Directory [/path/to/openam-tools/admin/debug]:
   Log Directory [/path/to/openam-tools/admin/log]:
   The scripts are properly setup under directory:
    /path/to/openam-tools/admin/openam
   Debug directory is /path/to/openam-tools/admin/debug.
   Log directory is /path/to/openam-tools/admin/log.
   The version of this tools.zip is: version and date
   The version of your server instance is: OpenAM version and date

   After setup, the tools are located under a directory named after the instance of AM:

   $ ls openam/bin/
   ampassword  amverifyarchive  ssoadm

   On Windows, these files are .bat scripts.

8. (Optional) If your web container uses a self-signed certificate as described in "To Set Up With HTTPS and Self-Signed Certificates", then the ssoadm command will not trust the certificate when connecting to AM over HTTPS, or when AM connects to the configuration store over LDAPS.

   To allow the ssoadm command to trust the certificate, add the -D"javax.net.ssl.trustStore=/path/to/tomcat/conf/keystore.jks" option to the ssoadm or ssoadm.bat script before using the script.

   The option should be set before the call to com.sun.identity.cli.CommandManager at the end of the script:

   $ tail -2 /path/to/openam-tools/admin/openam/bin/ssoadm
       -D"javax.net.ssl.trustStore=/path/to/tomcat/conf/keystore.jks" \
       com.sun.identity.cli.CommandManager "$@"

   Note

   In non-production environments, you can configure the ssoadm command to trust all server certificates. For more information, see Q. How do I configure ssoadm to trust all certificates? in the ForgeRock Knowledge Base.

9. (Optional) If you use IBM Java, add -D"amCryptoDescriptor.provider=IBMJCE" and -D"amKeyGenDescriptor.provider=IBMJCE" options to the ssoadm or ssoadm.bat script before using the script.

   The options should be set before the call to com.sun.identity.cli.CommandManager at the end of the script:

   $ tail -3 /path/to/openam-tools/admin/openam/bin/ssoadm
       -D"amCryptoDescriptor.provider=IBMJCE" \
       -D"amKeyGenDescriptor.provider=IBMJCE" \
       com.sun.identity.cli.CommandManager "$@"

10. Check that the ssoadm command works properly:

    1. Create a text file, for example $HOME/.pwd.txt, containing the AM administrative user's password string in cleartext on a single line.

    2. Make the text file read-only:

       $ chmod 400 $HOME/.pwd.txt

    3. Run the ssoadm command to list the configured servers:

       $ cd /path/to/openam-tools/admin/openam/bin/
       $ ./ssoadm list-servers -u amadmin -f $HOME/.pwd.txt
       https://openam.example.com:8443/openam

11. If you have deployed AM in a site configuration, edit the ssoadm (ssoadm.bat on Windows) script to map the site URL to the AM server URL.

    To do this, set the com.iplanet.am.naming.map.site.to.server system property as a java command option in the script. The option takes the following form:

    -D"com.iplanet.am.naming.map.site.to.server=lb-url=openam-url[,
     other-lb-url=openam-url ...]"

    The property maps each lb-url key to an openam-url value, where lb-url is the URL to a site load balancer, and openam-url is the URL to the AM server against which you set up the ssoadm command.

    Important

    The ssoadm command is dependent on the AM server against which you set it up, so always map site load balancer URLs to that server's openam-url.

    For example, if your site is behind https://lb.example.com:443/openam, and the AM server against which you set up the ssoadm command is at https://openam.example.com:8443/openam, then add the following property to the java command (all on one line without spaces):

    -D"com.iplanet.am.naming.map.site.to.server=
     https://lb.example.com:443/openam=https://openam.example.com:8443/openam"

    Repeat this step for each AM server in your site configuration. You can install all your instances of ssoadm on the same host, but in each case the command should manage only one AM server.

1. Verify that the JAVA_HOME environment variable is properly set:

   $ echo $JAVA_HOME
   /path/to/jdk

2. Create a file system directory to unpack the tools:

   $ mkdir -p /path/to/openam-tools/config

3. Unpack the tools from where you unzipped AM:

   $ cd /path/to/openam-tools/config
   $ unzip ~/Downloads/openam/SSOConfiguratorTools-5.1.2.24.zip
   Archive:  ~/Downloads/openam/SSOConfiguratorTools-5.1.2.24.zip
      creating: legal-notices/
     inflating: legal-notices/LICENSE.DOM-software.html
     inflating: legal-notices/NOTICE.resolver.txt
     inflating: legal-notices/LICENSE.DOM-documentation.html
           ... (more output) ...
    extracting: lib/xml-apis-2.11.0.jar
    extracting: openam-configurator-tool-14.1.2.24.jar
    extracting: lib/servlet-api-2.5.jar

Perform the following steps:

1. Verify that the JAVA_HOME environment variable is properly set:

   $ echo $JAVA_HOME
   /path/to/jdk

2. The configurator tool relies on a property file to specify the configuration for the AM server. For property file options, see configurator.jar(1).

   Copy the sample configuration property file provided with AM, and then modify properties as needed:

   $ cd /path/to/openam-tools/config
   $ cp sampleconfiguration config.properties
   $ grep -v "^#" config.properties | grep -v "^$"
   SERVER_URL=http://openam.example.com:8080
   DEPLOYMENT_URI=/openam
   BASE_DIR=/home/openam/openam
   locale=en_US
   PLATFORM_LOCALE=en_US
   AM_ENC_KEY=
   ADMIN_PWD=password
   COOKIE_DOMAIN=openam.example.com
   ACCEPT_LICENSES=true
   DATA_STORE=embedded
   DIRECTORY_SSL=SIMPLE
   DIRECTORY_SERVER=openam.example.com
   DIRECTORY_PORT=50389
   DIRECTORY_ADMIN_PORT=4444
   DIRECTORY_JMX_PORT=1689
   ROOT_SUFFIX=dc=openam,dc=forgerock,dc=org
   DS_DIRMGRDN=cn=Directory Manager
   DS_DIRMGRPASSWD=password

   When setting options in the property file, note the following:

   • If you include the ACCEPT_LICENSES=true property, AM auto-accepts the software licensing agreement and suppresses display of the license acceptance screen during silent installation.

   • When installing AM to support HTTPS, make sure the SERVER_URL property specifies a URL with HTTPS, and set the DIRECTORY_SSL property to SIMPLE.

3. Run the AM configurator tool, openam-configurator-tool-14.1.2.24.jar:

   java -jar openam-configurator-tool-14.1.2.24.jar --file config.properties

   If required, you can specify additional run-time options on the command line:

   • With the --acceptLicense option, the installer auto-accepts the software licensing agreement and suppresses the display of the license acceptance screen, resulting in the same behavior as specifying ACCEPT_LICENSES=true in the configuration property file.

   • The -Djavax.net.ssl.trustStore=PATH_TO_JKS_TRUSTSTORE option is required when installing AM to support HTTPS. Specify the AM web container's trust store for PATH_TO_JKS_TRUSTSTORE.

   Output similar to the following appears:

   $ java -jar openam-configurator-tool-14.1.2.24.jar --file config.properties
   Checking license acceptance...License terms accepted.
   Checking configuration directory /home/openam/openam....Success.
   Installing OpenAM configuration store...Success RSA/ECB/OAEPWithSHA1AndMGF1...
   Extracting OpenDJ, please wait...Complete
   Running OpenDJ setupSetup command: --cli --adminConnectorPort 4444
    --baseDN dc=openam,dc=forgerock,dc=org --rootUserDN cn=Directory Manager
    --ldapPort 50389 --skipPortCheck --rootUserPassword xxxxxxx --jmxPort 1689
    --no-prompt --doNotStart --hostname openam.example.com ...
   ...Success
   Installing OpenAM configuration store in /home/openam/openam/... ...Success.
   Creating OpenAM suffixImport+task+ ... ...Success
   Tag swapping schema files....Success.
   Loading Schema opendj_config_schema.ldif...Success.
   
   ...
   
   ...Success.
   Reinitializing system properties....Done
   Registering service dashboardService.xml...Success.
   
   ...
   
   Configuring system....Done
   Configuring server instance....Done
   Creating demo user....Done
   Creating Web Service Security Agents....Done
   Setting up monitoring authentication file.
   Configuration complete!

Perform the following steps to configure an external CTS token store:

1. Open the AM console and navigate to Configure > Server Defaults, and then click CTS.

2. On the CTS Token Store tab, configure the parameters as follows:

   CTS Token Store Parameters

   Parameter	Value	Notes
   Store Mode	External Token Store
   Root Suffix	ou=famrecords,ou=openam-session,ou=tokens
   Max Connections	17	For production, this value needs to be tuned. Consider 2^n+1, where n=4, 5, 6, and so on. For example, try setting this to 17, 33, 65, and test performance under load.

   
   

3. On the External Store Configuration tab, configure the parameters as follows:

   External Store Configuration Parameters

   Parameter	Value	Notes
   SSL/TLS Enabled	True	When connecting to a DS server in production mode, enable secure connections. When you enable SSL/TLS, make sure the AM server can trust the DS server certificate and that the certificate matches the CTS store FQDN.
   Connection String(s)	opendj.example.com:1389
   Login ID	uid=openam_cts,ou=admins,ou=famrecords,ou=openam-session,ou=tokens
   Password	strngB!ndPw@rd!
   Heartbeat	10	For production, this value needs to be tuned.

   
   

4. Click Save Changes.

5. Restart AM or the web container where it runs for the changes to take effect.

1. Open the deployment descriptor file web.xml in a text editor. The location of the file depends on your web application container, for example in Tomcat it might be located at: /path/to/tomcat/webapps/openam/WEB-INF/web.xml.

2. In the deployment descriptor file, add the following filter and filter mapping, which applies Cache-Control: private to the correct endpoints:

   <filter>
       <filter-name>CachePrivate</filter-name>
       <filter-class>org.forgerock.openam.headers.SetHeadersFilter</filter-class>
       <init-param>
           <param-name>Cache-Control</param-name>
           <param-value>private</param-value>
       </init-param>
       <init-param>
           <param-name>excludes</param-name>
           <param-value>/serverinfo/*,/serverinfo/version,/serverinfo/cookieDomains</param-value>
       </init-param>
   </filter>
   <filter-mapping>
       <filter-name>CachePrivate</filter-name>
       <url-pattern>/json/*</url-pattern>
   </filter-mapping>

3. Restart your web container for the changes to take effect.

The container in which you install AM requires a certificate in order to set up secure connections. Perform the following steps to set up Apache Tomcat 8.0 (Tomcat) with an HTTPS connector, using the Java keytool command to create a self-signed key pair:

1. Stop Tomcat.

2. Create a certificate and store it in a new keystore:

   $ cd /path/to/tomcat/conf/
   $ keytool -genkey -alias openam.example.com -storetype JCEKS
   -keyalg RSA -keystore keystore.jceks
   Enter keystore password:
    What is your first and last name?
    [Unknown]:  openam.example.com
   What is the name of your organizational unit?
    [Unknown]:  Eng
   What is the name of your organization?
    [Unknown]:  ForgeRock.com
   What is the name of your City or Locality?
    [Unknown]:  Grenoble
   What is the name of your State or Province?
    [Unknown]:  Isere
   What is the two-letter country code for this unit?
    [Unknown]:  FR
   Is CN=openam.example.com, OU=Eng, O=ForgeRock.com, L=Grenoble, ST=Isere,
    C=FR correct?
    [no]:  yes
   Enter key password for <openam.example.com>
    (RETURN if same as keystore password):

3. Uncomment the SSL connector configuration in Tomcat's conf/server.xml, and specify your keystore file, type, and password:

   <!-- Define a SSL HTTP/1.1 Connector on port 8443
   This connector uses the JSSE configuration, when using APR, the
   connector should be using the OpenSSL style configuration
   described in the APR documentation -->
   <!--
   -->
   <Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"
    SSLEnabled="true" maxThreads="150" scheme="https" secure="true"
    keystoreFile="/path/to/tomcat/conf/keystore.jceks"
    keystorePass="changeit"
    keystoreType="JCEKS"
    clientAuth="false" sslProtocol="TLS" />

   You may need different settings depending on your configuration and version of Apache Tomcat. See the documentation for your version for more information.

4. Start Tomcat.

5. Verify that you can connect to Tomcat on port 8443 over HTTPS.

   Your browser does not trust the certificate, because the certificate is self-signed and not signed by any of the CAs stored in your browser.

   Unknown Certificate

   
   
   

   You recognize the subject and issuer of your certificate, and so can choose to trust the certificate, saving it into your browser's trust store.

6. Deploy and configure AM.

7. To share the self-signed certificate in your container with other applications or servers, see "To Share Self-Signed Certificates".

Some client applications let you trust certificates blindly. This can be helpful when working in your lab or test environment with self-signed certificates. For example, you might want to use HTTPS with the AM RESTful API without having the client recognize the self-signed server certificate:

$ curl \
--header "Accept-API-Version: resource=1.0" \
'https://openam.example.com:8443/openam/identity/authenticate?username=bjensen&password=hifalutin'
{
    curl: (60) Peer certificate cannot be authenticated with known CA certificates
}

More details here: http://curl.haxx.se/docs/sslcerts.html

curl performs SSL certificate verification by default, using a "bundle" of Certificate Authority (CA) public keys (CA certs). If the default bundle file isnt adequate, you can specify an alternate file using the --cacert option. If this HTTPS server uses a certificate signed by a CA represented in the bundle, the certificate verification probably failed due to a problem with the certificate (it might be expired, or the name might not match the domain name in the URL). If you'd like to turn off curl's verification of the certificate, use the -k (or --insecure) option.

$ curl \
--insecure \
'https://openam.example.com:8443/openam/identity/authenticate?username=bjensen&password=hifalutin'
{
    token.id=AQIC5wM2LY4SfczMax8jegpSiaigB96NOWylLilsd0PUMjY.*AAJTSQACMDE.*
}

When you use a self-signed certificate for your container, clients connecting must be able to trust the container certificate. Your browser makes this an easy, but manual process. For other client applications, you must import the certificate into the trust store used by the client. By default, Java applications can use the $JAVA_HOME/jre/lib/security/cacerts store. The default password is changeit.^[5] The steps that follow demonstrate how to import a self-signed certificate into the Java cacerts store:

1. Export the certificate from the keystore:

   $ cd /path/to/tomcat/conf/
   $ keytool \
   -exportcert \
   -alias openam.example.com \
   -file openam.crt \
   -storetype JCEKS
   -keystore keystore.jceks
   {
   Enter keystore password:
   Certificate stored in file <openam.crt>;
   }

2. Import the certificate into the trust store:

   $ keytool \
   -importcert \
   -alias openam.example.com \
   -file openam.crt
   -trustcacerts \
   -keystore $JAVA_HOME/jre/lib/security/cacerts
   {
   Enter keystore password:
   Owner: CN=openam.example.com, OU=Eng, O=ForgeRock.com, L=Grenoble, ST=Isere,
   C=FR
   Issuer: CN=openam.example.com, OU=Eng, O=ForgeRock.com, L=Grenoble, ST=Isere,
   C=FR
   Serial number: 4e789e40
   Valid from: Tue Sep 20 16:08:00 CEST 2011 until: Mon Dec 19 15:08:00 CET 2011
   Certificate fingerprints:
   MD5:  31:08:11:3B:15:75:87:C2:12:08:E9:66:00:81:61:8D
   SHA1: AA:90:2F:42:0A:F4:A9:A5:0C:90:A9:FC:69:FD:64:65:D9:78:BA:1D
   Signature algorithm name: SHA1withRSA
   Version: 3
   Trust this certificate? [no]:
   }
   yes
   Certificate was added to keystore

1. Configure the org.forgerock.json.jose.jwe.compression.max.decompressed.size.bytes Java system property on the container where AM runs.

   For example, edit the setenv.sh file of the Apache Tomcat instance, and set the property with the new size in bytes:

   JAVA_OPTS="$JAVA_OPTS -Dorg.forgerock.json.jose.jwe.compression.max.decompressed.size.bytes=40960"

2. Restart the container for the changes to make effect.

• Change the value of the org.forgerock.openam.request.max.bytes.entity.size advanced server property to the new size, in bytes.

  How Do I Configure Advanced Server Properties?

  • To configure advanced server properties for all the instances of the AM environment, in the AM Admin UI, go to Configure > Server Defaults > Advanced.

  • To configure advanced server properties for a particular instance, go to Deployment > Servers > Server Name > Advanced.

  If the property you want to add or edit is not already configured, add it with its value, then click on the plus () button.

  If the property you want to add or edit is already configured, click on the pencil () button to edit it. When you are finished, click on the tick () button.

  Save your changes.

  The property is hot-swappable. You do not need to restart AM for the changes to take effect.