OpenAM Web Policy Agent Installation Guide
Chapter 6. Installing the Oracle iPlanet/Sun Web Server Policy Agent

Procedure 6.1. To Create the Oracle iPlanet Web Server 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 6.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 6.3. To Install the Policy Agent into Oracle iPlanet Web Server

1. Shut down Oracle iPlanet Web Server instance where you plan to install the agent.

2. Make sure OpenAM is running.

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

   $ /path/to/web_agents/sjsws_agent/bin/agentadmin --install
   ...
   -----------------------------------------------
   SUMMARY OF YOUR RESPONSES
   -----------------------------------------------
   Sun Java System Web Server Config Directory :
   /path/to/webserver7/https-www.example.com/config/
   OpenAM server URL : http://openam.example.com:8080/openam
   Agent URL : http://www.example.com:8080
   Agent Profile name : Sun Web Server 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/sjsws_agent/Agent_001/config/
    
   Agent Configuration Tag file location
   /path/to/web_agents/sjsws_agent/Agent_001/config/
    
   Agent Audit directory location:
   /path/to/web_agents/sjsws_agent/Agent_001/logs/audit
   Agent Debug directory location:
   /path/to/web_agents/sjsws_agent/Agent_001/logs/debug
   
   
   Install log file location:
   /path/to/web_agents/sjsws_agent/installer-logs/audit/install.log
   ...

   Upon successful completion, the installer has backed up and updated the Oracle iPlanet Web Server instance configuration, and has also set up configuration and log directories for the agent.

   	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/sjsws_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 log directory. 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. Set up ownership of the log directory. The default is to run as a webservd user instead of root. To post its logs, the agent needs permission to add the files to the directory.

   chown -R webservd:webservd /opt/web_agents/sjsws_agent/Agent_number/logs

7. Restart the Oracle iPlanet Web Server instance where you installed the agent.

8. Check that the agent protects the web site.

   If you have not yet configured any policies to allow access, then you should receive an HTTP 403 Forbidden error. In the above example, when accessing http://www.example.com:8080/, the content of the page returned appears in the browser as follows.

   Forbidden
   
   Your client is not allowed to access the requested object.

   If it appears the protection is inadequate, complete one of the following steps.

   Note

   A potential cause for the protection failing is updates to the server.xml file for the object-file property. A object-file property refers to the obj.conf file created during the web server installation. Multiple servers create their own obj.conf files, which can cause problems with protection. Also, admin changes can update the obj.conf file. For more information, checkout the Syntax and Use of obj.conf.

   • This step removes the obj.conf file if it is not needed.

     Open the server.xml and remove the object-file property. The web server will use the default obj.conf configuration.

     	Note
     	Do not change the original file.

     $ vi /path/to/webserver7/config/server.xml
      <virtual-server>
       <name>virtual.example.com</name>
       <http-listener-name>http-listener-1</http-listenername>
       <host>virtual.example.com</host>
       -  <object-file>virtual.example.com-obj.conf</object-file>
       <document-root>/path/to/webserver7/htdocs</document-root>
       <name>virtual.example.com</name>
      </virtual-server>

   • This step updates the obj.conf file if it is needed.

     Open the server.xml and manually update the object-file property to validate the location of the obj.conf file.

     	Note
     	Do not change the original file.

     $ vi /path/to/webserver7/config/server.xml
      <Object path="*/dummypost/sunpostpreserve*">
      Service type=text/* method=(GET) fn=append_post_data
      </Object>
      <Object path="*/UpdateAgentCacheServlet*">
      Service type=text/* method=(POST) fn=process_notification
      </Object>

9. Save the file and restart the Oracle iPlanet Web Server.