1. Stop JBoss or WildFly.

2. The default JVM settings do not allocate sufficient memory to OpenAM. 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 OpenDJ, the minimum heap size may be higher. For details on the JVM options to use, see "Preparing a Java Environment".

      When using JDK 7, change the permanent generation size to -XX:MaxPermSize=256m if the default size does not exceed this amount.

      When using JDK 8, 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 OpenAM to run with JBoss or WildFly, you should make a change to the OpenAM war file. JBoss and WildFly deploy applications from different temporary directories every time you restart the container, which would require reconfiguring OpenAM. To avoid problems, change the OpenAM war file as follows:

1. If you have not already done so, create a temporary directory and expand the OpenAM-14.0.0.war file (OpenAM-14.0.0.war if you obtained the file by unpacking OpenAM-14.0.0.zip).

   $ cd /tmp
   $ mkdir /tmp/openam ; cd /tmp/openam
   $ jar xvf ~/Downloads/OpenAM-14.0.0.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 OpenAM 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 OpenAM 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 OpenAM server. See "Handling Multiple Cookie Domains When Using Wildfly" for more information.

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

Change the OpenAM war file as follows:

1. Create a temporary directory and expand the OpenAM-14.0.0.war file (OpenAM-14.0.0.war if you obtained the file by unpacking OpenAM-14.0.0.zip):

   $ cd /tmp
   $ mkdir /tmp/openam ; cd /tmp/openam
   $ jar xvf ~/Downloads/OpenAM-14.0.0.war

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

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

4. Rebuild the openam.war file:

   $ jar cvf ../openam.war *

1. If you have not yet deployed OpenAM:

   1. Unpack the OpenAM .war file, OpenAM-14.0.0.war (OpenAM-14.0.0.war if you obtained the file by unpacking OpenAM-14.0.0.zip).

      $ mkdir /tmp/openam
      $ cd /tmp/openam/
      $ jar -xf ~/Downloads/openam/OpenAM-14.0.0.war

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

2. If you have already deployed OpenAM:

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

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

   origins (required)

   A comma-separated list of the origins allowed when making CORS requests to OpenAM. 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 OpenAM.

   Example: iPlanetDirectoryPro,Accept-API-Version

   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.

   Common headers used when accessing an OpenAM server includes the following:

   Common Headers Used

   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 OpenAM endpoint version. See "REST API Versioning" in the Authentication and Single Sign-On Guide.
   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) Guide .

   
   

   Caution

   Do not add Content-Type to the list of allowed headers in the CORS filter. Doing so can expose OpenAM to cross-site request forgery (CSRF) attacks.

   expectedHostname (optional)

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

   If not specified, any host value is accepted.

   If the OpenAM 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 the OpenAM 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 OpenAM:

   1. Pack up the OpenAM .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 OpenAM:

   1. Restart OpenAM 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 OpenAM-14.0.0.war file (OpenAM-14.0.0.war if you obtained the file by unpacking OpenAM-14.0.0.zip) contains OpenAM 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 OpenAM-14.0.0.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 OpenAM 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 OpenAM, OpenAM requires a deployment URI with a non-empty string after /. Do not deploy OpenAM 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 OpenAM to be deployed in your container.

2. Navigate to the initial configuration screen, for example http://openam.example.com:8080/openam.

   

   OpenAM 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 OpenAM. See "Installing a Single Server".

The following example procedure shows how to prepare a single OpenDJ directory server instance as an external configuration data store. The OpenDJ instance implements a single backend for the OpenAM 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 OpenDJ installation, then download the OpenDJ software. See the OpenDJ documentation about Installing OpenDJ Servers.

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

   Example options are as follows:

   Example OpenDJ 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 OpenAM can trust the OpenDJ certificate.
   Enable TLS	If you choose this option, make sure that OpenAM can trust the OpenDJ certificate.
   Start Server After Config	Yes

   
   

2. Change to the OpenDJ directory.

   $ cd /path/to/opendj

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

   The dsconfig command used to create the backend depends on the version of OpenDJ directory server.

   • 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 OpenAM user entry needed to access the directory server.

   When OpenAM 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 OpenAM 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 OpenAM 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 OpenAM 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 OpenAM the privileges to modify the schema definitions for the custom configuration where the OpenAM 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 OpenAM 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. At this point, deploy the OpenAM server if you have not done so already. For additional details on deploying OpenAM, see "Deploying".

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

9. Add the schema file to the directory server.

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

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

11. Add the schema file to the directory server.

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

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

13. Add the schema file to the directory server.

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

14. OpenAM uses the attributes in "Configuration Data Store Attributes" to search for configuration data. On the OpenDJ directory 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 OpenDJ directory server.

    • 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

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

16. Verify the indexes. Note that if you are running OpenDJ 3 and later, you need to stop OpenDJ 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 OpenAM 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 OpenAM 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 OpenAM, you configure an OpenAM 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 OpenAM 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 OpenAM server in the site.

   The directory used to store configuration data should use the same directory service used for this purpose by other OpenAM servers in the site. If you use the embedded OpenDJ directory 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 OpenAM administrator to access the AM console.

The following steps show how to set up the site for the first OpenAM 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 OpenAM servers in the site. For example, if your load balancer listens for HTTPS on host lb.example.com and port 443 with OpenAM under /openam, then your site URL is https://lb.example.com/openam.

   Client applications and policy 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 OpenAM site, add them to the site at configuration time as described in "To Add a Server to a Site".

1. Verify that OpenAM 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-14.0.0.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 OpenAM 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 OpenAM:

   $ ls openam/bin/
   ampassword  amverifyarchive  ssoadm

   On Windows, these files are .bat scripts.

8. (Optional) If you connect to OpenAM over HTTPS, and 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 be able to trust the certificate.

   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 OpenAM 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 OpenAM in a site configuration, edit the ssoadm (ssoadm.bat on Windows) script to map the site URL to the OpenAM 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 OpenAM server against which you set up the ssoadm command.

    Important

    The ssoadm command is dependent on the OpenAM 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 OpenAM 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 OpenAM 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 OpenAM 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 OpenAM:

   $ cd /path/to/openam-tools/config
   $ unzip ~/Downloads/openam/SSOConfiguratorTools-14.0.0.zip
   Archive:  ~/Downloads/openam/SSOConfiguratorTools-14.0.0.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.0.0.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 OpenAM server. For property file options, see configurator.jar(1).

   Copy the sample configuration property file provided with OpenAM, 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
   AMLDAPUSERPASSWD=secret12
   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, OpenAM auto-accepts the software licensing agreement and suppresses display of the license acceptance screen during silent installation.

   • When installing OpenAM 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 OpenAM configurator tool, openam-configurator-tool-14.0.0.jar:

   java -jar openam-configurator-tool-14.0.0.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 OpenAM to support HTTPS. Specify the OpenAM web container's trust store for PATH_TO_JKS_TRUSTSTORE.

   Output similar to the following appears:

   $ java -jar openam-configurator-tool-14.0.0.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 OpenDJ directory server.

2. Unzip the OpenDJ distribution and run setup, which launches a GUI application called the QuickSetup Wizard. If you want to run setup interactively from the command line, use setup --cli.

3. Install OpenDJ with the installation parameters necessary 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: dc=cts,dc=example,dc=com
   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 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 OpenDJ installation procedure, for example, dc=example,dc=com. Then, add the file to the repository.

   
   $ ROOT_SUFFIX="dc=example,dc=com"
   $ 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,dc=cts,dc=example,dc=com
   ADD operation successful for DN ou=tokens,dc=cts,dc=example,dc=com
   Processing ADD request for ou=openam-session,ou=tokens,dc=cts,dc=example,dc=com
   ADD operation successful for DN ou=openam-session,ou=tokens,dc=cts,dc=example,dc=com
   Processing ADD request for ou=famrecords,ou=openam-session,ou=tokens,dc=cts,dc=example,dc=com
   ADD operation successful for DN ou=famrecords,ou=openam-session,ou=tokens,dc=cts,dc=example,dc=com

6. If OpenAM 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 OpenDJ resource limits, see Setting Resource Limits on the OpenDJ 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 <password> tag with your actual password:

   dn: ou=admins,dc=cts,dc=example,dc=com
   objectClass: top
   objectClass: organizationalunit
   ou: OpenAM Administrator
   
   dn: uid=openam_cts,ou=admins,dc=cts,dc=example,dc=com
   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,dc=cts,dc=example,dc=com
   ADD operation successful for DN ou=admins,dc=cts,dc=example,dc=com
   Processing ADD request for uid=openam_cts,ou=admins,dc=cts,dc=example,dc=com
   ADD operation successful for DN uid=openam_cts,ou=admins,dc=cts,dc=example,dc=com

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,dc=cts,dc=example,dc=com";)'

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,dc=cts,dc=example,dc=com";)",

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: dc=cts,dc=example,dc=com
   changetype: modify
   add: aci
   aci: (targetattr="*")(version 3.0;acl "Allow entry search";
    allow (search, read)(userdn = "ldap:///uid=openam_cts,ou=admins,dc=cts,dc=example,dc=com");)
   aci: (targetattr="*")(version 3.0;acl "Modify entries"; allow (write)
    (userdn = "ldap:///uid=openam_cts,ou=admins,dc=cts,dc=example,dc=com");)
   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,dc=cts,dc=example,dc=com");)
   aci: (version 3.0;acl "Add config entry"; allow (add)(userdn =
    "ldap:///uid=openam_cts,ou=admins,dc=cts,dc=example,dc=com");)
   aci: (version 3.0;acl "Delete entries"; allow (delete)(userdn =
    "ldap:///uid=openam_cts,ou=admins,dc=cts,dc=example,dc=com");)

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 dc=cts,dc=example,dc=com
   MODIFY operation successful for DN dc=cts,dc=example,dc=com

1. 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. Rebuild all indexes and then verify them:

   ./rebuild-index \
    --port 4444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --baseDN "dc=cts,dc=example,dc=com" \
    --rebuildAll \
    --offline \
    --start 0
   
   ./verify-index --baseDN "dc=cts,dc=example,dc=com"

3. Restart the OpenDJ instance.

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	dc=cts,dc=example,d=com
   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
   Connection String(s)	cts.example.com:1389
   Login ID	uid=openam_cts,ou=admins,dc=cts,dc=example,dc=com
   Password	password
   Heartbeat	10	For production, this value needs to be tuned.

   
   

4. Click Save Changes.

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

1. In Chrome, log in to the second OpenAM instance with the amadmin user, select the realm, and then click on sessions.

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

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

4. Shut down the first OpenAM instance.

5. In Firefox, rewrite the URL to point to the second OpenAM 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 OpenAM instance to complete the testing.

The container in which you install OpenAM 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 OpenAM.

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 OpenAM 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.^[6] 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