Chapter 7. Installing the Varnish Policy Agent

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.

   
   [D]

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