Chapter 3. Installing the Apache 2.4 Policy Agent

Regardless of whether you store configurations centrally in OpenAM or locally with your agents, the agent requires a profile so that it can connect to and communicate with OpenAM.

1. In the OpenAM console, browse to Access Control > Realm Name> Agents > Web, and then click the New... button in the Agent table.

2. Complete the web form using the following hints.

   Name

   The name for the agent profile used when you install the agent

   Password

   Password the agent uses to authenticate to OpenAM

   Configuration

   Centralized configurations are stored in the OpenAM configuration store. You can manage the centralized configuration through the OpenAM console. Local configurations are stored in a file alongside the agent.

   Server URL

   The full URL to an OpenAM instance, or if OpenAM is deployed in a site configuration (behind a load balancer) then the site URL

   In centralized configuration mode, the Server URL is used to populate the agent profile for services such as Login, Logout, Naming, and Cross Domain SSO.

   Agent URL

   The web server URL that the agent protects

   In centralized configuration mode, the Agent URL is used to populate the Agent Profile for services such as notifications.

1. Create a text file containing only the password.

   $ echo password > /tmp/pwd.txt

2. Protect the password file you create as appropriate for your operating system.

   $ chmod 400 /tmp/pwd.txt

1. Shut down the Apache 2.4 server where you plan to install the agent.

   $ /path/to/apache24/bin/apachectl -k stop

2. Make sure OpenAM is running.

3. Run ./agentadmin --install to install the agent.

   $ cd /path/to/web_agents/apache24_agent/bin/
   $ ./agentadmin --install
   ...
   -----------------------------------------------
   SUMMARY OF YOUR RESPONSES
   -----------------------------------------------
   Apache Server Config Directory : /path/to/apache24/conf 
   OpenAM server URL : http://openam.example.com:8080/openam 
   Agent URL : http://www.example.com:80
   Agent Profile name : Apache Web Agent 
   Agent Profile Password file name : /tmp/pwd.txt 
   
   ...
   SUMMARY OF AGENT INSTALLATION
   -----------------------------
   Agent instance name: Agent_001
   Agent Bootstrap file location:
   /path/to/web_agents/apache24_agent/Agent_001/config/
    OpenSSOAgentBootstrap.properties
   Agent Configuration Tag file location
   /path/to/web_agents/apache24_agent/Agent_001/config/
    OpenSSOAgentConfiguration.properties
   Agent Audit directory location:
   /path/to/web_agents/apache24_agent/Agent_001/logs/audit
   Agent Debug directory location:
   /path/to/web_agents/apache24_agent/Agent_001/logs/debug
   
   
   Install log file location:
   /path/to/web_agents/apache24_agent/installer-logs/audit/install.log
   ...

   Upon successful completion, the installer has added the agent as a module to the Apache 2.4 configuration, and also set up configuration and log directories for the agent. You can find a backup Apache HTTPD configuration file, http.conf-preAmAgent-*, in the Apache HTTPD configuration directory.

   Note

   If the agent is in a different domain than the OpenAM server, refer to the Administration Guide procedure, Configuring Cross-Domain Single Sign On.

4. Take note of the configuration files and log locations.

   Each agent instance that you install on the system has its own numbered configuration and logs directory. The first agent's configuration and logs are thus located under the directory web_agents/apache24_agent/Agent_001/.

   config/OpenSSOAgentBootstrap.properties

   Used to bootstrap the web policy agent, allowing the agent to connect to OpenAM and download its configuration

   config/OpenSSOAgentConfiguration.properties

   Only used if you configured the web policy agent to use local configuration

   logs/audit/

   Operational audit log directory, only used if remote logging to OpenAM is disabled

   logs/debug/

   Debug directory where the amAgent debug file resides. Useful in troubleshooting policy agent issues.

5. If your policy agent configuration is not in the top-level realm (/), then you must edit config/OpenSSOAgentBootstrap.properties to indentify the sub-realm that has your policy agent configuration. Find com.sun.identity.agents.config.organization.name and change the / to the path to your policy agent profile. This allows the policy agent to properly identify itself to the OpenAM server.

6. Start the Apache 2.4 server where you installed the agent.

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

1. Check the Apache 2.4 error log after you start the server to make sure startup completed successfully.

   $ tail -n 2 /path/to/apache24/logs/error_log
   [Fri Sep 14 12:48:55.765192 2012] [dsame:notice] [pid 18991:tid 3075335872]
    Policy web agent shared memory configuration: notif_shm_size[2099200],
    pdp_shm_size[3213312], max_pid_count[256], max_pdp_count[256]
   [Fri Sep 14 12:48:55.774790 2012] [mpm_event:notice] [pid 18991:tid 3075335872]
    AH00489: Apache/2.4.3 (Unix) DSAME/3.0 configured
    -- resuming normal operations

2. Check the amAgent debug log to verify that no errors occurred on startup.

   $ tail /path/to/web_agents/apache24_agent/Agent_001/logs/debug/amAgent
   2012-09-14 12:48:55.613      -1 18991:85fdd48 all: ==============...=====
   2012-09-14 12:48:55.614      -1 18991:85fdd48 all: Version: ...
   2012-09-14 12:48:55.614      -1 18991:85fdd48 all: Revision: ...
   2012-09-14 12:48:55.614      -1 18991:85fdd48 all: Build Date: ...
   2012-09-14 12:48:55.614      -1 18991:85fdd48 all: Build Machine: ...
   2012-09-14 12:48:55.614      -1 18991:85fdd48 all: ==============...=====

3. If you have a policy configured, you can test your policy agent. For example, try to browse to a resource that your policy agent protects. You should be redirected to OpenAM to authenticate, for example as user demo, password changeit. After you authenticate, OpenAM then redirects you back to the resource you tried to access.