OpenAM requires that you use fully qualified domain names when protecting web resources. This is because OpenAM uses HTTP cookies to keep track of sessions for single sign on, and setting and reading cookies depends on the server name and domain.

You can get started with OpenAM however without setting up separate systems for each fully qualified domain name. Instead, give your system openam.example.com and www.example.com aliases by editing your hosts file.

Alternatively, if you already have DNS set up, you can use that instead of using your hosts file.

• Add the aliases to your hosts file using your preferred text editor.

  $ sudo vi /etc/hosts
  Password:
  
  ### Edit /etc/hosts ###
  
  $ cat /etc/hosts | grep openam
  127.0.0.1    localhost openam.example.com www.example.com

Apache HTTP Server is a popular web server, and one that is well supported by OpenAM's web policy agents. Apache HTTP Server might already be installed on your system, but since you are installing software only to get started with OpenAM, install the web server separately rather than modify any existing installations.

Full installation instructions are available online. The following steps are inspired by the Overview for the impatient for Apache HTTP Server 2.2 in the online documentation.

1. Make sure you have the tools installed to build Apache HTTP Server 2.2 from source.

   On Linux distributions, you need development tools including the C compiler. How you install these depends on your distribution.

   This might work for Red Hat and CentOS distributions:

   # yum groupinstall 'Development Tools'

   This might work for Ubuntu distributions:

   $ sudo apt-get install build-essential checkinstall

2. Download Apache HTTP Server 2.2 sources from the Apache download page.

   The OpenAM web policy agent requires Apache Portable Runtime 1.3 or later, so make sure you download Apache HTTP Server 2.2.9 or later.

3. Extract the download.

4. Configure the sources for compilation.

   The --prefix option can be used so that the web server is installed in a location where you can write files.

   $ cd ~/Downloads/httpd-2.2.25
   $ ./configure --prefix=/path/to/apache

5. Compile Apache HTTP Server.

   $ make

6. Install Apache HTTP Server.

   $ make install

7. Edit the configuration to set the server name to www.example.com and the port to one such as 8000 that the web server process can use when starting with your user ID.

   $ vi /path/to/apache/conf/httpd.conf
   $ grep 8000 /path/to/apache/conf/httpd.conf
   Listen 8000
   ServerName www.example.com:8000

8. Test that Apache HTTP Server is working.

   1. Start the web server.

      $ /path/to/apache/bin/apachectl -k start

   2. Browse to the home page, such as http://www.example.com:8000.

      

      This is the page to protect with OpenAM. Make sure you have successfully gotten to this point before you proceed.

OpenAM runs as a Java web application inside an application container. Apache Tomcat is one such application container that runs on a variety of platforms. The following instructions are loosely based on the RUNNING.txt file delivered with Tomcat.

1. Make sure you have a recent Java Development Kit release installed.

   One way of checking the version of the Java Development Kit is to list the version of the javac compiler.

   $ javac -version

   If the javac compiler is not found, then either you do not have a Java Development Kit installed, or it is installed but not on your PATH.

   The OpenAM Release Notes in the Release Notes indicate what versions of Java Development Kit are supported. Supported Java Development Kit versions also work for Apache Tomcat.

2. Download Apache Tomcat 7 from its download page.

3. Extract the download.

   $ cd /path/to
   $ unzip ~/Downloads/apache-tomcat-7.0.42.zip
   $ mv apache-tomcat-7.0.42 tomcat

4. On UNIX-like systems, make the scripts in Tomcat's bin/ directory executable.

   $ chmod +x /path/to/tomcat/bin/*.sh

5. Set the JAVA_HOME environment variable to the file system location of the Java Development Kit.

   On Linux, you might set JAVA_HOME as follows.

   export JAVA_HOME=/path/to/jdk

6. Edit Tomcat's catalina.sh script to set the JAVA_HOME environment variable to the file system location of the Java Development Kit, and to set the heap and permanent generation size appropriately.

   $ vi /path/to/tomcat/bin/catalina.sh
   $ grep ^JAVA_HOME /path/to/tomcat/bin/catalina.sh
   JAVA_HOME=/path/to/jdk
   $ grep ^CATALINA /path/to/tomcat/bin/catalina.sh
   CATALINA_OPTS="-Xmx1024m -XX:MaxPermSize=256m"

7. Start Tomcat.

   $ /path/to/tomcat/bin/startup.sh

   It might take Tomcat several seconds to start. When Tomcat has successfully started, you should see an informational message indicating how long startup took in the /path/to/tomcat/logs/catalina.out log file:

   INFO: Server startup in 4655 ms

8. Browse to Tomcat's home page, such as http://openam.example.com:8080.

   

   Apache Tomcat is going to serve the OpenAM web application. Make sure you have successfully gotten to this point before you proceed.

OpenAM is a web application that you deploy into Apache Tomcat and then configure for use.

1. Download the OpenAM .war (web archive) file either from the ForgeRock Enterprise Downloads page, or from the project nightly Builds page.

   Enterprise downloads are tested, stable releases.

   Nightly builds include the very latest features, but are not thoroughly tested. Some functionality might not be finished.

2. Deploy the .war file in Tomcat as openam.war.

   $ mv ~/Downloads/openam*.war /path/to/tomcat/webapps/openam.war

   Tomcat deploys OpenAM under the /path/to/tomcat/webapps/openam/ directory, and you can access the web application in a browser at http://openam.example.com:8080/openam/.

3. Browse to OpenAM where it is deployed in Tomcat, for example http://openam.example.com:8080/openam/, to configure the application.

   

4. On the OpenAM home page, click the link to Create Default Configuration, set the Default User [amAdmin] password to password and the Default Policy Agent [UrlAccessAgent] password to secret12, and then click Create Configuration to configure OpenAM.

   

   If you were configuring OpenAM for real-world use, you would not use either of those passwords, but this is only to get started with OpenAM. The amadmin user is the OpenAM administrator, who is like a super user in that amadmin has full control over the OpenAM configuration.

   The UrlAccessAgent is not used in this guide.

5. When you see the Configuration Complete! dialog, click the Proceed to Login link, and then log in as amadmin with password password.

   After login, OpenAM should direct you to the console at http://openam.example.com:8080/openam/console and then to the common tasks page.

   

   In your home directory, you find that OpenAM has stored its configuration, including the embedded OpenDJ directory server, in a folder named after the server instance, ~/openam/. It has also added a hidden folder, ~/.openamcfg/, with a file used by OpenAM when it starts up. If you ruin your configuration of OpenAM somehow, the quickest way to start over is to stop Tomcat, delete these two folders, and configure OpenAM again.

   OpenAM core server and OpenAM Console is now configured. Make sure you have successfully logged in to OpenAM Console before you proceed.

OpenAM authenticates users and then makes authorization decisions. The authorization decisions are based on access policies that indicate who can do what, when, and under what conditions. Follow these steps to create a policy that allows all authenticated users to perform an HTTP GET (for example, to browse) the Apache HTTP home page that you set up earlier.

1. In OpenAM Console, click the Access Control tab, then in the Realms table click the link to / (Top Level Realm).

   OpenAM allows you to organize identities, policies, and policy agent profiles into realms as described in the Administration Guide chapter, Configuring Realms in the Administration Guide. For now, use the default top level realm.

2. In the Console page for the top level realm, click the Policies tab, and then click New Policy.

3. Give your new policy the name Authenticated users can get Apache HTTP home page.

4. In the Rules table, click New, select URL Policy Agent (with resource name), click Next, and then create a rule for resource http://www.example.com:8000/ that allows HTTP GET, and then click Finish to save your work.

   

   OpenAM applies this rule to subjects that you specify next.

5. In the Subjects table, click New, select Authenticated Users and click Next, then name your rule All Authenticated Users, and click Finish to save your work.

   

   Your policy now specifies who (subject) can perform what actions on what resources (rule). You can ignore Conditions and Response Providers for now.

6. On the Edit Policy page, click OK to save your policy.

   Next you must create a web policy agent profile before installing the agent in Apache HTTP Server to enforce your new policy.

OpenAM stores profile information about policy agents centrally by default. You can then manage the policy agent profile through OpenAM Console. The policy agent can retrieve its configuration from its OpenAM profile at installation time and when it starts up, and OpenAM can notify the policy agent of changes to its configuration. Following these steps before installing the policy agent itself.

1. In OpenAM Console, browse to Access Control > / (Top Level Realm) > Agents > Web, and then click New in the Agents table.

2. In the page to configure your new web policy agent, set the following values.

   Name

   WebAgent

   Password

   password

   Configuration

   Keep the default, Centralized

   Server URL

   http://openam.example.com:8080/openam

   Agent URL

   http://www.example.com:8000

   8000 is the port number you set previously for Apache HTTP Server.

   

3. Click Create to save the new web policy agent profile in OpenAM.

   Next you must install a policy agent in Apache HTTP Server to enforce your new policy.

OpenAM policy agents enforce policies defined in OpenAM. The agent's job is to make sure that users have the right to access resources they request. And yet the agent does not make the policy decisions. Instead, the agent calls on OpenAM for policy decisions, using the information presented by the user (or the user's client application), such as the single sign on token in the HTTP cookie that OpenAM uses to keep track of user sessions. In essence the agent is a gatekeeper for OpenAM.

The agent runs inside of Apache HTTP Server as a library that the server loads at startup time. When a request comes in, the agent redirects users to OpenAM for authentication and calls on OpenAM for policy decisions as necessary.

1. Download the OpenAM policy agent for your version of Apache HTTP Server either from the ForgeRock Enterprise Downloads page, or from the project nightly Builds page.

2. Create a password file that the agent installer reads when first connecting to OpenAM to read its profile.

   The password file should be read-only by the user who installs the policy agent.

   $ echo password > /tmp/pwd.txt
   $ chmod 400 /tmp/pwd.txt

   The password is stored encrypted after installation.

3. Make sure OpenAM is running.

   You can check for example by logging into OpenAM Console.

4. Stop Apache HTTP Server while you install the policy agent.

   $ /path/to/apache/bin/apachectl stop

5. Extract the download.

   $ cd /path/to
   $ unzip ~/Downloads/apache_v22_Linux_agent*.zip

6. Install the web policy agent in Apache HTTP Server, making sure that you provide the correct information to the installer as shown in the following example.

   $ cd /path/to/web_agents/apache22_agent/bin
   $ ./agentadmin --install
   ...
   
   -----------------------------------------------
   SUMMARY OF YOUR RESPONSES
   -----------------------------------------------
   Apache Server Config Directory : /path/to/apache/conf
   OpenAM server URL : http://openam.example.com:8080/openam
   Agent URL : http://www.example.com:8000
   Agent Profile name : WebAgent
   Agent Profile Password file name : /tmp/pwd.txt
   
   ...

7. Start Apache HTTP Server, and check that the web policy agent seems to be correctly configured.

   $ /path/to/apache/bin/apachectl -k start
   $ tail /path/to/apache/logs/error_log
   ...[notice] Apache/2.2.25 (Unix) Web Policy Agent/3.0 configured -- resuming
    normal operations

   Assuming everything up to now has worked correctly, you can now try your installation to see OpenAM in action.