This chapter covers tasks required to install OpenAM core services, and to ensure they run properly. It includes instructions on preparing your application server to run OpenAM, preparing your identity repository to handle OpenAM identities, deploying component .war files, installing OpenAM administration tools, and performing post-installation configuration. To manage access to web resources on other servers, you can install policy agents that provide tight integration with OpenAM. See the Policy Agent Installation Guide for instructions on installing OpenAM agents in supported web servers and Java EE application containers.

OpenAM core services require the following prerequisite software installed before you begin OpenAM installation. A Java 6 runtime environment $ java -version java version "1.6.0_26" Java(TM) SE Runtime Environment (build 1.6.0_26-b03) Java HotSpot(TM) Client VM (build 20.1-b02, mixed mode, sharing) A supported application server as the deployment container See the Release Notes for a list. OpenAM core services require a minimum JVM heap size of 1 GB, and a permanent generation size of 256 MB. Apply the following JVM options before start your application server. -Xmx1024m -XX:MaxPermSize=256m If a Java Security Manager is enabled for your deployment container, add permissions before installing OpenAM. OpenAM examples here use Apache Tomcat as the deployment container. Tomcat is installed on openam.example.com, and listens on the default ports, with no Java Security Manager enabled. The script /etc/init.d/tomcat manages the service at system startup and shutdown. #!/bin/sh # # tomcat # # chkconfig: 345 95 5 # description: Manage Tomcat web application container CATALINA_HOME="/path/to/tomcat" export CATALINA_HOME JAVA_HOME=/path/to/jdk1.6 export JAVA_HOME JAVA_OPTS="-Xmx1024m -XX:MaxPermSize=256m" export JAVA_OPTS case "${1}" in start) /bin/su mark -c "${CATALINA_HOME}/bin/startup.sh" exit ${?} ;; stop) /bin/su mark -c "${CATALINA_HOME}/bin/shutdown.sh" exit ${?} ;; *) echo "Usage: $0 { start | stop }" exit 1 ;; esac A supported identity repository for user identity data See the Release Notes for a list. If you plan to use OpenAM for evaluation or testing, you can use the embedded identity repository. ForgeRock does not recommend using the embedded identity repository for production deployments, however. Examples here use OpenDJ as the identity repository. OpenDJ is installed on openam.example.com, and listens on the following ports. Port 1389 for LDAP requests and StartTLS Port 1636 for LDAP requests over SSL Port 4444 for administrative traffic The script /etc/init.d/opendj, created with the OpenDJ create-rc-script command, manages the service at system startup and shutdown. #!/bin/sh #... # chkconfig: 345 95 5 # description: Control the OpenDJ Directory Server # Set the path to the OpenDJ instance to manage INSTALL_ROOT="/path/to/OpenDJ" export INSTALL_ROOT cd ${INSTALL_ROOT} # Determine what action should be performed on the server case "${1}" in start) /bin/su mark -c "${INSTALL_ROOT}/bin/start-ds --quiet" exit ${?} ;; stop) /bin/su mark -c "${INSTALL_ROOT}/bin/stop-ds --quiet" exit ${?} ;; restart) /bin/su mark -c "${INSTALL_ROOT}/bin/stop-ds --restart --quiet" exit ${?} ;; *) echo "Usage: $0 { start | stop | restart }" exit 1 ;; esac The Example.com sample data loaded into OpenDJ are taken from the file, Example.ldif that you can download. See the OpenDJ Installation Guide for detailed installation instructions.

Download OpenAM releases from http://forgerock.com/downloads.html. At the download location you find links to stable releases, nightly builds for testing, previous releases, and also OpenAM policy agent releases. For each release of the OpenAM core services, you can download the entire package as a .zip archive, only the OpenAM .war file, or only the administrative tools as a .zip archive. After you unzip the archive of the entire package, you get an opensso directory including a README, a set of license files, and the following directories. deployable-war The deployable .war file as well as the tools and files required to create any specialized .war files you deploy. docs Javadoc API specifications for the public APIs exposed by OpenAM fedlet The lightweight service provider implementation that you embed in your Java EE application to enable it to use federated access management integrations Resources for integrating OpenAM with third-party access and identity management software ldif Schema and index definitions for use with external LDAP identity repositories legal Additional license and entitlement files libraries Client SDK and policy agent libraries patches Location for patches to apply to OpenAM samples Sample source files demonstrating how to use the OpenAM client SDK tools OpenAM tools for managing SSO, configuring deployed .war files, patching deployed .war files, managing sessions, and diagnosing deployment issues upgrade Content for upgrading from legacy versions of Sun Access Manager and Federation Manager xml OpenAM service and default delegation policy configuration files

The deployable-war/opensso.war file contains all OpenAM server components and samples. How you deploy the .war file depends on your web application container. Copy the .war file to the directory where web applications are stored. $ cp deployable-war/opensso.war /path/to/tomcat/webapps/openam.war Check that you see the initial configuration screen in your browser. Initial OpenAM configuration screen Port is 8080, but 12380 here because the port is redirected to a virtual machine. In the initial configuration screen, click Create Default Configuration under Default Configuration. Provide different passwords for the default OpenAM administrator, amadmin, and default Policy Agent users. OpenAM default configuration The default configuration asks only for two passwords. When the configuration completes, click Proceed to Login, and then login as OpenAM administrator with the first of the two passwords you provided. OpenAM first login The home page for OpenAM when logged in as the OpenAM Administrator, amadmin Stop the OpenAM web application to clear the configuration held in memory. The following example shuts down Tomcat configured as described above. $ /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 Delete OpenAM configuration files, by default in $HOME/openam. $ rm -rf $HOME/openam Restart the OpenAM web application. The following example restarts the Tomcat container. $ /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 In the initial configuration screen, click Create New Configuration under Custom Configuration. Provide a password having at least 8 characters for the OpenAM Administrator, amadmin. OpenAM amadmin password The OpenAM Administrator has username amadmin. Make sure the server settings are valid for your configuration. OpenAM server settings See OpenAM server settings below Server URL Provide a valid URL to the base of your OpenAM web container, including a fully qualified domain name (FQDN). In a test environment, you can fake the FQDN by adding it to your /etc/hosts as an alias. The following excerpt shows lines from the /etc/hosts file on a Linux system where OpenAM is installed. 127.0.0.1 localhost.localdomain localhost ::1 localhost6.localdomain6 localhost6 127.0.1.1 openam openam.example.com Cookie Domain Starts with a dot, . Platform Locale Supported locales include en_US (English), de (German), es (Spanish), fr (French), ja (Japanese), zh_CN (Simplified Chinese), and zh_TW (Traditional Chinese). Configuration Directory Location on server for OpenAM configuration files. OpenAM must be able to write to this directory. In the Configuration Store screen, you can accept the defaults to allow OpenAM to store configuration data in an embedded directory. The embedded directory can be configured separately to replicate data for high availability if necessary. You can also add this OpenAM installation to an existing deployment, proving the URL to reach an existing OpenAM instance. Alternatively, if you already manage an OpenDJ or DSEE deployment, you can choose to store OpenAM configuration data in your existing directory service. If you decide to use an existing installation of OpenDJ for configuration data, then you must first relax the restriction on objects with multiple structural object classes, by using the OpenDJ dsconfig command before completing OpenAM configuration. $ dsconfig -h hostname -p 4444 -D "cn=Directory Manager" -w password set-global-configuration-prop --set single-structural-objectclass-behavior:warn -X -n In the User Store screen, you configure where OpenAM looks for user identities. OpenAM must have write access to the directory service you choose, as it adds to the directory schema needed to allow OpenAM to manage access for users in the user store. OpenAM user store settings See OpenAM user store settings below User Data Store Type If you have a directory service already provisioned with users in a supported user data store, then select that type of directory from the options available. For OpenDJ, select OpenDS. SSL/TLS Enabled To use a secure connection, check this box, then make sure the Port you define corresponds to the port on which the directory listens for StartTLS or SSL connections. Directory Name FQDN for the host housing the directory service Port LDAP directory port. The default for LDAP and LDAP with StartTLS to protect the connection is port 389. The default for LDAP over SSL is port 636. Your directory service might use a different port. Root Suffix Base distinguished name (DN) where user data are stored Login ID Directory administrator user DN. The administrator must be capable of updating schema and user data. Password Password for the directory administrator user In the Site Configuration screen, you can set up OpenAM as part of a site where the load is balanced across multiple OpenAM servers. For your first OpenAM installation, accept the defaults. OpenAM site configuration Accept the defaults unless you load balance across multiple OpenAM servers. In the Agent Information screen, provide a password having at least 8 characters to be used by policy agents to connect to OpenAM. OpenAM policy agent password OpenAM policy agents use the password you provide to access centralized configuration information. When the configuration completes, click Proceed to Login, and then login as OpenAM administrator. OpenAM first login The home page for OpenAM when logged in as the OpenAM Administrator, amadmin

OpenAM tools are found in the tools/ directory where you unpacked the archive of the entire package. tools/ssoAdminTools.zip Administration tools like ssoadm and amtune tools/ssoConfiguratorTools.zip Tools for command line installation and configuration tools/ssoDiagnosticTools.zip Tool to check for problems with your deployment and configuration tools/ssoSessionTools.zip Session failover utilities Make sure the JAVA_HOME environment variable is properly set. $ echo $JAVA_HOME /path/to/jdk1.6 Unpack the tools from where you unzipped OpenAM. $ cd /path/to/admin/tools $ unzip /path/to/OpenAM/tools/ssoAdminTools.zip ... inflating: template/windows/bin/amtune/amtune.bat.template inflating: template/windows/bin/amverifyarchive.bat.template inflating: template/windows/bin/ssoadm.bat.template 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 (example: /opensso):/home/mark/openam Debug Directory:/home/mark/openam Log Directory:/home/mark/openam The scripts are properly setup under directory: /path/to/admin/tools/openam Debug directory is /home/mark/openam. Log directory is /home/mark/openam. 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 amtune/ amverifyarchive ssoadm Activate ssoadm, which is disabled by default. Login to the console as the OpenAM administrator, amadmin. Under Configuration > Servers and Sites, click the server to configure to edit the properties. On the Advanced tab page, add a property with name ssoadm.disabled and value false, and then save your work. Check that ssoadm works properly. $ echo password > /tmp/pwd.txt $ chmod 400 /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. Make sure the JAVA_HOME environment variable is properly set. $ echo $JAVA_HOME /path/to/jdk1.6 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 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 diagnostic tool, ssodtool.sh (ssodtool.bat on Windows), works in both graphical and console mode. Make sure the JAVA_HOME environment variable is properly set. $ echo $JAVA_HOME /path/to/jdk1.6 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. Expect this procedure to change as the new, OpenDJ-based session failover capabilities are included in OpenAM. Make sure the JAVA_HOME environment variable is properly set. $ echo $JAVA_HOME /path/to/jdk1.6 Install the necessary scripts for session failover. $ setup -p scripts The scripts are properly setup under directory: /path/to/session/tools/scripts ... For instructions on making sessions available across a site, see the chapter on Setting Up OpenAM Session Failover.

TODO

TODO

When you need to prevent end users from having direct access to the service URLs OpenAM uses to manage access, you can deploy the distributed authentication service (DAS) in your DMZ, leaving OpenAM core services behind the firewall that end users cannot access. You complete the following stages in deployment the DAS web service. Create the .war file for the DAS using OpenAM software. Deploy the DAS .war file into your web application container. How you deploy the DAS .war file depends on your web application container. The procedure in this section shows how to deploy on Apache Tomcat. Create an agent profile for the DAS. Configure the DAS UI to access OpenAM core services. Configure your firewall to allow end user access to the DAS. Firewall configuration is not described here. 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 Create the das.war file. $ cd /path/to/OpenAM/deployable-war $ sh createwar.sh --staging /tmp/das --type distauth --warfile das.war Put the das.war you created in the Tomcat webapps/ directory. $ mv das.war /path/to/tomcat/webapps/ Check that you see the initial DAS configuration screen in your browser. Initial DAS configuration screen The first time you access the DAS, you must configure access to OpenAM. Login to OpenAM as the administrator, amadmin. Under the Access Control > click / (Top Level Realm). Under the Agents > 2.2 Agents tab, click New... to open the New Agent page. Create a new agent user profile. The subsequent procedures in this section have an agent with name dasUser and password password. Configure the DAS using the agent profile to connect to OpenAM. Completed DAS configuration screen Configure access to OpenAM. Login through the DAS to access OpenAM services. The first time you test this in your lab or on your laptop, you can set up sample authentication data, and a sample realm that gives you a landing page after successful login. Otherwise the default result of successful login is a redirect to the default success login URL, which is /openam/console, resulting in a successful login, but an error in the browser. Indeed, /openam/console is a URL you probably do not want to expose outside the firewall. Instead, follow these steps to see the DAS at work. When setting up OpenAM, use OpenDJ with the sample data mentioned above. Login to the OpenAM console as the OpenAM Administrator, amadmin. Under the Access Control tab, in the Realms section, click New... to create a new Realm called Example. On the General tab for the Example realm, add .example.com. On the Authentication tab for the Example realm, make sure the Default Success Login URL list contains only the value /das/click/index.html. Edit the file /path/to/tomcat/webapps/das/click/index.html so it looks like this: <html> <head> <title>Successful login</title> </head> <body> <p>Congratulations, you have logged in successfully.</p> <p>Click <a href="../UI/Logout.jsp">here</a> to logout.</p> </body> </html> In your browser, visit the login page. For example, if Apache Tomcat is listening on localhost:8080, then browse to http://localhost:8081/das/UI/Login?org=/Example. Login as a sample user from the Example.ldif file, such as user bjensen who has password hifalutin. Logging into OpenAM through the DAS The DAS UI handles access to OpenAM. Successfully logged in through the DAS The DAS UI redirects the user to the URL you configured for the realm.

TODO