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.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.conf
   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

   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/agent.conf

   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

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. (Optional) 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.

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. (Optional) 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.

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. Protect the password file you will create as appropriate.

2. Create a text file containing only the password.

   C:\>notepad C:\Windows\Temp\pwd.txt

1. Log on as a user with Administrator privileges.

2. Change to the directory where you unpacked the agent download.

   C:\>cd web_agents\iis6_agent\bin

3. Create a configuration file using the IIS6CreateConfig.vbs script.

   Note

   The Web Site Identifier is the value of id, not the site name.

   C:\web_agents\iis6_agent\bin>cscript IIS6CreateConfig.vbs config.txt
   ...
   Enter the Agent Resource File Name [IIS6Resource.en] :
   
   Enter the Agent URL (Example: http://agent.example.com:80) :
   http://windows2003.example.com:80
   
   Displaying the list of Web Sites and its corresponding Identifiers
   Site Name (Site Id)
   Default Web Site (1)
   
   Web Site Identifier :
   1
   ...
   Enter the URL where the OpenAM server is running...:
   http://openam.example.com:8080/openam
   
   Please enter the Agent Profile name :
   IIS 6 Web Agent
   
   Enter the Agent profile password file :
   C:\Windows\Temp\pwd.txt
   
   -----------------------------------------------------
   Agent Configuration file created : config.txt
   -----------------------------------------------------

1. Log on as a user with Administrator privileges.

2. Make sure OpenAM is running.

3. Run IIS6Admin.vbs to install the agent.

   C:\web_agents\iis6_agent\bin>cscript IIS6Admin.vbs -config config.txt
   ...
   Enter the Agent Resource File Name [IIS6Resource.en] :
   
   Creating the Agent Config Directory
   Creating the  and
    agent.conf File
   Updating the Windows Product Registry
   Loading the IIS 6.0 Agent
   Completed Configuring the IIS 6.0 Agent

4. Restart IIS 6.

   C:\web_agents\iis6_agent\bin>iisreset
   
   Attempting stop...
   Internet services successfully stopped
   Attempting start...
   Internet services successfully restarted

   Note

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

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

   Each agent instance that you install on the system has its own configuration and logs directory. The agent protecting the Default Web Site (1) shown in the examples above has configuration and logs located under the directory web_agents\iis6_agent\Identifier_1. The number in the path to the agent configuration reflects the IIS site ID, unlike the other agents for which the number in the path is a counter. The number in the path therefore remains the same when you uninstall and then reinstall an agent to protect the same site.

   config\

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

   config\agent.conf

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

   audit\

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

   debug\

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

6. 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.

7. If the web policy agent performs naming URL validation, which you can configure by setting the com.forgerock.agents.ext.url.validation.level property in config\OpenSSOAgentBootstrap.properties, then make sure the IUSR_MachineName user has read-write access to C:\Windows\Temp\ before you start IIS.

8. (Optional) 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.

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. Protect the password file you will create as appropriate.

2. Create a text file containing only the password.

   C:\>notepad C:\Windows\Temp\pwd.txt

1. Log on as a user with Administrator privileges.

2. Change to the directory where you unpacked the agent download.

   C:\>cd web_agents\iis7_agent\bin

3. Create a configuration file using the IIS7CreateConfig.vbs script.

   Note

   The Web Site Identifier is the value of id, not the site name.

   C:\web_agents\iis7_agent\bin>cscript IIS7CreateConfig.vbs config.txt
   ...
   Enter the Agent Resource File Name [IIS7Resource.en] :
   
   Enter the Agent URL (Example: http://agent.example.com:80) :
   http://windows7.example.com:80
   
   Displaying the list of Web Sites and its corresponding Identifiers (id)
   
   SITE "Default Web Site" (id:1,bindings:http/*:80:,state:Started)
   
   Web Site Identifier :
   1
   ...
   Enter the URL where the OpenAM server is running...:
   http://openam.example.com:8080/openam
   
   Please enter the Agent Profile name :
   IIS 7 Web Agent
   
   Enter the Agent profile password file :
   C:\Windows\Temp\pwd.txt
   
   -----------------------------------------------------
   Agent Configuration file created : config.txt
   -----------------------------------------------------

1. Log on as a user with Administrator privileges.

2. Make sure OpenAM is running.

3. Run IIS7Admin.vbs to install the agent.

   C:\web_agents\iis7_agent\bin>cscript IIS7Admin.vbs -config config.txt
   ...
   Enter the Agent Resource File Name [IIS7Resource.en] :
   
   Creating the Agent Config Directory
   Creating the  and
    agent.conf File
   Updating the Windows Product Registry
   Installing policy web agent module in IIS (status: 0)
   Adding policy web agent module to "Default Web Site" (status: 0)
   Completed Configuring the IIS 7.0 Agent

4. Make sure the authentication method for IIS 7 is set to anonymous.

5. Restart IIS 7.

   C:\web_agents\iis7_agent\bin>iisreset
   
   Attempting stop...
   Internet services successfully stopped
   Attempting start...
   Internet services successfully restarted

   Note

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

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

   Each agent instance that you install on the system has its own configuration and logs directory. The agent protecting the Default Web Site (id: 1) shown in the examples above has configuration and logs located under the directory web_agents\iis7_agent\Identifier_1. The number in the path to the agent configuration reflects the IIS site ID, unlike the other agents for which the number in the path is a counter. The number in the path therefore remains the same when you uninstall and then reinstall an agent to protect the same site.

   config\

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

   config\agent.conf

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

   audit\

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

   debug\

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

7. 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.

8. (Optional) 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.

Follow these steps.

1. Generate and store an encryption key.

   1. Generate the key using com.sun.identity.common.DESGenKey using the .jars where you deployed OpenAM, as in the following example.

      $ cd /path/to/tomcat/webapps/openam/WEB-INF/lib
      $ java -cp openam-core-13.jar:openam-shared-13.jar
       com.sun.identity.common.DESGenKey
      Key ==> sxVoaDRAN0o=

   2. Store the key in the agent configuration on the property in the OpenAM console under Access Control > realm-name > Agents > Web > agent-name > Advanced > Microsoft IIS Server > Replay Password Key (property name: com.sun.identity.agents.config.replaypasswd.key), and then Save your work.

   3. Store the key in the server configuration in the OpenAM console under Configuration > Servers and Sites > server-name > Advanced > Add... to add the property com.sun.am.replaypasswd.key with the key you generated as the value, and then Save your work.

2. In the OpenAM console under Access Control > realm-name > Authentication > All Core Settings... > Authentication Post Processing Classes, add the class com.sun.identity.authentication.spi.ReplayPasswd, and then Save your work.

3. If you require Windows logon, or you need to use basic authentication with SharePoint or OWA, then you must configure Active Directory as a user date store, and you must configure the IIS 7 policy agent profile User ID Parameter and User ID Parameter Type so that the policy agent requests OpenAM to provide the appropriate account information from Active Directory in its policy response.

   Skip this step if you do not use SharePoint or OWA and no Windows logon is required.

   Make sure OpenAM data store is configured to use Active Directory as the user data store.

   In the OpenAM console under Access Control > realm-name > Agents > Web > agent-name > OpenAM Services > Policy Client Service, set User ID Parameter and User ID Parameter Type, and then Save your work. For example if the real username for Windows domain logon in Active Directory is stored on the samaccountname attribute, then set the User ID Parameter to samaccountname, and the User ID Parameter Type to LDAP.

   Setting the User ID Parameter Type to LDAP causes the policy agent to request that OpenAM get the value of the User ID Parameter attribute from the data store, in this case Active Directory. Given that information, the policy agent can set the HTTP headers remote_user, auth_user, or logon_user and user_password with Active Directory attribute values suitable for Windows logon, setting the remote user, and so forth.

4. To set the encrypted password in the AUTH_PASSWORD header, in the OpenAM console under Access Control > realm-name > Agents > Web > agent-name > Advanced > Custom Properties, add com.sun.identity.agents.config.iis.password.header=true.

5. To have the agent perform Windows logon (for user token impersonation), in the OpenAM console under Access Control > realm-name > Agents > Web > agent-name > Advanced > Custom Properties, add com.sun.identity.agents.config.iis.logonuser=true.

6. In the OpenAM console under Access Control > realm-name > Agents > Web > agent-name > Advanced > Microsoft IIS Server, set Authentication Type to basic, and then Save your work.

7. To use the agent with SharePoint or Microsoft Office, configure OpenAM to support the iPlanetDirectoryPro as a persistent cookie.

   In the OpenAM console under Access Control > realm-name > Authentication > All Core Settings... > Persistent Cookie Mode, select Enabled, and then Save your work.

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 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.conf
   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/agent.conf

   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.

1. Make sure OpenAM is installed and running.

2. Contact OpenAM from the system running the policy agent.

3. Install the Varnish HTTP Accelerator.

To create a new web agent profile, you need a name and password, and the URLs to OpenAM and the application to protect. 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.

   

   Use the following information to help you with the form.

   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.

3. After creating the agent profile, you can click the link to the new profile to adjust and export the configuration.

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. Go to Obtaining OpenAM Software to determine which version of the agent to download and download the agent.

2. Verify the checksum of the file you download against the checksum posted on the download page.

3. Unzip the file in the directory where you plan to install the policy agent. The agent you install stores its configuration and logs under this directory.

1. Stop Varnish.

   $ sudo service varnish stop

2. Make sure OpenAM is running.

3. Run ./agentadmin to install the agent.

   $ cd /path/to/web_agents/varnish/bin/
   $ ./agentadmin

   Note

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

4. Accept the ForgeRock Web Policy Agent License. Select Configure Varnish Web Policy Agent instance from the subsequent window.

5. Click on Configure Varnish Web Policy Agent instance and enter the following information for each consecutive screen.

   Press F3 to move to the next field, or F2 to return to the previous field to make a correction. Be careful as you make your entires, backspace will erase the entire entry, not just the last character.

   • URL where the OpenAM server runs

     Enter URL where the OpenAM server is running:
        http://openam.example.com:8080/openam

   • Agent URL that protects the web container

     Enter URL where Agent is protecting the Web Container:
        http://www.website.example.com:80

   • Profile ID and password

     Enter the Agent profile attributes in the OpenAM server:
        Profile ID: webagent
        Password: cangetin

   • Path to Varnish modules directory

     Enter the path to Varnish modules directory    
        /usr/lib/varnish/vmods

   Once you have configured your agent, you will get a page displaying the agent configuration results. Verify the information. Click F4 when you are done.

   Agent configuration results:
    OpenAM URL: http://openam.example.com:8080/openam
     Agent URL: http://website.example.com
       Profile: webagent
    WebServer configuration:
     /opt/webagent/web_agents/varnish/bin/instances/agent_1/config/am.vcl

6. Encrypt the password if you want additional security.

   Note

   The new agent appears as agent_1. You can return to this screen at any time by running /path/to/web_agents/varnish/bin/agentadmin to remove it.

7. Exit the screen.

8. 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 /path/to/web_agents/varnish/instances/agent_1/.

   config/OpenAMAgentBootstrap.properties

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

   config/OpenAMAgentConfiguration.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.

9. If your policy agent configuration is not in the top-level realm (/), then you must edit config/OpenAMAgentBootstrap.properties 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.

10. Setup the backend by updating the following lines in the VLC script. Make sure port and host are set correctly.

    $ vi /path/to/web_agents/varnish/instances/agent_1/config/am.vcl
     import am;
     backend default {
     .host = "127.0.0.1";
     .port = "8080";
     }

11. Start Varnish with the following command. It will also load the VLC script.

    varnishd -u root -F -T localhost:8080 -f
      /path/to/web_agents/varnish/instances/agent_1/config/am.vcl -a :80 -s malloc,50M

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

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

   $ tail /path/to/web_agents/varnish/instances/agent_1/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: Revision: ...
   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. (Optional) 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.