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 From the Command Line.

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

   $ bin/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 pwd \
     --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 service.

   When OpenAM connects as uid=openam,ou=admins,dc=example,dc=com to an external directory server to store its data, it requires both read and write access privileges. You add these privileges by means of access control instructions (ACIs) to the base distinguished name (DN) entry (dc=example,dc=com). If your OpenAM user has a different 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.

   Note that if you are having trouble with this 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, you can use the import-ldif command although you may have to re-apply the targetcontrol ACI attribute.

   dn: dc=example,dc=com
   objectclass: top
   objectclass: domain
   dc: example
   aci: (targetattr="*")(version 3.0;acl "Allow entry search"; allow (
    search, read)(userdn = "ldap:///uid=openam,ou=admins,dc=example,dc=com");)
   aci: (targetattr="*")(version 3.0;acl "Modify config entry"; allow (write)(
    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: (version 3.0;acl "Add config entry"; allow (add)(userdn = "ldap:///
    uid=openam,ou=admins,dc=example,dc=com");)
   aci: (version 3.0;acl "Delete config entry"; allow (delete)(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.

   $ bin/ldapmodify \
     --port 4444 \
     --bindDN "cn=Directory Manager" \
     --bindPassword pwd \
     --defaultAdd \
     --useSSL \
     --trustAll \
     --filename 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 are having difficulty successfully adding the global-aci attribute, try doing so without any line breaks.

   $ 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 pwd \
       --trustAll \
       --no-prompt
        

7. At this point, install the OpenAM server if you haven't done so already. For details, see Installing OpenAM Core Services.

8. OpenAM requires specific directory schema definitions for the object classes and attribute types that describe its data. For the configuration store, the directory administrator should let OpenAM update the directory schema at configuration time.

   Copy the schema files, located at /path/to/tomcat/webapps/openam/WEB-INF/template/ldif/sfha to a local file, cts-add-schema.ldif.

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

9. Add the schema to the directory server.

   $ bin/ldapmodify \
     --port 4444 \
     --bindDN "cn=Directory Manager" \
     --bindPassword pwd \
     --useSSL \
     --trustAll \
     --fileName cts-add-schema.ldif
        

10. OpenAM uses certain attributes to search for configuration data. You must set some indexes on these attributes for the configuration store.

    Configuration Data Store Indexes

    Attribute	Indexes Required
    iplanet-am-user-federation-info-key	equality
    sun-fm-saml2-nameid-infokey	equality
    sunxmlkeyvalue	equality, substring

    
    

    On the OpenDJ directory server, use dsconfig to add these indexes to your external configuration store. Repeat for each attribute in "Configuration Data Store Indexes".

    $ bin/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 \
       --trustAll \
       --no-prompt
         

11. Rebuild the indexes using the rebuild-index command. You can stop the server and run rebuild-index in offline mode, 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
         

12. Verify the indexes.

    $ 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 Configure OpenAM for more information.

For JBoss AS 7.1.0 / 7.1.1, you need to make changes to the module.xml file in the /path/to/jboss/modules/sun/jdk/main directory, as well as changes to a configuration file associated with JBoss standalone or domain modes.

1. Stop JBoss

2. Update the module.xml file associated with the container. You can find this file a directory such as /path/to/jboss/modules/sun/jdk/main.

3. In the same module.xml file, add the Sun x509 security module path (sun/security/x509).

   The following example shows an excerpt of the revised file for JBoss AS 7.1.0.

   <path name="com/sun/security/auth"/>
   <path name="com/sun/security/auth/login"/>
   <path name="com/sun/security/auth/module"/>
   <path name ="sun/security/x509"/> <!-- path added here -->
   <path name="sun/misc"/>

4. When using ssoadm or the distributed authentication service (DAS), also add the following path to the aforementioned module.xml file.

   <path name="com/sun/org/apache/xerces/internal/dom" />

5. Disable modules that conflict with OpenAM REST libraries. All jaxrs references need to be removed from the configuration. The file that you modify depends on whether you are running JBoss in standalone or domain mode.

   • The following example is based on JBoss 7.1.0 standalone mode. Remember to remove all subsystems and extension tags associated with urn:jboss:domain:jaxrs:1.0.

     $ vi /path/to/jboss/standalone/configuration/standalone.xml
     <extension module="org.jboss.as.ejb3"/>
     -  <extension module="org.jboss.as.jaxrs"/>
     ....
     -  <subsystem xmlns="urn:jboss:domain:jaxrs:1.0"/>
     <subsystem xmlns="urn:jboss:domain:jca:1.1">
                             

   • The following example is based on JBoss 7.1.0 for a managed domain.

     $ vi /path/to/jboss7/domain/configuration/domain.xml
     <extension module="org.jboss.as.ejb3"/>
     -  <extension module="org.jboss.as.jaxrs"/>
     ....
     -  <subsystem xmlns="urn:jboss:domain:jaxrs:1.0"/>
     <subsystem xmlns="urn:jboss:domain:jca:1.1">
                             

6. In either the standalone.xml or domain.xml files, you will also need to delete org.jboss.as.webservices references. Depending on the file, this includes one or more groups of subsystem lines such as:

   <subsystem xmlns="urn:jboss:domain:webservices:1.1"/>
   ....
   </subsystem>
                   

7. You are now ready to prepare OpenAM as described in "To Prepare OpenAM for JBoss".

JBoss EAP 6.0.0 and 6.0.1 are built from JBoss AS 7.1.2 and 7.1.3, respectively. The same techniques described in the "To Prepare JBoss AS 7.1.0 / 7.1.1" section work here as well. One alternative method is available, as described in this section.

1. Stop JBoss.

2. Update the openam.war before deploying OpenAM.

   1. Create a temporary directory and expand the openam.war.

      $ mkdir /tmp/openam ; cd /tmp/openam
      $ jar xvf /path/to/OpenAM-12.0.0.war
                              

   2. Create a new jboss-deployment-structure.xml file in the WEB-INF subdirectory so that it appears as follows, and save the change.

      <?xml version="1.0" encoding="UTF-8"?>
       <jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.2">
        <deployment>
         <exclusions>
          <module name="sun.jdk" />
         </exclusions>
         <exclude-subsystems>
          <subsystem name="jaxrs" />
          <subsystem name="webservices" />
         </exclude-subsystems>
        <dependencies>
         <module name="sun.jdk" >
          <imports>
           <exclude-set>
      <path name="com/sun/org/apache/xml/internal/security/transforms/implementations"/>
           </exclude-set>
          </imports>
         </module>
         <system>
          <paths>
           <path name="sun/security/x509" />
           <path name="com/sun/org/apache/xpath/internal" />
           <path name="com/sun/org/apache/xerces/internal/dom" />
           <path name="com/sun/org/apache/xml/internal/utils" />
          </paths>
         </system>
        </dependencies>
       </deployment>
      </jboss-deployment-structure>

   3. Rebuild the openam.war file.

      $ jar cvf ../openam.war *
                           

3. You will want to make at least one more change to the openam.war file before deployment, as described in "To Prepare OpenAM for JBoss".

4. You do not need to make any of the other changes to XML files described in this section. As JBoss EAP 6.0.0 and 6.0.1 was built from JBoss AS 7.1.2 and AS 7.1.3, respectively, this procedure may also work on those versions of JBoss.

1. For JBoss EAP 6.1.0 / 6.1.1, follow Step 5 and Step 6 from "To Prepare JBoss AS 7.1.0 / 7.1.1".

2. However, you still need to review "To Prepare JBoss for OpenAM" and "To Prepare OpenAM for JBoss" to make sure the JVM and directories are configured appropriately.

The default JBoss settings for JVM do not give sufficient memory to OpenAM. This procedure documents one method that you can use to modify JBoss. Other methods described in JBoss Middleware.

1. Stop JBoss.

2. Open an appropriate JBoss configuration file. This procedure describes the use of the standalone.conf file in the /path/to/jboss/bin directory for JBoss in standalone mode.

3. Check the JVM settings associated with JAVA_OPTS. For JBoss AS 7.1.0 and AS 7.1.1, you should change the JVM heap size to -Xmx1024m. The default JVM heap size and permanent generation settings for later versions of JBoss may already exceed recommended values (-Xmx1024m, -XX:MaxPermSize=256m). 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".

4. Set the following JVM JAVA_OPTS setting in the same file.

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

   Make sure that headers include the Expires attribute rather than only Max-Age, as some versions of Internet Explorer do not support Max-Age.

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

6. You do not need to make any of the other changes to XML files described in this section. As JBoss EAP 6.0.0 and 6.0.1 was built from JBoss AS 7.1.2 and AS 7.1.3, respectively, this procedure may also work on those versions of JBoss.

To take full advantage of JBoss with OpenAM, you should make a couple of changes to the OpenAM war file. One problem is that JBoss will deploy applications from different temporary directories every time you restart the container, which would require reconfiguring OpenAM. To avoid this issue, take the following steps:

1. If you have not already done so, create a temporary directory and expand the openam.war.

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

2. Update the # configuration.dir= line in the bootstrap.properties file so that it appears as follows, and 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=$HOME/openamJboss
                   

3. Rebuild the openam.war file.

   $ jar cvf ../openam.war *
                   

1. Unpack the OpenAM 12.0.4 .war file.

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

2. Create a folder for the shared library and copy in the required files from the unpacked .war file:

   $ mkdir /opt/containers/websphere-shared
   $ cd /opt/containers/websphere-shared
   $ cp /tmp/openam/WEB-INF/lib/jackson* .

3. In the WebSphere 8.5 administration console:

   1. Navigate to Environment > Shared libraries, select the correct Scope from the drop-down list, and then click New.

   2. In the Shared Libraries configuration page, enter the following values, and then click OK.

      • Name - Jackson

      • Classpath - /opt/containers/websphere-shared

      • Use an isolated class loader for this shared library - Enabled

   3. Navigate to Applications > Application Types > WebSphere enterprise applications, click the OpenAM application, and then click Shared library references.

   4. In the list of Enterprise Applications, select OpenAM admin console, and then click Reference shared libraries.

   5. Select the Jackson shared library you created earlier, click the Add button to move it to the Selected list, and then click OK.

1. Unpack the OpenAM .war file.

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

2. Add the JAXP Reference Implementation .jar in WEB-INF/lib/.

   $ wget http://repo1.maven.org/maven2/com/sun/xml/parsers/jaxp-ri/1.4.5/jaxp-ri-1.4.5.jar
   $ mv jaxp-ri-1.4.5.jar WEB-INF/lib/

3. Pack up the OpenAM .war file to deploy in WebSphere.

   $ jar -cf ../openam.war *

4. Deploy the new .war file.

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

To use the ssoadm with WebSphere, configure the server JVM arguments as follows:

1. On the WebSphere administration console, select Servers.

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

3. Click on the name of your server.

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

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

6. Scroll down and locate the Generic JVM arguments box. Enter the following JVM 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

You might already have configured an OpenAM server before realizing that a site is what you want.

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

1. Login to OpenAM Console as administrator, by default amadmin, and then browse to Configuration > Servers and Sites > 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. Under Configuration > Servers and Sites > Server, click the link to the server configuration.

6. On the server configuration General tab page, set the Parent Site to the name of the site you just created, and then click Save to keep your 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.

If you did not set up the site during initial configuration, first follow the instructions in "To Configure a Site with a First OpenAM Server", and then follow all the steps below.

1. For each OpenAM server in the site, select Configuration > Servers and Sites > Servers > Server Name, set Parent Site to the site you created, and then Save your work.

2. Make the amlbcookie value unique for each OpenAM server.

   In an OpenAM site, the server that authenticated a user is the server that continues to manage that user's session, unless the server is no longer available. The load balancer should send subsequent requests to that server to avoid overhead resulting from the server that gets the request being different from the server that authenticated the user.

   When traffic is protected with HTTPS, this approach requires that you terminate the connection on the load balancer. You then either re-encrypt the traffic from the load balancer to OpenAM, or make connections from the load balancer to OpenAM over HTTP.

   1. For each OpenAM server console in the site, browse to Configuration > Servers and Sites > Servers > Server Name > Advanced, and set com.iplanet.am.lbcookie.value to a unique value.

      By default, the cookie value is set to the OpenAM server ID.

      Changes take effect only after you restart the OpenAM server.

   2. Restart each OpenAM server where you changed the cookie value.

      You can then check the cookie value by logging in to OpenAM console, and examining the amlbcookie cookie in your browser.

3. Configure your load balancer to perform sticky load balancing based on the amlbcookie value.

   In other words, the load balancer layer must keep track of which amlbcookie cookie value corresponds to which OpenAM server.

   When the load balancer receives a request, it inspects the value of the amlbcookie cookie, and then forwards the request to the corresponding OpenAM server.

You can increase security against possible phishing attacks through open redirect by specifying a list of valid URL resources using the Valid goto URL Resource service.

OpenAM only redirects a user if the goto and gotoOnFail URL matches any of the resources specified in this setting. If no setting is present, it is assumed that the goto or gotoOnFail URL is valid.

When setting valid goto URLs, you can use the "*" wildcard, where "*" matches all characters except "?". For more specific patterns, use resource names with wildcards as described in the procedure, Configuring Valid goto URL Resources in the Administration Guide.

1. Open the OpenAM console. Click Access Control > Realm Name > Services, and then click Add.

2. Select Validation Service.

3. In the New Value box, enter a valid goto URL, and then click Add. You can repeat this step to enter additional URLs.

Rather than changing the default pages, customize your own copy.

1. Change to the config/auth directory where you deployed OpenAM.

   $ cd /path/to/tomcat/webapps/openam/config/auth
      

2. Copy the default files and optionally the localized files to suffix[_locale]/html, where suffix is the value of the RDN of the configuration suffix, such as openam if you use the default configuration suffix dc=openam,dc=forgerock,dc=org, and the optional locale is, for example, jp for Japanese, or zh_CN for Simplified Chinese.

   The following example copies the files for the Top-Level Realm (/) for a custom French locale.

   $ mkdir -p openam/html
   $ cp -r default/* openam/html
   $ mkdir -p openam_fr/html
   $ cp -r default_fr/* openam_fr/html
      

   See "How OpenAM Looks Up UI Files" for details.

3. You can now either follow the steps in "To Copy the Pages to Customize For Another Realm", or in "To Customize Files You Copied".

As for the top-level realm, customize your own copy rather than the default pages.

1. Change to the config/auth directory where you deployed OpenAM.

   $ cd /path/to/tomcat/webapps/openam/config/auth
      

2. Depending on which locale you want to customize, copy the default files and optionally the localized files to suffix[_locale]/services/realm/html, where suffix is the value of the RDN of the configuration suffix, which is openam if you use the default configuration suffix dc=openam,dc=forgerock,dc=org.

   The following example copies the files for a custom French locale and a realm named ventes.

   $ mkdir -p openam/services/ventes/html
   $ cp -r default/* openam/services/ventes/html
   $ mkdir -p openam_fr/services/ventes/html
   $ cp -r default_fr/* openam_fr/services/ventes/html
      

3. You can now follow the steps in "To Customize Files You Copied".

The .jsp files from the default/ directory reference the images used in the OpenAM pages, and retrieve localized text from the .xml files. Thus you customize appearance through the .jsp files, being careful not to change the functionality itself. You customize the localized text through the .xml files.

1. Modify appearance if you must by editing the .jsp, image, and CSS files without changing any of the JSP tags that govern how the pages work.

2. Modify the localized text, using UTF-8 without escaped characters, by changing only the original text strings in the .xml files.

   For example, to change the text in the default OpenAM login screen in the top-level realm for the French locale, edit openam_fr/html/DataStore.xml.

3. After making the changes, restart OpenAM or the web container where it runs.

4. Test the changes you have made.

   The following screen shot shows a customized French login page where the string Nom d'utilisateur has been replaced with the string Votre identifiant in openam_fr/html/DataStore.xml.

   

5. As mentioned in the tip at the outset of this section, build a customized OpenAM .war that includes your tested changes, and use this customized .war to deploy OpenAM.

To customize classic UI elements such as button text on the login screen, follow these steps.

1. Unpack the core OpenAM library, openam-core-12.0.0.jar, that contains the text in Java properties files.

   This library is available under WEB-INF/lib/ where OpenAM is unpacked for deployment. In the following example OpenAM is deployed on Apache Tomcat.

   $ mkdir openam-core && cd openam-core
   $ jar xf /path/to/tomcat/webapps/openam/WEB-INF/lib/openam-core-12.0.0.jar
       

2. Edit only property values in the appropriate properties files.

3. Prepare a new core OpenAM library with your modifications.

   $ jar cf ../openam-core-12.0.0.jar *
       

4. Replace the existing core OpenAM library with your modified version.

   The following example replaces the library only in a deployed OpenAM server.

   $ cp openam-core-12.0.0.jar /path/to/tomcat/webapps/openam/WEB-INF/lib/
       

   When preparing for production deployment make the modification in the OpenAM war file, OpenAM-12.0.0.war, instead.

5. Restart OpenAM or the container in which it runs to load the changes.

1. Download OpenDJ.

2. Create the install script. The following is an example, which you can edit for your specific system.

   #!/bin/sh
   
   #
   # copyright (C) 2014 ForgeRock AS
   #
   # cts-setup.sh: This script installs and configures an external CTS data store.
   # It assumes that you have downloaded the OpenDJ zip file to a local
   # folder.
   
   # Reset the tmp folder
   T=/tmp/ldif
   rm -rf $T
   mkdir $T
   
   # Define variables used in this script. Make them specific to your deployment.
   
   TOMCAT_OPENAM_WEBAPP=/usr/local/tomcat/webapps/openam/WEB-INF/template/ldif/sfha
   USER="cn=Directory Manager"
   PASS="pwd"
   PORT=4444
   CTS_DN="dc=cts,dc=example,dc=com"
   
   # Make sure to download the OpenDJ Zip file and place it in the same folder as
   # this script
   DS="OpenDJ-2.6.2.zip"
   
   # Sanity Check
   [ ! -d "$TOMCAT_OPENAM_WEBAPP" ] && echo "TOMCAT OPENAM WEBAPP folder inaccessible" \
    && exit 1
   [ ! -f "$DS" ] && echo "$DS is not present" && exit 1
   
   # Create a properties file for the OpenDJ install
   printf '#\n' >> $T/setup.props
   printf '# Sample properties file to set up the OpenDJ directory server\n' >> \
    $T/setup.props
   printf '#\n' >> $T/setup.props
   printf 'hostname                      = opendj.example.com\n' >> $T/setup.props
   printf 'ldapPort                      = 1389\n' >> $T/setup.props
   printf 'generateSelfSignedCertificate = true\n' >> $T/setup.props
   printf 'enableStartTLS                = true\n' >> $T/setup.props
   printf 'ldapsPort                     = 1636\n' >> $T/setup.props
   printf 'jmxPort                       = 1689\n' >> $T/setup.props
   printf "adminConnectorPort            = $PORT\n" >> $T/setup.props
   printf "rootUserDN                    = $USER\n" >> $T/setup.props
   printf 'rootUserPassword              = pwd\n' >> $T/setup.props
   #printf '#baseDN                      = dc=example,dc=com\n' >> $T/setup.props
   #printf '#ldifFile                    = /path/to/Example.ldif\n' >> $T/setup.props
   #printf '#sampleData                  = \n' >> $T/setup.props
   
   # Create the CTS base dn and ACIs entries and write them to a file
   # Linefeeds have been added for publication purposes.
   printf '#\n' >> $T/add-cts-entries.ldif
   printf '# add-cts-entries.ldif: base DN and ACIs\n' >> $T/add-cts-entries.ldif
   printf '#\n' >> $T/add-cts-entries.ldif
   printf "dn: $CTS_DN\n" >> $T/add-cts-entries.ldif
   printf 'objectclass: top\n' >> $T/add-cts-entries.ldif
   printf 'objectclass: domain\n' >> $T/add-cts-entries.ldif
   printf 'dc: cts\n' >> $T/add-cts-entries.ldif
   printf "aci: (targetattr=\"*\")(version 3.0;acl \"Allow entry search\"; \
    allow (search, read)(userdn = \
    "ldap:///uid=openam,ou=admins,$CTS_DN\");)\n" >> $T/add-cts-entries.ldif
   printf "aci: (targetattr=\"*\")(version 3.0;acl \"Modify config entry\"; \
    allow (write)(userdn = \
    "ldap:///uid=openam,ou=admins,$CTS_DN\");)\n" >> $T/add-cts-entries.ldif
   printf "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,$CTS_DN\");)\n" >> $T/add-cts-entries.ldif
   printf "aci: (version 3.0;acl \"Add config entry\"; allow (add)(userdn = \
    "ldap:///uid=openam,ou=admins,$CTS_DN\");)\n" >> $T/add-cts-entries.ldif
   printf "aci: (version 3.0;acl \"Delete config entry\"; allow (delete)(userdn = \
    "ldap:///uid=openam,ou=admins,$CTS_DN\");)\n" >> $T/add-cts-entries.ldif
   printf '\n' >>$T/add-cts-entries.ldif
   printf "dn: ou=admins,$CTS_DN\n" >> $T/add-cts-entries.ldif
   printf 'objectclass: top\n' >> $T/add-cts-entries.ldif
   printf 'objectclass: organizationalUnit\n' >> $T/add-cts-entries.ldif
   printf 'ou: admins\n' >> $T/add-cts-entries.ldif
   printf '\n' >>$T/add-cts-entries.ldif
   printf "dn: uid=openam,ou=admins,$CTS_DN\n" >> $T/add-cts-entries.ldif
   printf 'objectclass: top\n' >> $T/add-cts-entries.ldif
   printf 'objectclass: person\n' >> $T/add-cts-entries.ldif
   printf 'objectclass: organizationalPerson\n' >> $T/add-cts-entries.ldif
   printf 'objectclass: inetOrgPerson\n' >> $T/add-cts-entries.ldif
   printf 'cn: openam\n' >> $T/add-cts-entries.ldif
   printf 'sn: openam\n' >> $T/add-cts-entries.ldif
   printf 'uid: openam\n' >> $T/add-cts-entries.ldif
   printf 'userPassword: secret12\n' >> $T/add-cts-entries.ldif
   printf 'ds-privilege-name: subentry-write\n' >> $T/add-cts-entries.ldif
   printf 'ds-privilege-name: update-schema\n' >> $T/add-cts-entries.ldif
   
   # Unzip and install OpenDJ using the properties file
   echo ""
   echo "... Unpacking OpenDJ and installing ..."
   unzip "$DS" && cd opendj
   ./setup --cli --propertiesFilePath $T/setup.props --acceptLicense --no-prompt
   
   # Create the CTS Backend
   echo ""
   echo "... Creating backend ..."
   echo ""
   bin/dsconfig create-backend \
   --backend-name cts-store \
   --set base-dn:"$CTS_DN" \
   --set enabled:true \
   --type local-db \
   --port $PORT \
   --bindDN "$USER" \
   --bindPassword $PASS \
   --trustAll \
   --no-prompt
   echo "Backend created"
   
   # Verify Backend
   #bin/dsconfig list-backends \
   #--port $PORT \
   #--bindDN "$USER" \
   #--bindPassword $PASS \
   #--trustAll \
   #--no-prompt
   
   # Add the Base DN and ACIs
   echo ""
   echo "...Adding Base DN and ACIs..."
   echo ""
   bin/ldapmodify \
   --port $PORT \
   --bindDN "$USER" \
   --bindPassword $PASS \
   --defaultAdd \
   --filename $T/add-cts-entries.ldif \
   --useSSL \
   --trustAll 
   echo "BaseDN and ACIs added."
   
   # Verify BaseDN and ACIs
   #bin/ldapsearch --port $PORT --bindDN "$USER" --bindPassword $PASS \
    --baseDN "$CTS_DN" --searchscope sub --useSSL --trustAll  "(objectclass=*)"
   
   # Add the Admin Global ACI
   echo ""
   echo "...Adding Admin Global ACIs..."
   echo ""
   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=cts,dc=example,dc=com";)' \
   --port $PORT \
   --bindDN "$USER" \
   --bindPassword $PASS \
   --trustAll \
   --no-prompt
   echo "Global ACI added."
   
   # Verify Global ACI
   #bin/dsconfig get-access-control-handler-prop --property global-aci --port $PORT \
    --bindDN "$USER" --bindPassword $PASS -X -n
   
   # Copy the Schema, Indexes, and Container files for CTS
   echo ""
   echo "... Begin copying schema, indexes, and container ..."
   cp $TOMCAT_OPENAM_WEBAPP/cts-add-schema.ldif $T/cts-add-schema.ldif
   cat $TOMCAT_OPENAM_WEBAPP/cts-indices.ldif | sed -e 's/@DB_NAME@/cts-store/' > \
    $T/cts-indices.ldif
   cat $TOMCAT_OPENAM_WEBAPP/cts-container.ldif | sed -e \
    "s/@SM_CONFIG_ROOT_SUFFIX@/$CTS_DN/" > $T/cts-container.ldif
   echo "Schema, index, and container files copied."
   
   # Add the Schema Files
   echo ""
   echo "... Adding CTS Schema ..."
   bin/ldapmodify --port $PORT --bindDN "$USER" --bindPassword $PASS \
    --fileName $T/cts-add-schema.ldif --useSSL --trustAll
   
   # Add the CTS Indexes
   echo ""
   echo "... Adding CTS Indexes ..."
   bin/ldapmodify --port $PORT --bindDN "$USER" --bindPassword $PASS --defaultAdd \
    --fileName $T/cts-indices.ldif --useSSL --trustAll
   
   # Add the CTS Container Files
   echo ""
   echo "... Adding CTS Container ..."
   bin/ldapmodify --port $PORT --bindDN "$USER" --bindPassword "$PASS" --defaultAdd \
    --fileName $T/cts-container.ldif --useSSL --trustAll
   
   # Rebuild the Indexes
   echo ""
   echo "... Rebuilding Index ..."
   bin/rebuild-index --port $PORT --bindDN "$USER" --bindPassword "$PASS" \
    --baseDN "$CTS_DN" --rebuildALL --start 0 --trustAll
   
   # Verify the Indexes
   echo ""
   echo "... Verifying Index ..."
   bin/verify-index --baseDN "$CTS_DN"
   
   echo ""
   echo "Your CTS External Store has been successfully installed and configured."
   exit 0
   

3. Make the file executable.

   chmod u+x cts-setup.sh
        

4. Run the script. Make sure the OpenDJ zip file is in your same directory and update the script accordingly.

   ./cts-setup.sh
        

The following example procedure assumes that you have implemented the previous procedure. Also note that the OpenAM server will require a restart for the configuration changes to take effect.

1. Log into the OpenAM Console.

2. On the main OpenAM Console screen, click Configuration > Servers and Sites > Server Name > CTS. For this example, the Server Name is http://openam.example.com:8080/openam.

3. On the Edit Server Name screen, click Inheritance Settings. By default, the CTS properties are inherited from the Configuration data store settings created in a previous step. We want to clear or uncheck these properties to modify these properties for CTS.

4. On the Server Property Inheritance Setting screen, uncheck the properties that you want to modify for CTS, and then click Save.

   

   • Connection String(s). For example, host1:389,host2:50389|server1|site1,host3:50389.

   • Heartbeat. Default is 10.

   • Login Id. Specifies the directory server's bind DN.

   • Max Connections. Sets the maximum number of connections to the data store.

   • Password. Specifies the directory servers admin password.

   • Port. Specifies the LDAP port of the directory server.

   • Root Suffix. Specifies the base DN of the CTS store.

   • SSL/TLS Enabled. Specifies if SSL or TLS is configured for the connection to the directory server.

   • Store Mode. Specifies if the data store is a default (internal) data store or an external store. This property is required if you want to configure an external CTS store. Note that we recommend all settings to be enabled for editing and populated with the appropriate values.

5. On the Edit Server Name screen, click External Token Store and then enter the Root Suffix for the CTS store. For this example, enter dc=cts,dc=example,dc=com.

6. Under External Store Configuration, enter the properties for the CTS backend and then click Save.

   Connection String(s)

   host1:389,host2:50389|server1|site1,host3:50389

   Login Id

   uid=openam,ou=admins,dc=cts,dc=example,dc=com

   Password

   Enter the Login ID password. For this example, enter secret12.

7. Restart the OpenAM server to complete the external CTS store configuration. If there is a problem with the configuration, view the error in the <openam-installation>/debug/Session debug log, which will indicate that the External CTS connection could not be established.

   You have successfully configured an external OpenDJ directory server and configured OpenAM to use the external CTS store. For more CTS configuration options, see "Managing CTS Tokens".