1. Make sure the JAVA_HOME environment variable is properly set.

   $ echo $JAVA_HOME
   /path/to/jdk1.6

2. Unpack the tools from where you unzipped OpenAM.

   $ cd /path/to/admin/tools
   $ unzip /path/to/OpenAM/tools/ssoAdminTools.zip
   ...
     inflating: template/windows/bin/amverifyarchive.bat.template
     inflating: template/windows/bin/ssoadm.bat.template

3. Run the setup utility (setup.bat on Windows), providing the path to the directory where OpenAM configuration files are located, and where you want debug and log information to be located.

   $ ./setup
   Path to config files of OpenAM server [/home/mark/openam]:
   Debug Directory [/path/to/admin/tools/debug]:
   Log Directory [/path/to/admin/tools/log]:
   The scripts are properly setup under directory: /path/to/admin/tools/openam
   Debug directory is /path/to/admin/tools/debug.
   Log directory is /path/to/admin/tools/log.
   The version of this tools.zip is: (2011-July-11 00:05)
   The version of your server instance is: (2011-July-11 00:05)

   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.

4. Check that ssoadm works properly.

   $ umask 366
   $ echo password > /tmp/pwd.txt
   $ openam/bin/ssoadm list-servers -u amadmin -f /tmp/pwd.txt
   
   http://openam.example.com:8080/openam

   The ssoadm commands can also be run from ssoadm.jsp in OpenAM, for example at http://openam.example.com:8080/openam/ssoadm.jsp, once the page has been enabled as described in the section on OpenAM ssoadm.jsp in the Administration Guide in the Administration Guide.

   Not all the commands are available on ssoadm.jsp, however this limitation is not present for the command line tool.

5. (Optional) If you connect to OpenAM over SSL (HTTPS), and the SSL certificate was not signed by a CA whose certificate is found in the Java cacerts truststore (for example, you used a self-signed certificate as described in the Administration Guide procedure, To Set Up OpenAM With HTTPS on Tomcat in the Administration Guide), then edit the ssoadm (ssoadm.bat on Windows) script such that ssoadm recognizes the certificate.

   Add two additional options to the java command in the script to identify the proper truststore and truststore password, depending on how you set up SSL.

   -D"javax.net.ssl.trustStore=/path/to/tomcat/conf/keystore.jks"
    -D"javax.net.ssl.trustStorePassword=changeit"

6. (Optional) If you have deployed OpenAM in a site configuration, edit the ssoadm (ssoadm.bat on Windows) script to map the site name to servers.

   You add a com.iplanet.am.naming.map.site.to.server property to the java command in the script.

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

   Notice that the mapping is a comma separated list of server URLs, openam-url, in the site with the load balancer URL, lb-url. For example, if your site is behind https://lb.example.com:443/openam, and the OpenAM servers are at http://openam1.example.com:8080/openam and http://openam2.example.com:8080/openam, then you add the following property to the java command (without line breaks).

   -D"com.iplanet.am.naming.map.site.to.server=
      https://lb.example.com:443/openam=http://openam1.example.com:8080/openam,
      https://lb.example.com:443/openam=http://openam2.example.com:8080/openam"

1. Make sure the JAVA_HOME environment variable is properly set.

   $ echo $JAVA_HOME
   /path/to/jdk1.6

2. Unpack the tools from where you unzipped OpenAM.

   $ unzip /path/to/OpenAM/tools/ssoConfiguratorTools.zip 
   Archive:  /path/to/OpenAM/tools/ssoConfiguratorTools.zip
     inflating: README.setup
     inflating: configurator.jar
     inflating: sampleconfiguration
     inflating: sampleupgrade
     inflating: upgrade.jar

   Set up configuration files based on the sampleconfiguration example, and then apply the configuration to a deployed OpenAM .war file using the following command.

   $ java -jar configurator.jar -f config.file

   The config.file is set up by default to use the embedded data store with OpenAM installed on server1.example.com. You must edit the file before using it, as described in the OpenAM Reference for configurator.jar in the Reference.

The diagnostic tool, ssodtool.sh (ssodtool.bat on Windows), works in both graphical and console mode.

1. Make sure the JAVA_HOME environment variable is properly set.

   $ echo $JAVA_HOME
   /path/to/jdk1.6

2. Unpack the tools from where you unzipped OpenAM.

   $ unzip /path/to/OpenAM/tools/ssoDiagnosticTools.zip
   ...
     inflating: services/webcontainer/service.xml
     inflating: ssodtool.bat
     inflating: ssodtool.sh

   You can start the graphical user interface by using the tools without options, or in console mode using the ssodtool.sh --console command.

1. Unpack the opensso.war file into a temporary directory.

   $ mkdir -p /tmp/headless ; cd /tmp/headless
   $ jar xf /path/to/OpenAM/deployable-war/opensso.war

2. Create the headless.war file.

   $ cd /path/to/OpenAM/deployable-war
   $ sh createwar.sh -s /tmp/headless --type noconsole -w headless.war

1. Put the headless.war you created in the Tomcat webapps/ directory.

   $ mv headless.war /path/to/tomcat/webapps/

2. Browse to the console application, for example http://host.example.com:8080/headless/, and configure OpenAM core services as if you were deploying with a full version.

3. Restrict permissions to the $HOME/headless configuration directory, where $HOME corresponds to the user who runs the web container.

1. Unpack the opensso.war file into a temporary directory.

   $ mkdir -p /tmp/das ; cd /tmp/das
   $ jar xf /path/to/OpenAM/deployable-war/opensso.war

2. Create the das.war file.

   $ cd /path/to/OpenAM/deployable-war
   $ sh createwar.sh --staging /tmp/das --type distauth --warfile das.war

1. Put the das.war you created in the Tomcat webapps/ directory.

   $ mv das.war /path/to/tomcat/webapps/

2. Check that you see the initial DAS configuration screen in your browser.

1. Configure the DAS using the agent profile to connect to OpenAM.

   

   Most DAS configuration choices require no clarification. Hints for equivocal parameters follow.

   Debug Level

   Default is error. Other options include error, warning, message, and off.

   Encryption Key

   Do not change the password encryption key.

   Application User Name

   The DAS uses this identity, such as UrlAccessAgent, to authenticate to OpenAM.

   Application User Password

   The DAS uses this password to authenticate to OpenAM.

2. Login through the DAS to access OpenAM services.

   For testing, you can login as user demo, password changeit.

   

   When the /openam/idm/EndUser page is inside the firewall, and therefore not visible to users outside, redirect the browser after successful login to a page that exists. One way to do this is to use the goto parameter in the URL.

   https://das.example.com/das/UI/Login?goto=absolute-successful-redirect-URL

   On successful login, your browser stores an AMDistAuthConfig cookie that identifies the DAS.

3. Restrict permissions to the configuration for the DAS under the $HOME/FAMDistAuth directory of the user who runs the web container where you deployed the service.

   The configuration file name ends in AMDistAuthConfig.properties.

   If you deploy multiple DAS servers, you can configure them to forward requests to each other based on the AMDistAuthConfig cookie by setting the com.sun.identity.distauth.cluster property in this file. The following example lines are wrapped to fit on the page, but you put the entire property on a single line in the configuration file.

   com.sun.identity.distauth.cluster=
    http://das.example.com:8080/das/UI/Login,
    http://das2.example.com:8080/das/UI/Login

The sample web application deploys in your container to show you the client SDK samples in action.

1. Deploy the .war in your Java web application container such as Apache Tomcat or JBoss.

   $ cp war/opensso-client-jdk15.war /path/to/tomcat/webapps/client.war

2. Browse to the location where you deployed the client, and configure the application to access OpenAM using the application user name, UrlAccessAgent, and password configured when you set up OpenAM.

   

   The sample client writes configuration information under $HOME/OpenSSOClient/, where $HOME is that of the user running the web application container.

3. Verify that you have properly configured the sample web application.

   1. On the Client Samples page, click Access Management Samples.

   2. In another browser tab page of the same browser instance, login to OpenAM as the OpenAM Administrator, amadmin.

      This signs you into OpenAM, storing the cookie in your browser.

   3. On the Samples tab page, click the link under Single Sign On Token Verification Servlet.

      If the sample web application is properly configured, you should see something like the following text in your browser.

      SSOToken host name: 192.168.56.1
      SSOToken Principal name: id=amadmin,ou=user,o=openam
      Authentication type used: DataStore
      IPAddress of the host: 192.168.56.1
      SSO Token validation test succeeded
      The token id is AQIC5wM2LY4SfcyeA2UgS0dLJIb-xjJClrk_EIXBpdzh7RI.*AAJTSQACMDE.*
      Property: Company: Sun Microsystems
      Property: Country: USA
      User Attributes: {sunIdentityMSISDNNumber=[], mail=[],
       dn=[uid=amAdmin,ou=people,o=openam], givenName=[amAdmin],
       inetUserStatus=[Active], telephoneNumber=[], sn=[amAdmin],
       roles=[Top-level Admin Role], employeeNumber=[], postalAddress=[],
       iplanet-am-user-success-url=[], iplanet-am-user-failure-url=[],
       cn=[amAdmin], iplanet-am-user-alias-list=[]}

1. Compile the sample applications.

   $ cd sdk/
   $ sh scripts/compile-samples.sh

2. Configure the samples to access OpenAM.

   $ sh scripts/setup.sh
   Debug directory (make sure this directory exists): /tmp
   Application user (e.g. URLAccessAgent) password: secret12
   Protocol of the server: http
   Host name of the server: openam.example.com
   Port of the server: 8080
   Server's deployment URI: /openam
   Naming URL (hit enter to accept default value,
    http://openam.example.com:8080/openam/namingservice):
   $

3. Verify that you have properly configured the samples.

   $ sh scripts/Login.sh
   Realm (e.g. /):
   Login module name (e.g. DataStore or LDAP): LDAP
   Login locale (e.g. en_US or fr_FR): en_US
   LDAP: Obtained login context
   User Name:bjensen
   Password:hifalutin
   Login succeeded.
   Logged Out!!

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 opensso if you use the default configuration suffix dc=opensso,dc=java,dc=net, 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.

As for the top-level realm, customize your 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.

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

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

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. If necessary, restart OpenAM or the web container to 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, and the string Mot de passe has been replaced with the string Votre mot de passe in openam_fr/html/DataStore.xml.

   

Before you set up session failover, first configure OpenAM in a site configuration with a load balancer as the entry point to the site. The most expedient way to configure the site is to set it up during initial OpenAM configuration, where OpenAM can manage and replicate server configuration for availability. If you did not set up the site during initial configuration, then follow all the steps below.

1. In the OpenAM console for one of the servers in the site, select Configuration > Servers and Sites > Sites > New..., and then create a new site.

   The site URL is the URL to the load balancer in front of your OpenAM servers in the site. For example, if your load balancer listens on host lb.example.com and port 8080, with OpenAM under /openam, then your site URL is http://lb.example.com:8080/openam.

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

3. (Optional) If you want to use sticky load balancing, configure your load balancer to inspect the value of the amlbcookie to determine which OpenAM server should receive the client request.

   As your load balancer depends on the amlbcookie value, on each OpenAM server console in the site, select Configuration > Servers and Sites > Servers > Server Name > Advanced, makes sure that com.iplanet.am.lbcookie.value is unique. By default the value of the amlbcookie is set to the server ID for the OpenAM instance.

   Note

   When using SSL, the approach requires that you either terminate SSL on the load balancer, or that you re-encrypt traffic from the load balancer to the OpenAM servers.

   If you must change amlbcookie values to make them unique, then your changes take effect after you restart the OpenAM server. (To check, login to the console and check the cookie value in your browser.)

4. Restart each OpenAM server or the web containers where the OpenAM servers run so that all configuration changes take effect.

The session data service relies on Open Message Queue and Berkeley DB Java Edition. You set up the session failover service in a site cluster to serve as the highly available session data store.

1. Install the session tools from ssoSessionTools.zip on at least two, and generally not more than four, servers where you run OpenAM.^[1]

   For example, you can install the session tools in the OpenAM configuration directory.

   $ cd $HOME/openam
   $ unzip /path/to/OpenAM/tools/ssoSessionTools.zip
   ...
   $ ./setup
   Name of the directory to install the scripts (example: sfoscripts):sfoscripts
   The scripts are properly setup under directory: /home/user/openam/sfoscripts
   JMQ is properly setup under directory /home/user/openam/jmq

2. Start the Message Queue broker in order to configure user accounts.

   $ cd jmq/imq/bin
   $ ./imqbrokerd -name aminstance -port 7777 &

3. Change the default admin password from admin to something else.

   $ ./imqusermgr update -u admin -p password -i aminstance
   User repository for broker instance: aminstance
   Are you sure you want to update user admin? (y/n)[n] y
   User admin successfully updated.

4. Disable the default guest account.

   $ ./imqusermgr update -u guest -a false -i aminstance
   User repository for broker instance: aminstance
   Are you sure you want to update user guest? (y/n)[n] y
   User guest successfully updated.

5. Add a user for the session failover service.

   $ ./imqusermgr add -u openamuser -g admin -p secret12 -i aminstance
   User repository for broker instance: aminstance
   User openamuser successfully added.

6. Create a password file for the session failover service.

   $ cd ../../../sfoscripts/bin/
   $ ./amsfopassword --encrypt secret12 --passwordfile /home/user/openam/mqpwd.txt
   os.name=Linux
   SUCCESSFUL

7. Stop the broker you started on port 7777.

   $ fg
   ./imqbrokerd -name aminstance -port 7777 (wd: ~/openam/jmq/imq/bin)
   ^C
   [05/Mar/2012:08:35:22 CET] [B1047]: Shutting down broker...
   [05/Mar/2012:08:35:22 CET] [B1077]: Broadcast good-bye to all connections ...
   [05/Mar/2012:08:35:22 CET] [B1078]: Flushing good-bye messages ...
   [05/Mar/2012:08:35:23 CET] [B1048]: Shutdown of broker complete.

8. Configure the session failover service for the site.

   For each session tools installation, edit the /home/user/openam/sfoscripts/config/lib/amsfo.conf configuration file to change at least the USER_NAME, CLUSTER_LIST, and PASSWORDFILE parameters.

   USER_NAME should match the user you created for the session failover service.

   USER_NAME=openamuser

   CLUSTER_LIST specifies the host:port combinations for all the session failover services you configure for the site.

   CLUSTER_LIST=openam.example.com:7777,openam2.example.com:7777

   PASSWORDFILE specifies the path to the password file you created.

   PASSWORDFILE=/home/user/openam/mqpwd.txt

   You can optionally set AMSESSIONDB_ARGS="-v" to log additional information.

Enabling session failover at this point involves configuring OpenAM to use the session data store, and then starting services. Examples in this procedure show OpenAM running in Apache Tomcat.

1. On one of the OpenAM servers in the site, login to the console, and then select Configuration > Global > Session > Instances > New... to set up session data store access.

   Provide a user name for the Session Store User, such as openamuser, with the same password you entered into the password file, and the Database Url is the host:port combination that you entered for the CLUSTER_LIST parameter.

   Be sure to Add the new instance, and then also Save your configuration changes. The configuration changes take effect after you restart OpenAM.

2. Stop each OpenAM server in the site.

   $ /etc/init.d/tomcat stop

3. Start each session data service in the cluster.

   $ cd /home/user/openam/sfoscripts/bin
   $ ./amsfo start

   By default, the log and session data store are located under /tmp/amsession/.

   $ tail -f /tmp/amsession/logs/amsessiondb.log
   ...
   Initializing and connecting to the Message Queue server ...
   Successfully started.

4. Start each OpenAM server in the site.

   $ /etc/init.d/tomcat start

   Wait for each OpenAM server to start before starting another.

   $ tail -f /path/to/tomcat/logs/catalina.out
   ...
   INFO: Server startup in 26047 ms

   After OpenAM has started, you can test session failover.

ForgeRock has considerably simplified OpenAM core services upgrade with respect to earlier versions. If you have already moved to OpenAM 9.5 or later, follow these steps.

1. If you have customized end user OpenAM files for your deployment, build a new .war with the new version of OpenAM that includes your customizations.

2. If OpenAM is running in a site deployment with multiple servers, configure your load balancer to take the OpenAM server out of the site pool during upgrade.

3. Stop the container where OpenAM is running.

   $ /etc/init.d/tomcat stop
   Password: 
   Using CATALINA_BASE:   /path/to/tomcat
   Using CATALINA_HOME:   /path/to/tomcat
   Using CATALINA_TMPDIR: /path/to/tomcat/temp
   Using JRE_HOME:        /path/to/jdk1.6/jre
   Using CLASSPATH:       /path/to/tomcat/bin/bootstrap.jar:
    /path/to/tomcat/bin/tomcat-juli.jar

4. Make a copy of the OpenAM configuration directory that was created at installation time.

   In the following example, the OpenAM configuration directory is $HOME/openam, where $HOME is the home directory of the user running the container where OpenAM is deployed.

   $ cd $HOME
   $ cp -r openam openam-orig

   Files in the hidden $HOME/.openssocfg/ directory are not changed during upgrade.

5. Make a backup copy of the OpenAM configuration stored in your configuration store.

6. Move the current OpenAM web application aside.

   $ cd /path/to/tomcat/webapps
   $ mv openam openam-orig ; mv openam.war openam.war.orig

7. Deploy the new OpenAM in place of the old.

   $ cp /path/to/new/OpenAM/deployable-war/opensso.war openam.war

8. If your container caches OpenAM files, clear out the cache.

   $ rm -rf /path/to/tomcat/work/Catalina/localhost/openam

9. Start the container to run the new OpenAM.

   $ /etc/init.d/tomcat start
   Password: 
   Using CATALINA_BASE:   /path/to/tomcat
   Using CATALINA_HOME:   /path/to/tomcat
   Using CATALINA_TMPDIR: /path/to/tomcat/temp
   Using JRE_HOME:        /path/to/jdk1.6/jre
   Using CLASSPATH:       /path/to/tomcat/bin/bootstrap.jar:
    /path/to/tomcat/bin/tomcat-juli.jar

10. In your browser, visit the location where OpenAM is deployed, such as http://openam.example.com:8080/openam, and then click Upgrade to OpenAM 10.0.0.

    

11. In the Upgrading OpenAM screen, click Save Report to download an OpenAM Upgrade Report listing necessary configuration changes, and then click Upgrade.

    

    Log messages pertaining to upgrade of the embedded directory are written to the web container log.

12. When upgrade completes, restart OpenAM or the container where it runs, and continue your work.

    In site deployments with multiple OpenAM servers using the embedded OpenDJ configuration store, you must keep the first upgraded server running when upgrading the others.

    This allows secondary servers to correctly replicate their embedded configuration stores with that of the first server you upgraded.

13. If OpenAM is running in a site deployment with multiple servers, configure your load balancer to return the OpenAM server to the site pool.

If you must revert from an upgraded version of OpenAM, then the quickest way to return to the earlier version is to restore all the earlier files. You also must return to an earlier version of the configuration store data.

1. Stop OpenAM or the container where OpenAM is running.

2. Restore the old version of OpenAM files, including the .war and the configuration directory.

3. If your container caches OpenAM files, clear out the cache.

   $ rm -rf /path/to/tomcat/work/Catalina/localhost/openam

4. Restore the earlier version of the configuration store data.

5. (Optional) If you run OpenAM in Tomcat, remove files from the working directory where Tomcat has stored JSP files from the upgraded version.

   $ rm -fr /path/to/tomcat/work/Catalina/localhost/openam

   If you skip this step, you can see an error like the following when logging into the console after reverting to the older version.

   amConsole:10/29/2011 05:42:51:812 PM BST: Thread[http-8080-3,5,main]
   ERROR: ConsoleServletBase.onUncaughtException
   javax.servlet.ServletException: java.lang.NoClassDefFoundError:
    org/forgerock/openam/console/ui/taglib/header/CCHtmlHeaderTag
           at org.apache.jasper.runtime.PageContextImpl.doHandlePageException
            (PageContextImpl.java:862)
           at org.apache.jasper.runtime.PageContextImpl.handlePageException
            (PageContextImpl.java:791)
           at org.apache.jsp.console.task.Home_jsp._jspService(Home_jsp.java:564)
           at org.apache.jasper.runtime.HttpJspBase.service(HttpJspBase.java:70)

6. Start the earlier version of OpenAM or the container where OpenAM runs.

After you have deployed and configured OpenAM core services, you have at least two, perhaps three or four, locations where OpenAM files are stored on your system.

You remove the internal OpenAM configuration store when you follow the procedure below. If you used an external configuration store, you can remove OpenAM configuration data after removing all the software.

1. Shut down the web application container in which you deployed OpenAM.

   $ /etc/init.d/tomcat stop
   Password:
   Using CATALINA_BASE:   /path/to/tomcat
   Using CATALINA_HOME:   /path/to/tomcat
   Using CATALINA_TMPDIR: /path/to/tomcat/temp
   Using JRE_HOME:        /path/to/jdk1.6/jre
   Using CLASSPATH:       /path/to/tomcat/bin/bootstrap.jar:
    /path/to/tomcat/bin/tomcat-juli.jar

2. Unconfigure OpenAM by removing configuration files found in the $HOME directory of the user running the web application container.

   For a full install of OpenAM core services, configuration files include the following.

   • The configuration directory, by default $HOME/openam. If you did not use the default configuration location, then check in the OpenAM console under Configuration > Servers and Sites > Server Name > General > System > Base installation directory.

   • The hidden file that points to the configuration directory.

     For example, if you are using Apache Tomcat as the web container, this file could be $HOME/.openssocfg/AMConfig_path_to_tomcat_webapps_openam_.

   $ rm -rf $HOME/openam $HOME/.openssocfg

   Note

   At this point, you can restart the web container and configure OpenAM anew if you only want to start over with a clean configuration rather than removing OpenAM completely.

   If you used an external configuration store you must also remove the configuration manually from your external directory server. The default base DN for the OpenAM configuration is dc=opensso,dc=java,dc=net.

3. Undeploy the OpenAM web application.

   For example, if you are using Apache Tomcat as the web container, remove the .war file and expanded web application from the container.

   $ cd /path/to/tomcat/webapps/
   $ rm -rf openam.war openam/

4. If you have stored a download or unpacked version of OpenAM software on your system, you can now remove the files.

   If you cannot find the original .zip, search for files named openam_*.zip.

   $ find . -name "openam_*.zip"
   ./Downloads/openam_nightly_20110808.zip
   $ rm ./Downloads/openam_nightly_20110808.zip

   If you cannot find the unpacked version, you might search for the directory named deployable-war.

   $ locate deployable-war/
   /path/to/OpenAM/deployable-war/README
   ...
   $ rm -rf /path/to/OpenAM