OpenAM Web Policy Agent Installation Guide

Version 4.0.0-SNAPSHOT

Mark Craig

Mike Jang

Vanessa Richie

ForgeRock AS


    33 New Montgomery St.
    Suite 1500
    San FranciscoCA 94105
    USA
    +1 415-523-0772
    www.forgerock.com
   

Legal Notice

Abstract

Guide to installing OpenAM web policy agents. OpenAM provides open source Authentication, Authorization, Entitlement and Federation software.


Table of Contents
Preface
1. About OpenAM Web Policy Agents
2. Installing the Apache 2.2 Policy Agent
3. Installing the Apache 2.4 Policy Agent
4. Installing the Microsoft IIS 6 Policy Agent
5. Installing the Microsoft IIS 7 Policy Agent
6. Installing the Oracle iPlanet/Sun Web Server Policy Agent
7. Configuring Web Policy Agents Behind Load Balancers
8. Troubleshooting
Index

Preface

This guide shows you how to install OpenAM web server policy agents, as well as how to integrate with other access management software. Read the Release Notes before you get started.

1. Who Should Use this Guide

This guide is written for anyone installing OpenAM policy agents to interface with supported web servers application containers.

This guide covers procedures that you theoretically perform only once per version. This guide aims to provide you with at least some idea of what happens behind the scenes when you perform the steps.

You do not need to be an OpenAM wizard to learn something from this guide, though a background in access management and maintaining web application software can help. You do need some background in managing services on your operating systems and in your application servers. You can nevertheless get started with this guide, and then learn more as you go along.

2. Formatting Conventions

Most examples in the documentation are created on GNU/Linux or Mac OS X. Where it is helpful to make a distinction between operating environments, examples for UNIX, GNU/Linux, Mac OS X, and so forth are labeled (UNIX). Mac OS X specific examples can be labeled (Mac OS X). Examples for Microsoft Windows can be labeled (Windows). To avoid repetition, however, file system directory names are often given only in UNIX format as in /path/to/server, even if the text applies to C:\path\to\server as well.

Absolute path names usually begin with the placeholder /path/to/. This path might translate to /opt/, C:\Program Files\, or somewhere else on your system.

Command line, terminal sessions are formatted as follows.

$ echo $JAVA_HOME
/path/to/jdk

Command output is sometimes formatted for narrower, more readable output even though formatting parameters are not shown in the command. In the following example, the query string parameter _prettyPrint=true is omitted.

$ curl https://bjensen:hifalutin@opendj.example.com:8443/users/newuser
{
  "_rev" : "000000005b337348",
  "schemas" : [ "urn:scim:schemas:core:1.0" ],
  "contactInformation" : {
    "telephoneNumber" : "+1 408 555 1212",
    "emailAddress" : "newuser@example.com"
  },
  "_id" : "newuser",
  "name" : {
    "familyName" : "New",
    "givenName" : "User"
  },
  "userName" : "newuser@example.com",
  "displayName" : "New User",
  "meta" : {
    "created" : "2014-06-03T09:58:27Z"
  },
  "manager" : [ {
    "_id" : "kvaughan",
    "displayName" : "Kirsten Vaughan"
  } ]
}
 

Program listings are formatted as follows.

class Test {
    public static void main(String [] args)  {
        System.out.println("This is a program listing.");
    }
}

3. Accessing Documentation Online

ForgeRock core documentation, such as what you are now reading, aims to be technically accurate and complete with respect to the software documented.

Core documentation therefore follows a three-phase review process designed to eliminate errors.

  • Product managers and software architects review project documentation design with respect to the users' software lifecycle needs.

  • Subject matter experts review proposed documentation changes for technical accuracy and completeness with respect to the corresponding software.

  • Quality experts validate implemented documentation changes for technical validity with respect to the software, technical completeness with respect to the scope of the document, and usability for the expected audience.

The review process helps to ensure that documentation published for a ForgeRock release is technically accurate and complete.

Fully reviewed, published core documentation is available at http://docs.forgerock.org/. Use this documentation when working with a ForgeRock Enterprise release.

In-progress documentation can be found at each project site under the Developer Community projects page. Use this documentation when trying a nightly build.

The ForgeRock Community Wikis and provide additional, user-created information. We encourage you to join the community, so that you can update the Wikis, too.

4. Joining the ForgeRock Community

After you sign up to join the ForgeRock community, you can edit the Community Wikis, and also log bugs and feature requests in the issue tracker.

If you have a question regarding a project but cannot find an answer in the project documentation or Wiki, browse to the Developer Community page for the project, where you can find details on joining the project mailing lists, and find links to mailing list archives. You can also suggest updates to documentation through the ForgeRock docs mailing list.

The Community Wikis describe how to check out and build source code. Should you want to contribute a patch, test, or feature, or want to author part of the core documentation, first have a look on the ForgeRock site at how to get involved.

Chapter 1. About OpenAM Web Policy Agents

OpenAM web policy agents provide light touch integration for web applications running on supported web servers. This chapter covers what web policy agents do and how they work.

A policy agent enforces policy for OpenAM. A web policy agent installed in a web server intercepts requests from users trying to access a protected web resource, and denies access until the user has authorization from OpenAM to access the resource.

Note

A single policy agent can work with multiple applications. You therefore install only one policy agent per web server.

Installing more than one policy agent in a web server is not supported.

1.1. How the User, Web Policy Agent, & OpenAM Interact

Imagine that a user attempts to access a protected resource before having authenticated by pointing her browser to a web page. Assume that you have configured OpenAM to protect the web page. Then the web policy agent intercepting her browser's request finds no session token in the request, and so redirects the user's browser to the OpenAM login page for authentication. After the user has successfully authenticated, OpenAM sets a session token in a browser cookie, and redirects her browser back to the page she tried to access initially.

When the user's browser reiterates the request, the policy agent again checks that the request has a session token, finds a session token this time, and validates the session token with OpenAM. Given the valid session token, the policy agent gets a policy decision from OpenAM concerning whether the user can access the page. If OpenAM's Policy Service determines that the user is allowed to access the page, OpenAM responds to the policy agent that access should be granted. The web policy agent then permits the web page to be returned to the user's browser.

The following diagram shows how the pieces fit together when a web client accesses a web page protected by a policy agent. This diagram is simplified to show only the essential principals rather than to describe every possible case.

Diagram of web policy agent use

A web policy agent is a library installed in the web server and configured to be called by the web server when a client requests access to a protected resource in a web site.

  1. The web client requests access to a protected resource.

  2. The web server runs the request through the policy agent that protects the resource according to OpenAM policy. The policy agent acts to enforce policy, whereas the policy configuration and decisions are handled by OpenAM.

  3. The policy agent communicates with OpenAM to get the policy decision to enforce.

  4. For a resource to which OpenAM approves access, the policy agent allows access.

  5. The web server returns the requested access to the web client.

1.2. How Web Policy Agents are Configured

You install web policy agents in the web servers holding web resources that you want to protect. By default, the web policy agent has only enough configuration at installation time to connect to OpenAM in order to get the rest of its configuration from the OpenAM configuration store. With nearly all configuration stored centrally, you can manage policy agents centrally from the OpenAM console.

You can opt to store the agent configuration locally if necessary. If you store the configuration locally, then avoid issues with the configuration by making sure you provide valid values for configuration properties ending in the following.

  • .cookie.name

  • .fqdn.default

  • .agenturi.prefix

  • .naming.url

  • .login.url

  • .instance.name

  • .username

  • .password

  • .connection_timeout

  • .policy_clock_skew

You configure web policy agents per realm. Thus to access centralized configuration, you select Access Control > Realm Name > Agents > Web > Agent Name. Web policy agent configuration is distinct from policy configuration. The only policy-like configuration that you apply to web policy agents is indicating which URLs in the web server can be ignored (not enforced URLs) and which client IP address are exempt from policy enforcement (not enforced IPs).

For each aspect of web policy agent configuration, you can configure the policy agent through the OpenAM console during testing, and then export the resulting configuration in order to script configuration in your production environment.

Chapter 2. Installing the Apache 2.2 Policy Agent

This chapter covers installation of the policy agent for Apache HTTP Server 2.2.x.

2.1. Before You Install

Make sure OpenAM is installed, running, that you can contact OpenAM from the system running the policy agent. Next, create a profile for your policy agent as described in the Administration Guide section on Creating Agent Profiles. To protect resources with the agent also create at least one policy as described in the section on Configuring Policies. Consider creating a simple policy, such as a policy that allows only authenticated users to access your resources, in order to test your policy agent after installation.

You must install Apache HTTP Server before you install the policy agent, and you must stop the server during installation.

You must install a supported version of the Java runtime environment. Please review the OpenAM Release Notes for the currently supported version of Java, and set the JAVA_HOME environment variable accordingly. The policy agent installer requires Java.

$ echo $JAVA_HOME
/path/to/java
      

Go to Obtaining OpenAM Software to determine which version of the agent to download and download the agent. Also verify the checksum of the file you download against the checksum posted on the download page.

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

When you unzip the policy agent .zip download, you find the following directories under the web_agents/apache22_agent directory.

bin

The installation and configuration program agentadmin and a password hashing tool crypt_util.

config

Configuration templates used by the agentadmin command during installation

data

Not used

etc

Configuration templates used during installation

installer-logs

Location for log files written during installation

legal-notices

Contains licensing information including third-party licenses

lib

Shared libraries used by the Java EE policy agent

locale

Property files used by the installation program

README

README file containing platform and install information for the agent

2.2. Installing Apache 2.2 Web Policy Agent

Complete the following procedures to install the policy agent.

Procedure 2.1. To Create the 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 URL to the web agent application, such as http://www.example.com:8080/agentapp

    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.

    When you run the command, you will be prompted to read and accept the software license agreement for the agent installation. You can suppress the license agreement prompt by including the --acceptLicense option on the command line. The inclusion of the option indicates that you have read and accepted the terms stated in the license. To view the license agreement, open <server-root>/legal-notices/license.txt.

    $ cd /path/to/web_agents/apache22_agent/bin/
    $ ./agentadmin --install --acceptLicense
    ...
    -----------------------------------------------
    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/
     OpenSSOAgentBootstrap.properties
    Agent Configuration Tag file location
    /path/to/web_agents/apache22_agent/Agent_001/config/
     OpenSSOAgentConfiguration.properties
    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/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 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.

2.3. Installing Apache 2.2 Web Policy Agent (Windows)

The instructions for installing the Apache 2.2 Web Policy Agent on a Windows system mirror those on the Unix/Linux systems. Run the following procedures.

Procedure 2.5. Before You Begin

First read the pre-install requirements in Before You Install.

  1. Make sure you have a Java runtime environment. Review the OpenAM Release Notesfor the currently supported version of Java, and set the JAVA_HOME environment variable accordingly.

  2. Make sure you have installed Apache HTTP server. Stop the HTTP server prior to installing the Apache 2.2 Web Policy Agent.

  3. Make sure you have an installed and running OpenAM server. The OpenAM server should be installed and running with at least one policy agent profile configured.

  4. Go to Obtaining OpenAM Software to download the agent. Also verify the checksum of the file you download against the checksum posted on the download page. Unzip the file in the directory where you plan to install the web policy agent.

Procedure 2.6. To Create the Apache 2.2 Web Agent Profile
  • Follow the instructions presented in To Create the Apache 2.2 Web Agent Profile.

Procedure 2.7. To Create the Password File
  1. Create a text file containing only the password.

    C:\> echo password > pwd.txt
                
  2. Open the Properties dialog on the password file, click the Read-only box, and then click OK.

Procedure 2.8. To Install the Policy Agent into Apache 2.2
  1. Shut down the Apache 2.2 server where you plan to install the agent.

    C:\> C:\Apache2.2\bin\httpd -k stop
            
  2. Make sure OpenAM is running.

  3. Change to the Web Agent directory.

    C:\> cd web_agents\apache22_agent\bin
            
  4. Install the agent. When prompted for information, enter the inputs appropriate for your deployment.

    C:\path\to\web_agents\apache22_agent\bin> agentadmin.bat --install
    
    Please read the following License Agreement carefully:
    
    [Press <Enter> to continue...] or [Enter n To Finish] n
    
    Do you completely agree with all the terms and conditions of this License
    Agreement (yes/no): [no]: yes
    
    
    ...
    
    -----------------------------------------------
    SUMMARY OF YOUR RESPONSES
    -----------------------------------------------
    Apache Server Config Directory : C:\Apache2.2\conf
    OpenAM server URL : http://openam.example.com:8080/openam
    Agent URL : http://ec2-54-194-46-210.eu-west-1.compute.amazonaws.com:8080
    Agent Profile name : winagent
    Agent Profile Password file name : C:\pwd.txt
    
    Verify your settings above and decide from the choices below.
    1. Continue with Installation
    2. Back to the last interaction
    3. Start Over
    4. Exit
    Please make your selection [1]:
    
    Creating directory layout and configuring Agent file for Agent_001
    instance ...DONE.
    
    Reading data from file C:\pwd.txt and encrypting it ...DONE.
    
    Generating audit log file name ...DONE.
    
    Creating tag swapped OpenSSOAgentBootstrap.properties file for instance
    Agent_001 ...DONE.
    
    Creating a backup for file C:\Apache2.2\conf/httpd.conf ...DONE.
    
    Adding Agent parameters to
    C:/web_agents/apache22_agent/Agent_001/config/dsame.conf file ...DONE.
    
    Adding Agent parameters to C:\Apache2.2\conf/httpd.conf file ...DONE.
    
    SUMMARY OF AGENT INSTALLATION
    -----------------------------
    Agent instance name: Agent_001
    Agent Bootstrap file location:
    C:/web_agents/apache22_agent/Agent_001/config/OpenSSOAgentBootstrap.properties
    Agent Configuration Tag file location:
    C:/web_agents/apache22_agent/Agent_001/config/OpenSSOAgentConfiguration.properties
    Agent Audit directory location:
    C:/web_agents/apache22_agent/Agent_001/logs/audit
    Agent Debug directory location:
    C:/web_agents/apache22_agent/Agent_001/logs/debug
    
    
    Install log file location:
    C:/web_agents/apache22_agent/installer-logs/audit/install.log
    
    Thank you for using OpenAM Policy Agent
        
Procedure 2.9. To Check the Policy Agent Installation (Windows)
  1. Check the Apache 2.2 error log after you start the server to make sure startup completed successfully.

    [Mon Jan 27 13:28:15 2014] [notice] Policy web agent shared memory conf...
    [Mon Jan 27 13:28:15 2014] [notice] Apache\2.2.19 (Windows) DSAME\3.0 configured
                    -- resuming normal operations
                
  2. Check the amAgent debug log to verify that no errors occurred on startup.

    2014-01-27 13:28:16.971    -1 1944:9daae60 all: ==============...=====
    2014-01-27 13:28:16.972    -1 1944:9daae60 all: Version: ...
    2014-01-27 13:28:16.972    -1 1944:9daae60 all:
    2014-01-27 13:28:16.972    -1 1944:9daae60 all: Build Date: ...
    2014-01-27 13:28:16.972    -1 1944:9daae60 all: Build Machine: ..example.com
    2014-01-27 13:28:16.972    -1 1944: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.

2.4. Custom Apache 2.2 Web Policy Agent Installation

When running multiple Apache 2.2 servers on the same host, use ./agentadmin --custom-install. If you want to suppress the license agreement prompt, add the --acceptLicense option to the command.

When performing a scripted, silent installation, use ./agentadmin --install --saveResponse response-file to create a response file for scripted installation. Then install silently using ./agentadmin --install --acceptLicense --useResponse response-file.

With ./agentadmin --custom-install, you can opt to create the policy agent profile during installation. The OpenAM administrator must first create an agent administrator user, as described in Delegating Agent Profile Creation, and provide you with the agent administrator user name and password. Before running the ./agentadmin --custom-install command, put the password alone in a read-only file only the user installing can access, as for the agent password. When the agentadmin command prompts you to create the profile during installation, enter true, and then respond to the agentadmin prompts for the agent administrator user name and password file.

2.5. Remove Apache 2.2 Web Policy Agent Software

Shut down the Apache 2.2 server before you uninstall the policy agent.

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

To remove the web policy agent, use ./agentadmin --uninstall.

$ ./agentadmin --uninstall
...
-----------------------------------------------
SUMMARY OF YOUR RESPONSES
-----------------------------------------------
Apache Server Config Directory : /path/to/apache22/conf 

...
Deleting the config directory
/path/to/web_agents/apache22_agent/Agent_001/config
...DONE.

Removing Agent parameters from /path/to/apache22/conf/httpd.conf file
...DONE.


Uninstall log file location:
/path/to/web_agents/apache22_agent/installer-logs/audit/uninstall.log
...
  

Chapter 3. Installing the Apache 2.4 Policy Agent

This chapter covers installation of the policy agent for Apache HTTP Server 2.4.x.

3.1. Before You Install

Make sure OpenAM is installed, running, that you can contact OpenAM from the system running the policy agent. Next, create a profile for your policy agent as described in the Administration Guide section on Creating Agent Profiles. To protect resources with the agent also create at least one policy as described in the section on Configuring Policies. Consider creating a simple policy, such as a policy that allows only authenticated users to access your resources, in order to test your policy agent after installation.

You must install Apache HTTP Server before you install the policy agent, and you must stop the server during installation.

You must install a supported version of the Java runtime environment. Please review the OpenAM Release Notes for the currently supported version of Java, and set the JAVA_HOME environment variable accordingly. The policy agent installer requires Java.

Go to Obtaining OpenAM Software to determine which version of the agent to download and download the agent. Also verify the checksum of the file you download against the checksum posted on the download page.

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

When you unzip the policy agent .zip download, you find the following directories under the web_agents/apache24_agent directory.

bin

The installation and configuration program agentadmin and a password hashing tool crypt_util.

config

Configuration templates used by the agentadmin command during installation

data

Not used

etc

Configuration templates used during installation

installer-logs

Location for log files written during installation

legal-notices

Contains licensing information including third-party licenses

lib

Shared libraries used by the Java EE policy agent

locale

Property files used by the installation program

README

README file containing platform and install information for the agent

3.2. Installing Apache 2.4 Web Policy Agent

Complete the following procedures to install the policy agent.

Procedure 3.1. To Create the 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 URL to the web agent application, such as http://www.example.com:8080/agentapp

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

Procedure 3.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 3.3. To Install the Policy Agent into Apache 2.4
  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.

    When you run the command, you will be prompted to read and accept the software license agreement for the agent installation. You can suppress the license agreement prompt by including the --acceptLicense option on the command line. The inclusion of the option indicates that you have read and accepted the terms stated in the license. To view the license agreement, open <server-root>/legal-notices/license.txt.

    $ cd /path/to/web_agents/apache24_agent/bin/
    $ ./agentadmin --install --acceptLicense
    ...
    -----------------------------------------------
    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
        
Procedure 3.4. To Check the Policy Agent Installation
  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.

3.3. Custom Apache 2.4 Web Policy Agent Installation

When running multiple Apache 2.4 servers on the same host, use ./agentadmin --custom-install. If you want to suppress the license agreement prompt, add the --acceptLicense option to the command.

When performing a scripted, silent installation, use ./agentadmin --install --saveResponse response-file to create a response file for scripted installation. Then install silently using ./agentadmin --install --acceptLicense --useResponse response-file.

With ./agentadmin --custom-install, you can opt to create the policy agent profile during installation. The OpenAM administrator must first create an agent administrator user, as described in Delegating Agent Profile Creation, and provide you with the agent administrator user name and password. Before running the ./agentadmin --custom-install command, put the password alone in a read-only file only the user installing can access, as for the agent password. When the agentadmin command prompts you to create the profile during installation, enter true, and then respond to the agentadmin prompts for the agent administrator user name and password file.

3.4. Remove Apache 2.4 Web Policy Agent Software

Shut down the Apache 2.4 server before you uninstall the policy agent.

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

To remove the web policy agent, use ./agentadmin --uninstall.

$ ./agentadmin --uninstall
...
-----------------------------------------------
SUMMARY OF YOUR RESPONSES
-----------------------------------------------
Apache Server Config Directory : /path/to/apache24/conf 

...
Deleting the config directory
/path/to/web_agents/apache24_agent/Agent_001/config
...DONE.

Removing Agent parameters from /path/to/apache24/conf/httpd.conf file
...DONE.


Uninstall log file location:
/path/to/web_agents/apache24_agent/installer-logs/audit/uninstall.log
...
  

Chapter 4. Installing the Microsoft IIS 6 Policy Agent

This chapter covers installation of the policy agent for Microsoft Internet Information Services 6.

4.1. Before You Install

Make sure OpenAM is installed, running, that you can contact OpenAM from the system running the policy agent. Next, create a profile for your policy agent as described in the Administration Guide section on Creating Agent Profiles. To protect resources with the agent also create at least one policy as described in the section on Configuring Policies. Consider creating a simple policy, such as a policy that allows only authenticated users to access your resources, in order to test your policy agent after installation.

You must install Microsoft IIS 6 before you install the policy agent, and make sure that IIS 6 allows anonymous authentication. Make sure that IIS 6 listens on the URL used during the web policy agent installation, such as http://win2003.example.com:80/. Furthermore, you must reset IIS 6 after installing the policy agent.

Go to Obtaining OpenAM Software to determine which version of the agent to download and download the agent. Also verify the checksum of the file you download against the checksum posted on the download page.

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

When you unpack the policy agent you download, you find the following directories under the web_agents\iis6_agent\ directory.

bin

Contains the configuration creation script, IIS6CreateConfig.vbs; the agent administration and installation script, IIS6Admin.vbs; the certificate management tool certutil.exe; the password hashing tool cryptit.exe; additional .dll and support files.

config

Configuration templates used by the scripts during configuration and installation

4.2. Installing IIS 6 Web Policy Agent

Complete the following procedures to install the policy agent.

Procedure 4.1. To Create the 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 URL to the web agent application, such as http://www.example.com:8080/agentapp

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

Procedure 4.2. To Create the Password File
  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
        
Procedure 4.3. To Configure Policy Agent Installation
  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
    -----------------------------------------------------
        
Procedure 4.4. To Install the Policy Agent into IIS 6
  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 OpenSSOAgentBootstrap.properties and
     OpenSSOAgentConfiguration.properties 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 the 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\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

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

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

4.3. Custom IIS 6 Web Policy Agent Installation

When protecting multiple IIS 6 websites on the same host, use different configuration files for each site.

When preparing a scripted, silent installation, notice that the configuration file generated using IIS6CreateConfig.vbs is a text file containing all of the configuration information in clear text plus the encrypted password retrieved originally from the password file. Encrypt passwords using cryptit.exe.

C:\web_agents\iis6_agent\bin>cryptit.exe pwd-file encryption-key
  

The cryptit.exe command uses its own implementation of the Rivest Cipher 5 (RC5) encryption algorithm.

4.4. Remove IIS 6 Web Policy Agent Software

To remove the web policy agent, log on as a user with Administrator privileges, run cscript IIS6Admin.vbs -unconfig config.txt, and then run iisreset.

Chapter 5. Installing the Microsoft IIS 7 Policy Agent

This chapter covers installation of the policy agent for Microsoft Internet Information Services 7. This policy agent also works with Microsoft IIS 8.

5.1. Before You Install

Make sure OpenAM is installed, running, that you can contact OpenAM from the system running the policy agent. Next, create a profile for your policy agent as described in the Administration Guide section on Creating Agent Profiles. To protect resources with the agent also create at least one policy as described in the section on Configuring Policies. Consider creating a simple policy, such as a policy that allows only authenticated users to access your resources, in order to test your policy agent after installation.

You must install Microsoft IIS 7 before you install the policy agent, and make sure that IIS 7 allows anonymous authentication. Make sure that IIS 7 listens on the URL used during the web policy agent installation, such as http://windows7.example.com:80/. Furthermore, you must reset IIS 7 after installing the policy agent.

In addition, the Microsoft IIS 7 policy agent requires that IIS Application Development features be installed with IIS. Application Development is an optional component of the IIS web server. The component provides infrastructure for developing and hosting web applications.

Go to Obtaining OpenAM Software to determine which version of the agent to download and download the agent. Also verify the checksum of the file you download against the checksum posted on the download page.

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

When you unpack the policy agent you download, you find the following directories under the web_agents\iis7_agent\ directory.

bin

Contains the configuration creation script, IIS7CreateConfig.vbs; the agent administration and installation script, IIS7Admin.vbs; the certificate management tool certutil.exe; the password hashing tool cryptit.exe; additional .dll and support files.

config

Configuration templates used by the scripts during configuration and installation

5.2. Installing IIS 7 Web Policy Agent

Complete the following procedures to install the policy agent.

Procedure 5.1. To Create the 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 URL to the web agent application, such as http://www.example.com:8080/agentapp

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

Procedure 5.2. To Create the Password File
  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
        
Procedure 5.3. To Configure Policy Agent Installation
  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
    -----------------------------------------------------
        
Procedure 5.4. To Install the Policy Agent into IIS 7
  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 OpenSSOAgentBootstrap.properties and
     OpenSSOAgentConfiguration.properties 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 the 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\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

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

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

5.3. Custom IIS 7 Web Policy Agent Installation

When protecting multiple IIS 7 websites on the same host, use different configuration files for each site.

When preparing a scripted, silent installation, notice that the configuration file generated using IIS7CreateConfig.vbs is a text file containing all of the configuration information in clear text plus the encrypted password retrieved originally from the password file. Encrypt passwords using cryptit.exe.

C:\web_agents\iis7_agent\bin>cryptit.exe pwd-file encryption-key
  

5.4. Enable IIS 7 Basic Authentication & Password Replay Support

The IIS 7 web policy agent now supports IIS 7 basic authentication and password replay. You must use the appropriate software versions.

Given the proper configuration and with Active Directory as a user data store for OpenAM, the IIS 7 web policy agent can provide access to the IIS server variables. The instructions for configuring the capability follow in this section, though you should read the section in full, also paying attention to the required workarounds for Microsoft issues.

When configured as described the policy agent requests IIS server variable values from OpenAM, which gets them from Active Directory. The policy agent then sets the values in HTTP headers so that they can be accessed by your application.

The following IIS server variables all take the same value when set: REMOTE_USER, AUTH_USER, and LOGON_USER. The policy agent either sets all three, or does not set any of them.

When you enable Logon and Impersonation in the console (com.sun.identity.agents.config.iis.logonuser=true in the policy agent configuration), the policy agent performs Windows logon and sets the user impersonation token in the IIS session context.

When you enable Show Password in HTTP Header in the console (com.sun.identity.agents.config.iis.password.header=true in the policy agent configuration), the policy agent adds it in the USER_PASSWORD header.

The policy agent does not modify any other IIS server variables related to the authenticated user's session.

The policy agent works best with IIS running in Integrated, not Classic mode. In Classic mode, you cannot share sessions between the policy agent and another .NET application, so Logon and Impersonation are not operative. Furthermore IIS in Classic mode treats all modules as ISAPI extensions, and request processing is affected. It is therefore strongly recommended that you run IIS in Integrated mode.

  • For Microsoft Office integration, you must use Microsoft Office 2007 SP2 or later.

  • For Microsoft SharePoint integration, you must use Microsoft SharePoint Server 2007 SP2 or later.

You must also apply workarounds as described for the following Microsoft issues.

Microsoft Support Issue: 841215

Link: http://support.microsoft.com/kb/841215

Description: Error message when you try to connect to a Windows SharePoint document library: "System error 5 has occurred"

Summary: Enable Basic Authentication on the client computer.

Microsoft Support Issue: 870853

Link: http://support.microsoft.com/kb/870853

Description: Office 2003 and 2007 Office documents open read-only in Internet Explorer

Summary: Add registry keys as described in Microsoft's support document.

Microsoft Support Issue: 928692

Link: http://support.microsoft.com/kb/928692

Description: Error message when you open a Web site by using Basic authentication in Expression Web on a computer that is running Windows Vista: "The folder name is not valid"

Summary: Edit the registry as described in Microsoft's support document.

Microsoft Support Issue: 932118

Link: http://support.microsoft.com/kb/932118

Description: Persistent cookies are not shared between Internet Explorer and Office applications

Summary: Add the web site the list of trusted sites.

Microsoft Support Issue: 943280

Link: http://support.microsoft.com/kb/943280

Description: Prompt for Credentials When Accessing FQDN Sites From a Windows Vista or Windows 7 Computer

Summary: Edit the registry as described in Microsoft's support document.

Microsoft Support Issue: 968851

Link: http://support.microsoft.com/kb/968851

Description: SharePoint Server 2007 Cumulative Update Server Hotfix Package (MOSS server-package): April 30, 2009

Summary: Apply the fix from Microsoft if you use SharePoint.

Microsoft Support Issue: 2123563

Link: http://support.microsoft.com/kb/2123563

Description: You cannot open Office file types directly from a server that supports only Basic authentication over a non-SSL connection

Summary: Enable SSL encryption on the web server.

Procedure 5.5. To Configure IIS 7 Basic Authentication & Password Replay Support

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. The Java command below is broken out into multiple lines for display purposes only.

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

      Windows users should use semi-colons (";"), instead of colons (":") in the commands. The Java command below is broken out into multiple lines for display purposes only.

      C:>cd path\to\tomcat\webapps\openam\WEB-INF\lib
      C:>java -cp forgerock-util-1.3.0.jar;openam-core-12.0.0-SNAPSHOT.jar;openam-shared-12.0.0-SNAPSHOT.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 data 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, browse in the OpenAM console to Access Control > realm-name > Agents > Web > agent-name > Advanced > Microsoft IIS Server, select Show Password in HTTP Header, and then Save your work.

  5. To have the agent perform Windows logon (for user token impersonation), browse in the OpenAM console to Access Control > realm-name > Agents > Web > agent-name > Advanced > Microsoft IIS Server, select Logon and Impersonation, and then Save your work.

  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.

5.5. Remove IIS 7 Web Policy Agent Software

To remove the web policy agent, log on as a user with Administrator privileges, run cscript IIS7Admin.vbs -unconfig config.txt, and then run iisreset.

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

This chapter covers installation of the policy agent for Oracle iPlanet Web Server, formerly known as Sun Web Server.

6.1. Before You Install

Make sure OpenAM is installed, running, that you can contact OpenAM from the system running the policy agent. Next, create a profile for your policy agent as described in the Administration Guide section on Creating Agent Profiles. To protect resources with the agent also create at least one policy as described in the section on Configuring Policies. Consider creating a simple policy, such as a policy that allows only authenticated users to access your resources, in order to test your policy agent after installation.

You must install Apache HTTP Server before you install the policy agent, and you must stop the server during installation.

You must install a supported version of the Java runtime environment. Please review the OpenAM Release Notes for the currently supported version of Java, and set the JAVA_HOME environment variable accordingly. The policy agent installer requires Java.

$ echo $JAVA_HOME
/path/to/java
      

Go to Obtaining OpenAM Software to determine which version of the agent to download and download the agent. Also verify the checksum of the file you download against the checksum posted on the download page.

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

When you unzip the policy agent .zip download, you find the following directories under the web_agents/sjsws_agent directory.

bin

The installation and configuration program agentadmin and a password hashing tool crypt_util.

config

Configuration templates used by the agentadmin command during installation

data

Not used

etc

Configuration templates used during installation

installer-logs

Location for log files written during installation

legal-notices

Contains licensing information including third-party licenses

lib

Shared libraries used by the Java EE policy agent

locale

Property files used by the installation program

README

README file containing platform and install information for the agent

6.2. Installing Oracle iPlanet Web Server Web Policy Agent

Complete the following procedures to install the policy agent.

Procedure 6.1. To Create the 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 URL to the web agent application, such as http://www.example.com:8080/agentapp

    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.

    When you run the command, you will be prompted to read and accept the software license agreement for the agent installation. You can suppress the license agreement prompt by including the --acceptLicense option on the command line. The inclusion of the option indicates that you have read and accepted the terms stated in the license. To view the license agreement, open <server-root>/legal-notices/license.txt.

    $ /path/to/web_agents/sjsws_agent/bin/agentadmin --install --acceptLicense
    ...
    -----------------------------------------------
    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/
     OpenSSOAgentBootstrap.properties
    Agent Configuration Tag file location
    /path/to/web_agents/sjsws_agent/Agent_001/config/
     OpenSSOAgentConfiguration.properties
    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/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 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/OpenSSOAgentBootstrap.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.

  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.

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

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

6.3. Custom Oracle iPlanet Web Policy Agent Installation

For alternative installations, use agentadmin --custom-install. If you want to suppress the license agreement prompt, add the --acceptLicense option to the command.

When performing a scripted, silent installation, use agentadmin --install --saveResponse response-file to create a response file for scripted installation. Then install silently using agentadmin --install --acceptLicense --useResponse response-file.

With ./agentadmin --custom-install, you can opt to create the policy agent profile during installation. The OpenAM administrator must first create an agent administrator user, as described in Delegating Agent Profile Creation, and provide you with the agent administrator user name and password. Before running the ./agentadmin --custom-install command, put the password alone in a read-only file only the user installing can access, as for the agent password. When the agentadmin command prompts you to create the profile during installation, enter true, and then respond to the agentadmin prompts for the agent administrator user name and password file.

6.4. Remove Oracle iPlanet Web Policy Agent Software

Shut down the Oracle iPlanet Web Server before you uninstall the policy agent.

To remove the web policy agent, use agentadmin --uninstall.

Chapter 7. Configuring Web Policy Agents Behind Load Balancers

This chapter addresses the question of configuring policy agents on protected servers that operate behind network load balancers.

7.1. The Role of the Load Balancing Layer

A load balancing layer that stands between clients and protected servers can distribute the client load, and fail client traffic over when a protected server goes offline. In the simplest case, the load balancing layer passes requests from the clients to servers and responses from servers to clients, managing the traffic so the client experience is as smooth as possible.

Figure 7.1. Load Balancing With Same Protocol and Port
Diagram showing matching protocols and port numbers

If your deployment has protocols and port numbers on the load balancer that match those of the protected servers, see Section 7.2, “When Protocols & Port Number Match”.

A load balancing layer can also offload processor-intensive public-key encryption algorithms involved in SSL transactions to a hardware accelerator, reducing the load on the protected servers. The client connects to the load balancer over HTTPS, but the load balancer connects to the servers over HTTP.

Figure 7.2. Load Balancing With SSL Offloading
Diagram showing SSL offloading

If your deployment uses SSL offloading, see Section 7.3, “When Protocols & Port Number Differ”.

7.2. When Protocols & Port Number Match

When the protocol on the load balancer, such as HTTP or HTTPS, matches the protocol on the protected web server, and the port number the load balancer listens on, such as 80 or 443, matches the port number the protected web server listens on, then the main difference between URLs is in the host names. Map the agent host name to the host name for the load balancer.

Procedure 7.1. To Map the Agent Host Name to the Load Balancer Host Name

When protocols and port numbers match, configure fully qualified domain name (FQDN) mapping.

This procedure explains how to do so for a centralized web policy agent profile configured in OpenAM Console. The steps also mention the properties for web agent profiles that rely on local, file-based configurations.

  1. Login to OpenAM Console as an administrative user with rights to modify the policy agent profile.

  2. Browse to Access Control > Realm Name > Agents > Web > Agent Name to open the web agent profile for editing.

  3. In the Global tab page section Fully Qualified Domain Name Checking, make sure FQDN checking is selected (the default).

    The equivalent property setting is com.sun.identity.agents.config.fqdn.check.enable=true.

  4. Set FQDN Default to the fully qualified domain name of the load balancer, such as lb.example.com, rather than the protected server FQDN where the policy agent is installed.

    The equivalent property setting is com.sun.identity.agents.config.fqdn.default=lb.example.com.

  5. Set FQDN Virtual Host Map to map the protected server FQDN to the load balancer FQDN, for example where the key agent.example.com (protected server) has value lb.example.com (load balancer).

    The equivalent property setting is com.sun.identity.agents.config.fqdn.mapping[agent.example.com]=lb.example.com.

  6. Save your work, and then restart the protected server.

7.3. When Protocols & Port Number Differ

When the load balancer protocol and port, such as HTTPS and 443, differ from the protocol on the protected web server, such as HTTP and 80, then you must override these in the policy agent configuration.

Procedure 7.2. To Override Protocol, Host, & Port

Use the Agent Deployment URI Prefix setting to override the agent protocol, host, and port with that of the load balancer.

Important

The web policy agent configuration for SSL offloading has the side effect of preventing FQDN checking and mapping. As a result, URL rewriting and redirection does not work correctly when the policy agent is accessed directly and not through the load balancer. This should not be a problem for client traffic, but potentially could be an issue for applications accessing the protected server directly, from behind the load balancer.

This procedure explains how to do so for a centralized web policy agent profile configured in OpenAM Console. The steps also mention the properties for web agent profiles that rely on local, file-based configurations.

  1. Login to OpenAM Console as an administrative user with rights to modify the policy agent profile.

  2. Browse to Access Control > Realm Name > Agents > Web > Agent Name to open the web agent profile for editing.

  3. In the Global tab page Profile section, set the Agent Deployment URI Prefix to that of the load balancer.

    The value you set here is used when overriding protocol, host, and port on the protected server with the web policy agent.

    The property to set is com.sun.identity.agents.config.agenturi.prefix.

  4. In the Advanced tab page Load Balancer section, enable Load Balancer Setup.

    The equivalent property setting is com.sun.identity.agents.config.load.balancer.enable=true.

  5. Enable Override Request URL Protocol.

    The equivalent property setting is com.sun.identity.agents.config.override.protocol=true.

  6. Enable Override Request URL Host.

    The equivalent property setting is com.sun.identity.agents.config.override.host=true.

  7. Enable Override Request URL Port.

    The equivalent property setting is com.sun.identity.agents.config.override.port=true.

  8. Enable Notification URL when the web policy agent gets notifications about configuration changes.

    The equivalent property setting is com.sun.identity.agents.config.override.notification.url=true.

  9. Save your work, and then restart the protected server.

Chapter 8. Troubleshooting

This chapter offers solutions to issues during installation of OpenAM policy agents.

Solutions to Common Issues

This section offers solutions to common problems when installing OpenAM policy agents.

Q:

I am trying to install a policy agent, connecting to OpenAM over HTTPS, and seeing the following error.

OpenAM server URL: https://openam.example.com:8443/openam

WARNING: Unable to connect to OpenAM server URL. Please specify the
correct OpenAM server URL by hitting the Back button (<) or if the OpenAM
server URL is not started and you want to start it later, please proceed with
the installation.
If OpenAM server is SSL enabled and the root CA certificate for the OpenAM
server certificate has been not imported into installer JVMs key store (see
installer-logs/debug/Agent.log for detailed exception), import the root
CA certificate and restart the installer; or continue installation without
verifying OpenAM server URL.
    

What should I do?

A:

The Java platform includes certificates from many Certificate Authorities (CAs). If however you run your own CA, or you use self-signed certificates for HTTPS on the container where you run OpenAM, then the agentadmin command cannot trust the certificate presented during connection to OpenAM, and so cannot complete installation correctly.

After setting up the container where you run OpenAM to use HTTPS, get the certificate to trust in a certificate file. The certificate you want is the that of the CA who signed the container certificate, or the certificate itself if the container certificate is self-signed.

Copy the certificate file to the system where you plan to install the policy agent. Import the certificate into a trust store that you will use during policy agent installation. If you import the certificate into the default trust store for the Java platform, then the agentadmin command can recognize it without additional configuration.

Export and import of self-signed certificates is demonstrated in the Administration Guide chapter on Managing Certificates.

Q:

I am trying to install the policy agent on SELinux and I am getting error messages after installation. What happened?

A:

SELinux must be properly configured to connect the web policy agent and OpenAM nodes. Either re-configure SELinux or disable it, then reinstall the policy agent.

Q:

My Apache HTTPD server is not using port 80. But when I install the web policy agent it defaults to port 80. How do I fix this?

A:

You probably set ServerName in Apache HTTPD's configuration to the host name, but did not specify the port number.

Instead you must set both the host name and port number for ServerName in Apache HTTPD's configuration. For example, if you have Apache HTTPD configured to listen on port 8080, then set ServerName appropriately as in the following excerpt.

<VirtualHost *:8080>
ServerName www.localhost.example:8080

Q:

My web server and web policy agent are installed as root, and the agent cannot rotate logs. I am seeing this error.

Could not rotate log file ... (error: 13)

What should I do?

A:

First, avoid installing the web server (and therefore also the web policy agent) as root, but instead create a web server user and install as that user.

If however you cannot avoid installing the web server and policy agent as root, the you must give all users read and write permissions to the logs/ and logs/debug directories under the agent instance directory ( /path/to/web_agents/type/Agent_number/logs/). Otherwise the web policy agent fails to rotate log files with the error you observed.

Q:

I have multiple web servers on a single system, and want to protect each of them with a policy agent.

A:

Once both web policy agents are installed, navigate to the /path/to/Agent_00x directory, and then open the OpenSSOAgentBootstrap.properties file. Near the end of the file, you should see the following attribute:

com.forgerock.agents.instance.id=

Set that attribute to an appropriate unique value such as 1 or 2. Restart the web service that is being protected by the agent. If successful, you should see related shared memory files, with time stamps updated for the restarted web services. On a Linux system, you may see these files in the /dev/shm directory. On a Solaris system, you may see these files in the /tmp directory.

Index