The openam-server-10.2.0-SNAPSHOT.war file contains all OpenAM server components and samples. 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/openam-server-10.2.0-SNAPSHOT.war 
       /path/to/tomcat/webapps/openam.war

   Note

   By adding openam.war to the end of the path, the name of the .war file will be changed from openam-server-only-10.2.0-SNAPSHOT.war to openam.war to make deployment easier.

2. Check that you see the initial configuration screen in your browser at openam.example.com:8080/openam.

   Note

   You should NOT use localhost domain for accessing OpenAM, not even for testing purposes, because OpenAM strongly relies on browser cookies. Also the chosen domain name should contain at least 2 '.' (dot) characters, like openam.example.com. This gives your instance a domain, example, and a subdomain, openam. Sub-domains provide an extra layer of organization for different department or types of users or clients. It also provides a level of control over your top- level domain that you would not have if you used .com or .org.

   

   
   [D]

The default configuration option will basically configure the embedded OpenDJ instance on default ports (if the ports are already in use, OpenAM will look for a free port) as both configuration store and identity store. The install will create a standalone OpenAM instance using the subset of the fully qualified hostname as the cookie domain. In the example .example.com the cookie domain is set to .example.com.

1. In the initial configuration screen, click Create Default Configuration under Default Configuration.

2. Provide different passwords for the default OpenAM administrator, amadmin, and default Policy Agent users.

   

   
   [D]

3. When the configuration completes, click Proceed to Login, and then login as OpenAM administrator with the first of the two passwords you provided.

   

   
   [D]

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

2. Delete OpenAM configuration files, by default under the $HOME of the user running the web application container.

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

   Note

   When using the internal OpenAM configuration store, this step deletes the embedded directory server and all of its contents. You should always stop the application server before removing the configuration files. In case you're using external configuration store make sure you delete the entries under the configured OpenAM suffix (by default dc=openam,dc=forgerock,dc=org).

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

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

2. Provide a password having at least 8 characters for the OpenAM Administrator, amadmin.

   

   
   [D]

3. Make sure the server settings are valid for your configuration.

   

   
   [D]

   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), ko (Korean), 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.

4. 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, providing the URL to reach an existing OpenAM instance. Procedure 2.5, “Configuring an Additional Instance” provides information on setting up an additional instance of OpenAM.

   Alternatively, if you already manage an OpenDJ or DSEE deployment, you can choose to store OpenAM configuration data in your existing directory service. You must, however, create the suffix to store configuration data on the directory server before you configure OpenAM. OpenAM does not create the suffix when you use an external configuration store.

   Note

   When you create a new OpenAM custom configuration that uses an external LDAP directory server for the configuration data store, you must use a root suffix DN with at least two domain components, such as dc=example,dc=com. The root suffix must be dc. You will not be able to move to the next configuration screen if both of these conditions are not met.

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

   

   
   [D]

   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.

   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. When using this option you also need to make sure the trust store used by the JVM running OpenAM has the necessary certificates installed.

   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

6. 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, you can accept the defaults. If you have a load balancer, you can enable session high availability persistence. This will store sessions in case of a server failure, so that when the server is restored, users will be returned to their sessions without having to login again. If you would like to enable session high availability persistence or if you plan to setup additional instances, enter the Site Name, Load Balancer URL, and click the Enable Session HA Persistence and Failover.

   

   
   [D]

   If you plan to set up an additional instance but are not ready yet, you do not have to set it up now. The site configuration can be set up during configuration of your additional instances.

7. In the Agent Information screen, provide a password having at least 8 characters to be used by policy agents to connect to OpenAM.

   

   
   [D]

8. When the configuration completes, click Proceed to Login, and then login as OpenAM administrator.

   

   
   [D]

9. Restrict permissions to the configuration directory (by default $HOME/openam, where $HOME corresponds to the user who runs the web container).

When an additional OpenAM instance is necessary (usually for Setting Up OpenAM Session Failover [SFO]), it is configured separately from the first instance.

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

2. Enter the same password entered during the first instance configuration for the OpenAM Administrator, amadmin.

   Note

   If you make a mistake at any time during the configuration, click on the Previous button and the OpenAM Configurator will return to the previous screen. When you click Next, the original default values will appear.

3. Make sure the server settings are valid for your configuration.

   If you make changes to the default values, an x mark or a check mark will indicate if the added value is acceptable. For example, you cannot add additional instances under the same configuration directory as the first instance.

   

   
   [D]

4. Click on Add to Existing Deployment?. Enter the Server URL of the first instance, for example http://openam.example.com:18080/openam. You should be able to accept the default settings once your Server URL has been verified.

   

   
   [D]

5. Select Yes to add the load balancer with each additional instance. It is alright if you did not add the load balancer with the first instance. The SFO chapter describes how to add the load balancer to the first instance.

   Enter the Site Name, for example openamlb, and the Load Balancer URL.

   

   
   [D]

6. Verify the Configurator Summary Details.

7. When the configuration completes, click Proceed to Login, and then login as OpenAM administrator.

You can deploy OpenAM core services without including the console if you install the console elsewhere, or if you plan to perform all configuration using ssoadm for example.

1. Deploy the openam-server-only-10.2.0-SNAPSHOT.war file on your container.

   For example, copy the file to deploy on Apache Tomcat.

   $ cp ~/Downloads/openam/openam-server-only-10.2.0-SNAPSHOT.war 
       /path/to/tomcat/webapps/coreonly.war

   Note

   By adding coreonly.war to the end of the path, the name of the .war file will be changed from openam-server-only-10.2.0-SNAPSHOT.war to coreonly.war so the deployment URI will be /coreonly.

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

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