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

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

Alternatively, if you already have a DNS set up, you can use that instead of 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 that is supported by AM's web policy agents. Apache HTTP Server might already be installed on your system, but since you are installing software for the sole purpose of getting started with AM, install the web server separately instead of modifying any existing installations.

Full installation instructions are available online.

1. Verify the correct tools are installed to build Apache HTTP Server 2.2 from source.

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

   For Red Hat and CentOS distributions:

   # yum groupinstall 'Development Tools'

   For Ubuntu distributions:

   $ sudo apt-get install build-essential checkinstall

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

   The AM 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 to install the Web server 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 the installation to ensure Apache HTTP Server is working.

   1. Make sure that your system's firewall does not block the port that Apache HTTP Server uses.

      See the documentation for your version of your system regarding how to allow traffic through the firewall on a specific port. A variety of firewalls are in use on Linux systems. The one in use depends on your specific distribution.

   2. Start the web server.

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

   3. Point your browser to following URL: http://www.example.com:8000.

      

      This is the page to protect with AM. Do not proceed with the next steps unless this page appears.

AM runs as a Java web application inside an application container. Apache Tomcat is an 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 JDK release installed.

   One way of checking the version of the JDK 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.

   "Java Requirements" in the Release Notes indicates what JDK versions are supported. Supported JDK versions also work for 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, set JAVA_HOME as follows.

   export JAVA_HOME=/path/to/jdk

6. Create a Tomcat setenv.sh (Unix/Linux) or setenv.bat (Windows) 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 or metaspace size appropriately.

   If you are using JDK 7:

   export JAVA_HOME="/path/to/usr/jdk"
   export CATALINA_OPTS="$CATALINA_OPTS -Xmx2g -XX:MaxPermSize=256m"

   If you are using JDK 8:

   export JAVA_HOME="/path/to/usr/jdk"
   export CATALINA_OPTS="$CATALINA_OPTS -Xmx2g -XX:MaxMetaspaceSize=256m"

7. Make sure that your system's firewall does not block the port that Apache Tomcat uses.

   See the Apache documentation for instructions for allowing traffic through the firewall on a specific port for the version of Tomcat on your system. A variety of firewalls are in use on Linux systems. The version your system uses depends on your specific distribution.

8. Start Tomcat.

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

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

   INFO: Server startup in 4655 ms

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

   

   Tomcat will serve the AM web application. Make sure you have successfully gotten to this point before you proceed.

Deploy AM into Tomcat and then configure it for use.

1. Download the AM .war file by visiting the ForgeRock BackStage website.

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

   $ mv ~/Downloads/OpenAM-14.0.0.war /path/to/tomcat/webapps/openam.war

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

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

4. On the AM home page, click Create Default Configuration.

   

5. Review the software license agreement. If you agree to the license, click "I accept the license agreement", and then click Continue.

   

6. Set the Default User [amAdmin] password to changeit and the Default Policy Agent [UrlAccessAgent] password to secret12, and then click Create Configuration to configure AM.

   

   Note

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

   The UrlAccessAgent is not used in this guide.

7. Click the Proceed to Login link, then log in as amadmin with the password specified in the previous step, changeit.

   After login, AM should direct you to the Realms page.

   

   AM stores its configuration, including the embedded DS directory server in the folder named ~/openam/ in your home directory. The folder shares the same name as your server instance. It also has a hidden folder, ~/.openamcfg/, with a file used by AM when it starts up. If you ruin your configuration of AM somehow, the quickest way to start over is to stop Tomcat, delete these two folders, and configure AM again.

   AM core server and The AM console are now configured. Make sure you have successfully logged in to the AM console before you proceed.

AM authenticates users and then makes authorization decisions based on access policies that indicate user entitlements. 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 the AM console, select the Top Level Realm on the Realms page.

   AM allows you to organize identities, policies, and policy agent profiles into realms as described in "Setting Up Realms" in the Setup and Maintenance Guide. For now, use the default Top Level Realm.

2. On the Realm Overview page, navigate to Authorization > Policy Sets > Default Policy Set > Add a Policy.

   

   For more information on the relationship between realms, policy sets, and policies, see "Resource Types, Policy Sets, and Policies" in the Authorization Guide.

3. On the New Policy page, enter the following data:

   1. In the Name field, give your new policy the name Authenticated users can get Apache HTTP home page.

   2. On the Resource Type drop-down list, select URL.

   3. On the Resources drop-down list, select the URL pattern for your policy. In this example, select *://*:*/*, then enter the resource URL: http://www.example.com:8000/*, and then click Add.

      

   4. Click Create to save your settings.

      

4. On your policy page, select the Actions tab, and then enter the following information:

   1. On the Add an action drop-down list, select GET.

   2. On the Add an action drop-down list, select POST.

   3. Save your changes.

      

5. On your policy page, navigate to Subjects and enter the following data:

   1. On the All of drop-down list, review the list and select All of....

   2. On the Type section, click the Edit icon. On the Type drop-down list, select Authenticated Users, and then click the checkmark.

   3. Save your changes.

      

6. Review your configuration. To make changes to the configuration, click the relevant tab and amend the configuration.

AM stores profile information about policy agents centrally by default. You can manage the policy agent profile through The AM console. The policy agent retrieves its configuration from its AM profile at installation and start up, and AM notifies the policy agent of changes to its configuration. Follow these steps before installing the policy agent itself.

1. In the AM console, navigate to Realms > Realm Name > Applications > Agents > Web, and select 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 AM.

By default, AM installer sets the cookie domain based on the fully-qualified hostname on the server on which it installs AM. During your installation, it sets the cookie domain to .openam.example.com.

To allow the agent, which runs on www.example.com, to accept AM's iPlanetDirectoryPro cookie, you must change the AM cookie domain from .openam.example.com to .example.com.

1. In the AM console, navigate to Configure > Global Services > Platform > Cookie Domain.

2. In the Cookie Domain field, change the domain to .example.com.

3. Click Save Changes to apply your changes.

Policy agents enforce policies defined in AM. While the policy agent's job is to verify that uses have the appropriate privileges to the resources they request, the policy agents do not make policy decisions. They call on AM to make policy decisions using information presented by the user (or the user's client application), such as the SSO token in the HTTP cookie, which AM uses to manage user sessions. A policy agent is, in essence, a gatekeeper for AM.

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

1. Download the AM policy agent for your version of Apache HTTP Server from the ForgeRock BackStage webite.

2. Create a password file, for example $HOME/.pwd.txt, that the agent installer reads when first connecting to AM to read its profile. The file should only contain the password string, on a single line.

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

   $ chmod 400 $HOME/.pwd.txt

   The password is stored encrypted after installation.

3. Make sure AM is running.

   You can verify this by logging in to the AM 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-64-Agent-${webAgentsDocTargetVersion}.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.

   When you run the command, you will be prompted to read and accept the software license agreement for the agent installation. You can suppress the license agreement prompt by including the --acceptLicence parameter. The inclusion of the option indicates that you have read and accepted the terms stated in the license. To view the license agreement, open <server-root>/legal-notices/license.txt.

   $ cd /path/to/web_agents/apache22_agent/bin
   $ ./agentadmin --install --acceptLicense
   ...
   
   -----------------------------------------------
   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 : $HOME/.pwd.txt
   
   ...

7. Start Apache HTTP Server, and verify that the web policy agent is configured correctly.

   $ /path/to/apache/bin/apachectl -k start
   $ tail /path/to/apache/logs/error_log
   ...[notice] Apache/2.2.25 (Unix) OpenAM WPA/${webAgentsDocTargetVersion} configured -- resuming
    normal operations

   You can now try your installation to see AM in action.