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. 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 a change to the 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-5.5.2.war file. For example:

   $ cd /tmp
   $ mkdir /tmp/openam ; cd /tmp/openam
   $ jar xvf ~/Downloads/AM-5.5.2.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. Rebuild the openam.war file.

   $ jar cvf ../openam.war *

5. 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-5.5.2.war file. For example:

   $ cd /tmp
   $ mkdir /tmp/openam ; cd /tmp/openam
   $ jar xvf ~/Downloads/AM-5.5.2.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-5.5.2.war file:

   $ jar cvf ../Edited-AM-5.5.2.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-5.5.2.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-5.5.2.war file. For example:

   $ cd /tmp
   $ mkdir /tmp/openam ; cd /tmp/openam
   $ jar xvf ~/Downloads/AM-5.5.2.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-5.5.2.war file:

   $ jar cvf ../AM-5.5.2.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 of Java agents earlier than version 5, 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-5.5.2.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 Session State" 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" 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 set. See "To Update an UMA Resource Set" 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"

  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.

  Note

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

After you enable AES key wrap encryption, you will also need to update the ssoadm command for it 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=20000 -Dorg.forgerock.openam.encryption.key.size=256 -Dorg.forgerock.openam.encryption.key.digest=SHA512

The AM-5.5.2.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-5.5.2.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 http://openam.example.com:8080/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 Data Stores".

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

The following example procedure shows how to prepare a single DS server as an external configuration data store. The DS instance implements a single backend for the AM configuration data. The procedure assumes that you have also prepared an external identity repository and an external CTS store, separate from the configuration data store.

1. Prepare your DS installation, then download the DS software. See the DS documentation about Installing OpenDJ Servers.

   $ cd /path/to/opendj
   $ ./setup --cli

   Example options are as follows:

   Example DS Setup Parameters

   Parameter	Example Inputs
   Accept License	Yes
   Root User DN	cn=Directory Manager
   Root User DN Password	(arbitrary)
   Fully Qualified Domain Name	opendj.example.com
   LDAP Port	1389
   Administration Connector Port	4444
   Create Base DN	No. This will be created in a later step.
   Enable SSL	If you choose this option, make sure that AM can trust the DS certificate.
   Enable TLS	If you choose this option, make sure that AM can trust the DS certificate.
   Start Server After Config	Yes

   
   

2. Change to the directory containing DS's binaries.

   $ cd /path/to/opendj/bin

3. Create a directory server backend, and call it cfgStore.

   The dsconfig command used to create the backend depends on the version of DS.

   • Use the following command with OpenDJ 2.6:

     $ dsconfig create-backend \
      --backend-name cfgStore \
      --set base-dn:dc=example,dc=com \
      --set enabled:true \
      --type local-db \
      --port 4444 \
      --bindDN "cn=Directory Manager" \
      --bindPassword password \
      --no-prompt

   • Use the following command with OpenDJ 3.0 and later to create a backend:

     $ dsconfig create-backend \
      --backend-name cfgStore \
      --set base-dn:dc=example,dc=com \
      --set enabled:true \
      --type je \
      --port 4444 \
      --bindDN "cn=Directory Manager" \
      --bindPassword password \
      --no-prompt

4. Create an LDIF file to add the initial entries for the configuration store, and save the file as add-config-entries.ldif. The entries include the base DN suffix, an organizational unit entry, and the AM user entry needed to access the directory server.

   When AM connects as uid=openam,ou=admins,dc=example,dc=com to an external directory server to store its data, it requires read, write, persistent search, and server-side sorting access privileges. You add these privileges by setting access control instructions (ACIs) on the base distinguished name (DN) entry (dc=example,dc=com). If your AM user has a DN other than uid=openam,ou=admins,dc=example,dc=com, adjust the ACIs where appropriate.

   You must also give privileges to the AM user to modify the schema and write to subentries, such as the schema entry. To grant these privileges, you include the following attributes on the AM user entry: ds-privilege-name: subentry-write and ds-privilege-name: update-schema.

   dn: dc=example,dc=com
   objectclass: top
   objectclass: domain
   dc: example
   aci: (targetattr="*")(version 3.0;acl "Allow CRUDQ operations";
    allow (search, read, write, add, delete)
    (userdn = "ldap:///uid=openam,ou=admins,dc=example,dc=com");)
   aci: (targetcontrol="2.16.840.1.113730.3.4.3")(version 3.0;
    acl "Allow persistent search"; allow (search, read)
    (userdn = "ldap:///uid=openam,ou=admins,dc=example,dc=com");)
   aci: (targetcontrol="1.2.840.113556.1.4.473")(version 3.0;
    acl "Allow server-side sorting"; allow (read)
    (userdn = "ldap:///uid=openam,ou=admins,dc=example,dc=com");)
   
   dn: ou=admins,dc=example,dc=com
   objectclass: top
   objectclass: organizationalUnit
   ou: admins
   
   dn: uid=openam,ou=admins,dc=example,dc=com
   objectclass: top
   objectclass: person
   objectclass: organizationalPerson
   objectclass: inetOrgPerson
   cn: openam
   sn: openam
   uid: openam
   userPassword: secret12
   ds-privilege-name: subentry-write
   ds-privilege-name: update-schema

5. Add the initial entries LDIF file using the ldapmodify command. The following example assumes that you are using OpenDJ 4.0 and later:

   If you are having trouble with the preceding LDIF file, consider removing the line feeds for the ACI attributes and let it wrap to the next line. If you are still having trouble using the ldapmodify command, you can use the import-ldif command, although you may have to re-apply the targetcontrol ACI attribute.

   $ bin/ldapmodify \
    --port 1389 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    add-config-entries.ldif

6. Add the Global Access Control Instruction (ACI) to the access control handler. The Global ACI gives AM the privileges to modify the schema definitions for the custom configuration where the AM entry has DN uid=openam,ou=admins,dc=example,dc=com.

   Note

   These access rights are only required during configuration, and only if the directory administrator does not add the AM directory schema definitions manually.

   If you copy the text from the following example, make sure that the value of global-aci is all on a single line.

   $ bin/dsconfig set-access-control-handler-prop \
    --add global-aci:'(target = "ldap:///cn=schema")(targetattr = "attributeTypes ||
    objectClasses")(version 3.0; acl "Modify schema"; allow (write)
    (userdn = "ldap:///uid=openam,ou=admins,dc=example,dc=com");)'
    --port 4444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --no-prompt

7. (Optional) If the DS server was set up with the --productionMode option, grant the additional access that AM requires.

   When DS servers are set up with the --productionMode option, many settings are hardened for a more secure default installation. Compared to evaluation mode, production mode significantly restricts access for non-admin users. For details, see Directory Server Setup Parameters in the ForgeRock Directory Services Installation Guide.

   The following example grants the additional required ACIs:

   $ ./dsconfig \
    set-access-control-handler-prop \
    --port 4444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --add 'global-aci: (extop="1.3.6.1.4.1.26027.1.6.1 || 1.3.6.1.4.1.26027.1.6.3 || 1.3.6.1.4.1.4203.1.11.1 || 1.3.6.1.4.1.1466.20037 || 1.3.6.1.4.1.4203.1.11.3")(version 3.0; acl "AM extended operation access"; allow(read) userdn="ldap:///uid=openam,ou=admins,dc=example,dc=com";)' \
    --add 'global-aci: (targetcontrol="2.16.840.1.113730.3.4.2 || 2.16.840.1.113730.3.4.17 || 2.16.840.1.113730.3.4.19 || 1.3.6.1.4.1.4203.1.10.2 || 1.3.6.1.4.1.42.2.27.8.5.1 || 2.16.840.1.113730.3.4.16 || 1.2.840.113556.1.4.1413 || 1.3.6.1.4.1.36733.2.1.5.1 || 1.3.6.1.1.12 || 1.3.6.1.1.13.1 || 1.3.6.1.1.13.2 || 1.2.840.113556.1.4.319 || 1.2.826.0.1.3344810.2.3 || 2.16.840.1.113730.3.4.18 || 2.16.840.1.113730.3.4.9 || 1.2.840.113556.1.4.473 || 1.3.6.1.4.1.42.2.27.9.5.9")(version 3.0; acl "AM extended operation access"; allow(read) userdn="ldap:///uid=openam,ou=admins,dc=example,dc=com";)' \
    --add 'global-aci: (targetattr="createTimestamp||creatorsName||modifiersName||modifyTimestamp||entryDN||entryUUID||subschemaSubentry||etag||governingStructureRule||structuralObjectClass||hasSubordinates||numSubordinates||isMemberOf")(version 3.0; acl "AM Operational Attributes"; allow (read,search,compare) userdn="ldap:///uid=openam,ou=admins,dc=example,dc=com";)' \
    --add 'global-aci: (targetcontrol="1.3.6.1.1.12 || 1.3.6.1.1.13.1")(version 3.0; acl "Allow assertion control";allow (read) userdn = "ldap:///uid=openam,ou=admins,dc=example,dc=com";)' \
    --trustAll \
    --no-prompt

8. At this point, deploy the AM server if you have not done so already. For additional details on deploying AM, see "Deploying".

9. AM requires additional schema definitions for attributes used to search for user and configuration data:

   Configuration Data Store Attributes

   Attribute	Index Type	Description
   CTS attributes		Specifies the CTS attributes required for stateful session high availability and persistence. Located in the WEB-INF/template/ldif/sfha/cts-add-schema.ldif file.
   iplanet-am-user-federation-info-key	equality	Specifies a configuration setting to store an account's federation information key, which is used internally. Located in WEB-INF/template/ldif/opendj/opendj_user_schema.ldif file.
   sun-fm-saml2-nameid-infokey	equality	Specifies an information key common to an IdP and SP to link accounts. Located in WEB-INF/template/ldif/opendj/opendj_user_schema.ldif file.
   sunxmlkeyvalue	equality, substring	Stores configuration values that may be looked up through searches. Located in WEB-INF/template/ldif/opendj/opendj_config_schema.ldif.

   
   

   Add the required CTS schema definitions. You can find the CTS schema definitions at /path/to/tomcat/webapps/openam/WEB-INF/template/ldif/sfha/cts-add-schema.ldif.

   $ cp /path/to/tomcat/webapps/openam/WEB-INF/template/ldif/sfha/cts-add-schema.ldif /tmp

10. Add the schema file to the directory server.

    $ bin/ldapmodify \
     --port 1389 \
     --bindDN "cn=Directory Manager" \
     --bindPassword password \
     /tmp/cts-add-schema.ldif

11. Add the required user store schema definitions. You can find the schema definitions at /path/to/tomcat/webapps/openam/WEB-INF/template/ldif/opendj/opendj_user_schema.ldif.

    $ cp /path/to/tomcat/webapps/openam/WEB-INF/template/ldif/opendj/opendj_user_schema.ldif /tmp

12. Add the schema file to the directory server.

    $ bin/ldapmodify \
     --port 1389 \
     --bindDN "cn=Directory Manager" \
     --bindPassword password \
     /tmp/opendj_user_schema.ldif

13. Add the schema definitions to the configuration repository. You can find the schema definitions at /path/to/tomcat/webapps/openam/WEB-INF/template/ldif/opendj/opendj_config_schema.ldif.

    $ cp /path/to/tomcat/webapps/openam/WEB-INF/template/ldif/opendj/opendj_config_schema.ldif /tmp

14. Add the schema file to the directory server.

    $ bin/ldapmodify \
     --port 1389 \
     --bindDN "cn=Directory Manager" \
     --bindPassword password \
     /tmp/opendj_config_schema.ldif

15. AM uses the attributes in "Configuration Data Store Attributes" to search for configuration data. On the DS server, use the dsconfig command to add these indexes to your external configuration store. Repeat this step to index the iplanet-am-user-federation-info-key and sun-fm-saml2-nameid-infokey attributes if you are deploying federation.

    The dsconfig subcommand used to create the index depends on the version of DS.

    • Use the following commands with OpenDJ 2.6.x:

      $ dsconfig create-local-db-index \
       --port 4444 \
       --hostname opendj.example.com \
       --bindDN "cn=Directory Manager" \
       --bindPassword password \
       --backend-name cfgStore \
       --index-name sunxmlkeyvalue \
       --set index-type:equality \
       --set index-type:substring \
       --no-prompt
      
      $ dsconfig create-local-db-index \
       --port 4444 \
       --hostname opendj.example.com \
       --bindDN "cn=Directory Manager" \
       --bindPassword password \
       --backend-name cfgStore \
       --index-name iplanet-am-user-federation-info-key \
       --set index-type:equality \
       --no-prompt
      
      $ dsconfig create-local-db-index \
       --port 4444 \
       --hostname opendj.example.com \
       --bindDN "cn=Directory Manager" \
       --bindPassword password \
       --backend-name cfgStore \
       --index-name sun-fm-saml2-nameid-infokey \
       --set index-type:equality \
       --no-prompt

    • Use the following commands with OpenDJ 3 and later:

      $ dsconfig create-backend-index \
       --port 4444 \
       --hostname opendj.example.com \
       --bindDN "cn=Directory Manager" \
       --bindPassword password \
       --backend-name cfgStore \
       --index-name sunxmlkeyvalue \
       --set index-type:equality \
       --set index-type:substring \
       --no-prompt
      
      $ dsconfig create-backend-index \
       --port 4444 \
       --hostname opendj.example.com \
       --bindDN "cn=Directory Manager" \
       --bindPassword password \
       --backend-name cfgStore \
       --index-name iplanet-am-user-federation-info-key \
       --set index-type:equality \
       --no-prompt
      
      $ dsconfig create-backend-index \
       --port 4444 \
       --hostname opendj.example.com \
       --bindDN "cn=Directory Manager" \
       --bindPassword password \
       --backend-name cfgStore \
       --index-name sun-fm-saml2-nameid-infokey \
       --set index-type:equality \
       --no-prompt

16. Rebuild the indexes using the rebuild-index command. You can stop the server and run rebuild-index in offline mode by specifying the --offline option, or you can run rebuild-index online using a task as follows:

    $ bin/rebuild-index --port 4444 --hostname opendj.example.com \
     --bindDN "cn=Directory Manager" --bindPassword password \
     --baseDN dc=example,dc=com --rebuildAll \
     --start 0

17. Verify the indexes. Note that if you are running OpenDJ 3 and later, you need to stop the server before running this command.

    $ bin/verify-index --baseDN dc=example,dc=com

    You have successfully installed and prepared the directory server for an external configuration store. When installing the AM server, you need to specify the host name, port and root suffix of the external directory server on the Configuration Data Store Settings screen of the AM Configurator. See "To Custom Configure an Instance" for more information.

1. Set the heartbeat interval using the JVM startup property org.forgerock.openam.ldap.sm.heartbeat.interval in your container.

   For example, to set the heartbeat interval to 20 seconds, edit %CATALINA_HOME%/bin/setenv.sh (Unix) or %CATALINA_HOME%\bin\setenv.bat (Windows) on Tomcat by adding the following line:

   set CATALINA_OPTS=-Dorg.forgerock.openam.ldap.sm.heartbeat.interval=20
        

2. Make sure that the heartbeat requests have the permissions necessary for a firewall or load balancer.

• Disable the heartbeat interval by setting the JVM startup property org.forgerock.openam.ldap.sm.heartbeat.interval to 0.

  For example, edit %CATALINA_HOME%/bin/setenv.sh (Unix) or %CATALINA_HOME%\bin\setenv.bat (Windows) on Tomcat by adding the following line:

  set CATALINA_OPTS=-Dorg.forgerock.openam.ldap.sm.heartbeat.interval=0

1. To allow unauthenticated access to the DS root entry, set the global-aci using the dsconfig command:

   $ ./dsconfig set-access-control-handler-prop --add 'global-aci:(target="ldap:///")(targetscope="base")(targetattr="objectClass||namingContexts||supportedAuthPasswordSchemes||supportedControl||supportedExtension||supportedFeatures||supportedLDAPVersion||supportedSASLMechanisms||vendorName||vendorVersion")(version 3.0; acl "User-Visible Root DSE Operational Attributes"; allow (read,search,compare) userdn="ldap:///anyone";)' --hostname server.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password --trustAll --no-prompt

2. Remove the default access to anonymous users using the dsconfig command:

   • On DS 3.x or later:

     $ ./dsconfig set-access-control-handler-prop --remove 'global-aci:(targetattr!="userPassword||authPassword||debugsearchindex||changes||changeNumber||changeType||changeTime||targetDN||newRDN||newSuperior||deleteOldRDN")(version 3.0; acl "Anonymous read access"; allow (read,search,compare) userdn="ldap:///anyone";)' --hostname server.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password --trustAll --no-prompt

   • On OpenDJ 2.6.x:

     $ ./dsconfig set-access-control-handler-prop --remove 'global-aci:(targetattr!="userPassword||authPassword||changes||changeNumber||changeType||changeTime||targetDN||newRDN||newSuperior||deleteOldRDN")(version 3.0; acl "Anonymous read access"; allow (read,search,compare) userdn="ldap:///anyone";)' --hostname server.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password --trustAll --no-prompt

3. If you have other custom ACIs that affect anonymous users, review them and update as necessary. To generate a list of ACIs, run the following command:

   $ ./ldapsearch --hostname openam.example.com --port 1389 --bindDN "cn=Directory manager" \
    --bindPassword "password" --baseDN "cn=config" --searchScope sub "cn=Access Control Handler"

4. Repeat these steps for all appropriate DS instances.

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. If the site is already using keystore keys in the configuration, such as for signing stateless cookies, SAML v2.0 assertions, and others, copy the keystore from any of the servers of the site to the configuration directory of the new instance:

   1. Create the configuration directory of the new instance, for example, /path/to/openam/openam. This directory must be the same as the configuration directory used by other AM servers in the site.

   2. Log in to the AM console and navigate to Deployment > Servers > Server Name > Security > Key Store and find the following properties:

      • Keystore File

      • Keystore Password File

      • Private Key Password File

      These properties configure the name and path of the keystore files you need to copy to the new instance. By default, they are located in the /path/to/openam/openam directory.

   3. Copy the keystore files from one of the instances of the site to the /path/to/openam/openam directory created for the new instance.

2. Navigate to the deployment URL of the new instance. You should see the AM configurator page.

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

4. In the first screen, enter the same password entered for the AM Administrator, amadmin, when you configured the first server in the site.

5. Configure server settings as required.

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

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

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

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

9. When the configuration process finishes, click Proceed to Login, and then login as the AM administrator to access the AM console.

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 New 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. Navigate to Deployment > Servers > Server Name > General.

6. Set the Parent Site to the name of the site you just created, and then select Save 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.1.8.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
       http://openam.example.com:8080/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 http://openam.example.com:8080/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=http://openam.example.com:8080/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.1.8.zip
   Archive:  ~/Downloads/openam/SSOConfiguratorTools-5.1.1.8.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.1.8.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.1.8.jar:

   java -jar openam-configurator-tool-14.1.1.8.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.1.8.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!

1. Go to the ForgeRock BackStage website, and then download a supported version of DS server.

2. Unzip the DS distribution and run the setup command.

3. Install DS with the installation parameters required for your deployment. Note, however, that SSL may be required in production deployments. This example uses the following parameters:

   Accept license?: yes
   Initial Root User DN for the Directory Server: cn=Directory Manager
   Password for the Initial Root User: <password value>
   Fully Qualified Hostname: cts.example.com
   LDAP Listening Port: 1389
   Administration Connector Port: 4444
   Create Base DNs: yes
   Backend Type*: JE Backend ([1])
   Base DN for Directory Data: cn=cts,ou=famrecords,ou=openam-session,ou=tokens
   Option for Populating Database: Option 2 - Only create base entry
   Do You Want to Enable SSL: no (may be required for your deployment)
   Do You Want to Enable StartTLS: no (may be required for your deployment)
   Do You Want To Start The Server: yes
   What Would You Like To Do: 1 - Set up server with parameters above

   * The Backend Type choice is available for OpenDJ 3.0 directory server and later.

1. Copy the CTS schema and then add it the repository.

   $ TOMCAT_OPENAM_WEBAPP=/path/to/tomcat/webapps/openam
   $ T=/tmp/ldif
   $ rm -rf $T
   $ mkdir $T
   $ cp $TOMCAT_OPENAM_WEBAPP/WEB-INF/template/ldif/sfha/cts-add-schema.ldif $T/cts-add-schema.ldif
   

   If you are using OpenDJ 4.0 or later:

   $ ./ldapmodify \
   --port 1389 \
   --bindDN "cn=Directory Manager" \
   --bindPassword password \
   $T/cts-add-schema.ldif

   If DS runs in production mode, then you must use the --useStartTls option to authenticate as Directory Manager on the LDAP port. This applies to the example above, and to other examples in this chapter.

   If you are using OpenDJ 3.5 or earlier:

   $ ./ldapmodify \
   --port 1389 \
   --bindDN "cn=Directory Manager" \
   --bindPassword password \
   --filename $T/cts-add-schema.ldif

   The output should be:

   # Processing MODIFY request for cn=schema
   # MODIFY operation successful for DN cn=schema

2. Copy the multivalue file and then add it to the repository.

   $ cp $TOMCAT_OPENAM_WEBAPP/WEB-INF/template/ldif/sfha/cts-add-multivalue.ldif $T/cts-add-multivalue.ldif

   If you are using OpenDJ 4.0 or later:

   $ ./ldapmodify \
   --port 1389 \
   --bindDN "cn=Directory Manager" \
   --bindPassword password \
   $T/cts-add-multivalue.ldif

   If you are using OpenDJ 3.5 or earlier:

   $ ./ldapmodify \
   --port 1389 \
   --bindDN "cn=Directory Manager" \
   --bindPassword password \
   --filename $T/cts-add-multivalue.ldif

3. Copy the multivalue index file, and then replace the @DB_NAME@ variable with your repository in the file. Then, add the file to the repository.

   $ cat $TOMCAT_OPENAM_WEBAPP/WEB-INF/template/ldif/sfha/cts-add-multivalue-indices.ldif \
    | sed -e 's/@DB_NAME@/userRoot/' > $T/cts-add-multivalue-indices.ldif
   

   If you are using OpenDJ 4.0 or later:

   $ ./ldapmodify \
   --port 1389 \
   --bindDN "cn=Directory Manager" \
   --bindPassword password \
   $T/cts-add-multivalue-indices.ldif

   If you are using OpenDJ 3.5 or earlier:

   $ ./ldapmodify \
   --port 1389 \
   --bindDN "cn=Directory Manager" \
   --bindPassword password \
   --filename $T/cts-add-multivalue-indices.ldif

4. Copy the CTS index file, and then replace the @DB_NAME@ variable with your repository in the file. Then, add the file to the repository.

   $ cat $TOMCAT_OPENAM_WEBAPP/WEB-INF/template/ldif/sfha/cts-indices.ldif \
   | sed -e 's/@DB_NAME@/userRoot/' > $T/cts-indices.ldif

   If you are using OpenDJ 4.0 or later:

   $ ./ldapmodify \
   --port 1389 \
   --bindDN "cn=Directory Manager" \
   --bindPassword password \
   $T/cts-indices.ldif

   If you are using OpenDJ 3.5 or earlier:

   $ ./ldapmodify \
   --port 1389 \
   --bindDN "cn=Directory Manager" \
   --bindPassword password \
   --filename $T/cts-indices.ldif

5. Copy the container file, and then replace the @SM_CONFIG_ROOT_SUFFIX@ variable with the base DN defined during the external DS installation procedure, for example, cn=cts,ou=famrecords,ou=openam-session,ou=tokens. Then, add the file to the repository.

   $ ROOT_SUFFIX="cn=cts,ou=famrecords,ou=openam-session,ou=tokens"
   $ cat $TOMCAT_OPENAM_WEBAPP/WEB-INF/template/ldif/sfha/cts-container.ldif | sed -e 's/@SM_CONFIG_ROOT_SUFFIX@/$ROOT_SUFFIX/' > $T/cts-container.ldif

   If you are using OpenDJ 4.0 or later:

   $ ./ldapmodify \
   --port 1389 \
   --bindDN "cn=Directory Manager" \
   --bindPassword password \
   $T/cts-container.ldif

   If you are using OpenDJ 3.5 or earlier:

   $ ./ldapmodify \
   --port 1389 \
   --bindDN "cn=Directory Manager" \
   --bindPassword password \
   --filename $T/cts-container.ldif

   The output should be:

   Processing ADD request for ou=tokens,cn=cts,ou=famrecords,ou=openam-session,ou=tokens
   ADD operation successful for DN ou=tokens,cn=cts,ou=famrecords,ou=openam-session,ou=tokens
   Processing ADD request for ou=openam-session,ou=tokens,cn=cts,ou=famrecords,ou=openam-session,ou=tokens
   ADD operation successful for DN ou=openam-session,ou=tokens,cn=cts,ou=famrecords,ou=openam-session,ou=tokens
   Processing ADD request for ou=famrecords,ou=openam-session,ou=tokens,cn=cts,ou=famrecords,ou=openam-session,ou=tokens
   ADD operation successful for DN ou=famrecords,ou=openam-session,ou=tokens,cn=cts,ou=famrecords,ou=openam-session,ou=tokens

6. If AM is binding to CTS as the Directory Manager user, you can jump to section "CTS Index Import and Build".

   To create a non-admin user, follow the instructions in the next section.

1. Create an LDIF file called cts_user.ldif that defines the CTS non-admin user. The following sample LDIF creates a user called openam_cts and assigns the update-schema, subentry-write, and password-reset privileges.

   The LDIF file also overrides the default lookthrough limit of 5000 for this non-admin user to unlimited (0) and sets the maximum number of entries returned for a search to 5000 (default, 1000). The ds-rlim-size-limit: 5000 is arbitrary and can be any value larger than the default maximum number of entries returned for a search, for example, value >= 1001. Setting the max number of entries for a search to 5000 ensures that the CTS reaper can properly delete returned tokens when large bursts of CTS tokens (> 5000 per interval between CTS reaping) are returned. For more information on DS resource limits, see Setting Resource Limits in the ForgeRock Directory Services Administration Guide.

   If there are more than 100K of expired tokens in the CTS, the search from the CTS reaper will be treated as non-indexed and will fail if the non-admin user does not have the unindexed-search privilege. Therefore, you should add the unindexed-search privilege to the user's entry.

   Finally, make sure that you replace the userPassword value, shown as password in the LDIF, with your actual password:

   dn: ou=admins,cn=cts,ou=famrecords,ou=openam-session,ou=tokens
   objectClass: top
   objectClass: organizationalunit
   ou: OpenAM Administrator
   
   dn: uid=openam_cts,ou=admins,cn=cts,ou=famrecords,ou=openam-session,ou=tokens
   objectClass: top
   objectClass: person
   objectClass: organizationalPerson
   objectClass: inetOrgPerson
   cn: OpenAM Non-Admin-User
   sn: OpenAM
   userPassword: password
   ds-privilege-name: update-schema
   ds-privilege-name: subentry-write
   ds-privilege-name: password-reset
   ds-privilege-name: unindexed-search
   ds-rlim-lookthrough-limit: 0
   ds-rlim-size-limit: 5000

2. Add the new user to the CTS repository. The following example assumes that you are using OpenDJ 4.0 and later:

   $ ./ldapmodify \
    --port 1389 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    cts_user.ldif

   If you are using OpenDJ 3.5 or earlier:

   $ ./ldapmodify \
    --defaultAdd
    --port 1389 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --filename cts_user.ldif

   The output should be:

   Processing ADD request for ou=admins,cn=cts,ou=famrecords,ou=openam-session,ou=tokens
   ADD operation successful for DN ou=admins,cn=cts,ou=famrecords,ou=openam-session,ou=tokens
   Processing ADD request for uid=openam_cts,ou=admins,cn=cts,ou=famrecords,ou=openam-session,ou=tokens
   ADD operation successful for DN uid=openam_cts,ou=admins,cn=cts,ou=famrecords,ou=openam-session,ou=tokens

3. Add a global ACI to allow the openam_cts user to modify schema:

   $ ./dsconfig \
    set-access-control-handler-prop \
    --no-prompt \
    --hostname cts.example.com \
    --port 4444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --add 'global-aci:(target = "ldap:///cn=schema")(targetattr = "attributeTypes ||
     objectClasses")(version 3.0; acl "Modify schema"; allow (write)
     userdn = "ldap:///uid=openam_cts,ou=admins,cn=cts,ou=famrecords,ou=openam-session,ou=tokens";)'

4. Use dsconfig to check that the global ACI has been applied:

   $ ./dsconfig \
    get-access-control-handler-prop \
    --hostname cts.example.com \
    --port 4444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --no-prompt \
    --property global-aci

   Verify that the following entry is present:

   "(target = "ldap:///cn=schema")(targetattr = "attributeTypes || objectClasses")
    (version 3.0; acl "Modify schema"; allow (write) userdn =
   "ldap:///uid=openam_cts,ou=admins,cn=cts,ou=famrecords,ou=openam-session,ou=tokens";)",

5. Create an LDIF file called cts_acis.ldif to add the ACIs to allow the CTS user to create, search, modify, delete, and allow persistent search to the CTS repository:

   dn: cn=cts,ou=famrecords,ou=openam-session,ou=tokens
   changetype: modify
   add: aci
   aci: (targetattr="*")(version 3.0;acl "Allow entry search";
    allow (search, read) userdn = "ldap:///uid=openam_cts,ou=admins,cn=cts,ou=famrecords,ou=openam-session,ou=tokens";)
   aci: (targetattr="*")(version 3.0;acl "Modify entries"; allow (write)
    userdn = "ldap:///uid=openam_cts,ou=admins,cn=cts,ou=famrecords,ou=openam-session,ou=tokens";)
   aci: (targetcontrol="2.16.840.1.113730.3.4.3")(version 3.0;
    acl "Allow persistentsearch";allow (search, read)
    userdn = "ldap:///uid=openam_cts,ou=admins,cn=cts,ou=famrecords,ou=openam-session,ou=tokens";)
   aci: (version 3.0;acl "Add config entry"; allow (add) userdn =
    "ldap:///uid=openam_cts,ou=admins,cn=cts,ou=famrecords,ou=openam-session,ou=tokens";)
   aci: (version 3.0;acl "Delete entries"; allow (delete) userdn =
    "ldap:///uid=openam_cts,ou=admins,cn=cts,ou=famrecords,ou=openam-session,ou=tokens";)

6. Import the ACIs into the CTS repository:

   $ ./ldapmodify \
    --hostname cts.example.com \
    --port 1389 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    cts_acis.ldif

   If you are using OpenDJ 3.5 or earlier:

   $ ./ldapmodify \
    --hostname cts.example.com \
    --port 1389 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --filename cts_acis.ldif

   The output should be:

   # Processing MODIFY request for cn=cts,ou=famrecords,ou=openam-session,ou=tokens
   # MODIFY operation successful for DN cn=cts,ou=famrecords,ou=openam-session,ou=tokens

7. If the DS server was set up with the --productionMode option, grant the additional access that AM requires.

   When DS servers are set up with the --productionMode option, many settings are hardened for a more secure default installation. Compared to evaluation mode, production mode significantly restricts access for non-admin users. For details, see Directory Server Setup Parameters in the ForgeRock Directory Services Installation Guide.

   The following example grants the same permissions as evaluation mode to the AM non-admin user that you created:

   $ ./dsconfig \
    set-access-control-handler-prop \
    --hostname cts.example.com \
    --port 4444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --add 'global-aci: (extop="1.3.6.1.4.1.26027.1.6.1 || 1.3.6.1.4.1.26027.1.6.3 || 1.3.6.1.4.1.4203.1.11.1 || 1.3.6.1.4.1.1466.20037 || 1.3.6.1.4.1.4203.1.11.3")(version 3.0; acl "AM extended operation access"; allow(read) userdn="ldap:///uid=openam_cts,ou=admins,cn=cts,ou=famrecords,ou=openam-session,ou=tokens";)' \
    --add 'global-aci: (targetcontrol="2.16.840.1.113730.3.4.2 || 2.16.840.1.113730.3.4.17 || 2.16.840.1.113730.3.4.19 || 1.3.6.1.4.1.4203.1.10.2 || 1.3.6.1.4.1.42.2.27.8.5.1 || 2.16.840.1.113730.3.4.16 || 1.2.840.113556.1.4.1413 || 1.3.6.1.4.1.36733.2.1.5.1 || 1.3.6.1.1.12 || 1.3.6.1.1.13.1 || 1.3.6.1.1.13.2 || 1.2.840.113556.1.4.319 || 1.2.826.0.1.3344810.2.3 || 2.16.840.1.113730.3.4.18 || 2.16.840.1.113730.3.4.9 || 1.2.840.113556.1.4.473 || 1.3.6.1.4.1.42.2.27.9.5.9")(version 3.0; acl "AM extended operation access"; allow(read) userdn="ldap:///uid=openam_cts,ou=admins,cn=cts,ou=famrecords,ou=openam-session,ou=tokens";)' \
    --add 'global-aci: (targetattr="createTimestamp||creatorsName||modifiersName||modifyTimestamp||entryDN||entryUUID||subschemaSubentry||etag||governingStructureRule||structuralObjectClass||hasSubordinates||numSubordinates||isMemberOf")(version 3.0; acl "AM Operational Attributes"; allow (read,search,compare) userdn="ldap:///uid=openam_cts,ou=admins,cn=cts,ou=famrecords,ou=openam-session,ou=tokens";)' \
    --add 'global-aci: (targetcontrol="1.3.6.1.1.12 || 1.3.6.1.1.13.1")(version 3.0; acl "Allow assertion control";allow (read) userdn = "ldap:///uid=openam_cts,ou=admins,cn=cts,ou=famrecords,ou=openam-session,ou=tokens";)' \
    --trustAll \
    --no-prompt

1. (Optional) If you have not yet imported CTS index files as described in "To Import the CTS Configuration", open the /tomcat/webapps/openam/WEB-INF/template/ldif/sfha/cts-indices.ldif file. Apply each index to the CTS repository using the dsconfig command. Note that these indexes may require further tuning depending on environmental load testing.

   For example, you can apply the first index coreTokenExpirationDate as shown below. Then, apply the other indexes individually in the same manner:

   $ ./dsconfig  \
    --port 4444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --backend-name userRoot \
    --index-name coreTokenExpirationDate \
    --set index-type:ordering \
    --trustAll \
    --no-prompt

   Or, you can obtain a copy of a dsconfig batch file, which adds all of your indexes to the CTS repository at one time. Copy the cts-add-indexes.txt in "Supported Scripts", save it locally, then run dsconfig in batch mode:

   $ ./dsconfig  \
    --port 4444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --batchFilePath cts-add-indexes.txt \
    --trustAll \
    --no-prompt

2. Stop the DS instance.

   $ ./stop-ds

3. Rebuild all indexes and then verify them:

   $ ./rebuild-index --baseDN "cn=cts,ou=famrecords,ou=openam-session,ou=tokens" \
    --rebuildAll --offline
   $ ./verify-index --baseDN "cn=cts,ou=famrecords,ou=openam-session, ou=tokens"
   . . . msg=Checked 6 entries and found 0 error(s) in 0 seconds . . .

4. Restart the DS instance.

   $ ./start-ds

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	cn=cts,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	False	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)	cts.example.com:1389
   Login ID	uid=openam_cts,ou=admins,cn=cts,ou=famrecords,ou=openam-session,ou=tokens
   Password	password
   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. In Chrome, log in to the second AM instance with the amadmin user, select the realm, and then click on sessions.

2. In Firefox, log in to the first AM instance with a test user.

3. In Chrome, verify that the test user exists in the first AM instance's session list and not in the second instance.

4. Shut down the first AM instance.

5. In Firefox, rewrite the URL to point to the second AM instance. If successful, the browser should not prompt for login.

6. Confirm the session is still available. In Chrome, list the sessions on the second instance, the test user's session should be present.

7. Restart the first AM instance to complete the testing.

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 \
"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