2.2. Installing Apache 2.2 Web Policy Agent

Complete the following procedures to install the policy agent.

Procedure 2.1. To Create the Apache 2.2 Web Agent Profile

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.

Procedure 2.2. To Create the Password File

  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

Procedure 2.3. To Install the Policy Agent into Apache 2.2

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

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

  2. Make sure OpenAM is running.

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

    $ cd /path/to/web_agents/apache22_agent/bin/
$ ./agentadmin --install
...
-----------------------------------------------
SUMMARY OF YOUR RESPONSES
-----------------------------------------------
Apache Server Config Directory : /path/to/apache22/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/apache22_agent/Agent_001/config/
 
Agent Configuration Tag file location
/path/to/web_agents/apache22_agent/Agent_001/config/
 
Agent Audit directory location:
/path/to/web_agents/apache22_agent/Agent_001/logs/audit
Agent Debug directory location:
/path/to/web_agents/apache22_agent/Agent_001/logs/debug


Install log file location:
/path/to/web_agents/apache22_agent/installer-logs/audit/install.log
...

    Upon successful completion, the installer has added the agent as a module to the Apache 2.2 configuration, and also set up configuration and log directories for the agent.

    [Note] Note

    If the agent is in a different domain than the server, refer to 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/apache22_agent/Agent_001/.

    config/

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

    config/

    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/ to identify 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.2 server where you installed the agent.

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

Procedure 2.4. To Check the Policy Agent Installation

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

    $ tail -n 2 /path/to/apache22/logs/error_log
[Sat Sep 03 13:28:16 2011] [notice] Policy web agent shared memory conf...
[Sat Sep 03 13:28:16 2011] [notice] Apache/2.2.19 (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/apache22_agent/Agent_001/logs/debug/amAgent
2011-09-03 13:28:16.971    -1 32686:9daae60 all: ==============...=====
2011-09-03 13:28:16.972    -1 32686:9daae60 all: Version: ...
2011-09-03 13:28:16.972    -1 32686:9daae60 all: 
2011-09-03 13:28:16.972    -1 32686:9daae60 all: Build Date: ...
2011-09-03 13:28:16.972    -1 32686:9daae60 all: Build Machine: ..forgerock.com
2011-09-03 13:28:16.972    -1 32686:9daae60 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.