![]() |
Sun ONE Identity Server Policy Agent Pack Guide |
Chapter 7 Policy Agent for Lotus Domino 5.0.10
Sun ONE Identity Server Policy Agents work in tandem with Sun ONE Identity Server to grant or deny user access to web servers in an enterprise. The Sun ONE Identity Server Policy Agent for Lotus Domino 5.0.10 supports only the Single Sign-on (SSO) feature of Sun ONE Identity Server. This chapter explains how to install the Sun ONE Identity Server Policy Agent for Lotus Domino 5.0.10 server running on the Windows 2000 operating system.
Before You Begin
Using the Graphical User Interface (GUI) Version of the Installation Program
Using the Command-Line Version of the Installation Program
Configuring the Domino DSAPI Filter
Before You Begin
Be sure that you are familiar with the concepts presented in Chapter 1 "Read This First." The chapter includes brief but important information on the following topics:
How Policy Agents Work
Java Runtime Environment (JRE) 1.3.1_04 Requirement
Using the Graphical User Interface (GUI) Version of the Installation Program
Use the GUI version to install the Policy Agent.
Installing the Policy Agent Using GUI
You must have administrator privileges to run the Installation program.
Unzip the product binaries file.
Run the Installation program by double-clicking setup.exe.
In the Welcome panel, click Next.
Read the License Agreement. Click Yes to agree to the license terms.
In the Select Installation Directory screen, select where you would like to install the agent by clicking Browse, or click Next to accept the default.
Mark the check box to select the component "SunTM ONE Identity Server Policy Agent 1.1 for Lotus Domino 5.0.10" and click Next.
Provide the following information about the web server where this agent will be installed:
Host Name: Enter the fully qualified domain name of the system where the agent web server is installed. For example, mycomputer.siroe.com.
Domino directory: Enter the full path to the directory where the Domino Web Server instance is located. This is the web server instance that the agent will protect. For example, /Web_Server_root/https-mycomputer.siroe.com.
Domino Data directory: Enter the full path to the directory where the Domino data is located.
Web Server Port: Enter the port number for the web server that will be protected by the agent.
Web Server Protocol: If the web server has been configured for SSL, then select HTTPS; otherwise select HTTP.
Agent Deployment URI: Enter a directory name. The default URI for the policy agent is /amagent.
The Universal Resource Identifier (URI) prefix tells the web server where to look for HTML pages the agent needs to display. For example, when a user attempts to access a URL, but cannot provide proper credentials, the agent must display an "Access denied" message. The URI prefix tells the web server where to look for the HTML page that contains the message. A directory denoted by this URI, will be created in the web server Document Root you supplied.
If all the information entered is correct, click Next.
Provide the following information about the web server that runs Identity Server services.
Identity Server Services Host: Enter the fully qualified domain name of the system where the primary web server that runs Identity Server services is installed. For example, myserver.siroe.com.
Identity Server Services Port: Enter the port number for the primary web server that runs Identity Server services.
Identity Server Services Protocol: If the web server that runs Identity Server services has been configured for SSL, then select HTTPS; otherwise select HTTP.
Identity Server Services Deployment URI: Enter the location that was specified when Identity Server was installed. The default Universal Resource Identifier (URI) for Identity Server is /amserver.
Failover Server Host: Enter the fully qualified domain name for the secondary web server that will run Identity Server services if the primary server becomes unavailable. If no failover server exists, then leave this field blank.
Failover Server Port: Enter the port number of the secondary web server that will run Identity Server services. If no failover server exists, then leave this field blank.
If all the information entered is correct click Next.
When the installation is complete you may review the details, and then click Exit. After the agent is installed successfully, configure the Domino DSAPI filter. See "Configuring the Domino DSAPI Filter".
Invoke Lotus Notes, choose File > Preferences > Local Preferences.
Click Internet Protocols > HTTP tab.
Remove the DSAPI filter file name and leave this field blank.
Click the Save and Close button to save the changes.
Open Domino console and restart the server by entering the following commands:
tell http quit
load http
From the Start Menu, choose Settings > Control Panel.
In the Control Panel, double-click Add / Remove Programs.
In the Add/Remove Programs window, choose iPlanet Directory Services Access Management Edition Agent 1.1 for Lotus Domino 5.0.10 and then click Change/Remove.
In the Welcome Panel, click Next.
In the Type of Uninstall Panel, select Full.
Note
Since there is only one component, it is recommended that you select Full uninstallation.The Partial uninstallation is not supported.
Using the Command-Line Version of the Installation Program
The command-line version of the Installation program provides you an alternative to the graphical user interface (GUI) version.
Installing the Policy Agent Using the Command Line
In the directory where you unzipped the binaries file, at the command line, enter the following command:
java agent_Domino_W2K -nodisplay
When prompted, provide the following information:
Have you read, and do you accept, all of the terms of the preceding Software License Agreement?
Install Sun ONE Identity Server Agent in this directory: Specify the directory where you want the agent to be installed. To accept the default directory that is displayed in brackets, press Enter. Otherwise, enter a full path.
The following text displays:
Sun ONE Identity Server Agent components showing a checked box will be installed. Only one agent may be installed at a time.
[ ] 1 Sun(TM) ONE Identity Server Policy Agent for Lotus Domino 5.0.10
Enter 1 to install the agent.When a check mark appears beside your choice, enter 0 to continue.
When prompted, provide the following information about the Domino server instance this Agent will protect:
Host Name
For details on these items, refer to "Using the Graphical User Interface (GUI) Version of the Installation Program" on page 112.
When prompted, provide the following information about the Domino Server that runs Identity Server Services:
Identity Server Services Host
Identity Server Services Protocol
Identity Server Services Deployment URI
For details on these items, refer to "Using the Graphical User Interface (GUI) Version of the Installation Program" on page 112.
When displayed, review the summary of installation information you've specified. Press Enter to continue, or enter and exclamation point (!) to exit the program.
The following message displays:
Ready to Install
1. Install Now
2. Start Over
3. Exit Installation
What would you like to do
To continue with installation, enter 1.
After the agent is installed, configure the Domino DSAPI filter. Refer to "Configuring the Domino DSAPI Filter"
In the Agent_Install_Dir directory, at the command line, enter the following command:
java uninstall_DSAME_Agent_Pack -nodisplay
When prompted, provide the following information:
Please select the type of uninstall to perform from the following choices: To remove the product and all of the components, enter 1 for Full. To select some, but not all, product components to removed, enter 2 for Partial.
Note
Since there is only one component, it is recommended that you enter 1 for Full uninstallation.The Partial uninstallation is not supported.
The following message displays:
Ready to Uninstall
1. Uninstall Now
2. Start Over
3. Exit Uninstallation
What would you like to do?
To begin uninstalling the agent, enter 1.
The following message displays
Product Result More Info
1. Domino Agent Full Available
2. Done
To see log information, enter 1. To exit the Installation program, enter 2.
When the Installation program is finished, you must reboot the system.
Configuring the Domino DSAPI Filter
Use the following procedure to configure DSAPI filter.
Invoke Lotus Notes, choose File > Preferences > Local Preferences.
Click Internet Protocols > HTTP tab.
Enter the following for DSAPI filter file name:
Agent_Install_Dir\Agents\Domino\lib\amdomino.dll
On Domino console restart the server by entering the following commands:
tell http quit
load http
Using Secure Sockets Layer (SSL) With an Agent
During Installation, if you specify the HTTPS protocol for the web server that runs Identity Server services, the agent is automatically configured to communicate over SSL.
The Agent's Default Trust Behavior
By default, a policy agent is installed on a Domino Server that will trust any server certificate presented over SSL by the web server that runs Identity Server services; the agent does not check the Certificate Authority (CA) certificate. If the web server that runs Identity Server services is SSL-enabled, and you want the policy agent to perform certificate-checking, you must do the following:
Disable the agent's default trust behavior.
Install a CA certificate on the web server where the agent is installed. The CA certificate must the be same one that is installed on the web server that runs Identity Server service.
Disabling the Agent's Default Trust Behavior
The following property exists in the AMAgent.properites file, and by default it is set to true:
com.iplanet.am.policy.agents.trust_server_certs=true
This means that the agent does not perform certificate checking.
To Disable the Default Behavior
The following property must be set to false:
com.iplanet.am.policy.agents.trust_server_certs=false
Installing the CA Certificate
The CA certificate that you install on the Domino server must be the same one that is installed on the web server that runs Identity Server services.
To Install the CA Certificate on Domino Server
See the instructions for installing a CA Certificate in the documentation that comes with the web server. Generally, this is done through the web server's Administration console.
Go to the following directory:
Agent_Install_Dir\Agents\domino\utils
Add the same certificate that is installed on the web server that runs Identity Server services into the existing certificate database. At the command line, enter the following command:
certutil -A -n cert-name -t "C,C,C" -d cert-dir -i cert-file
using the following variables:
cert-name can be any name for this certificate.
cert-dir is directory where the certificate-related files are located. On Windows the locations is:
Agent_Install_Dir\Agents\domino\cert
cert-file is the base-64 encoded certificate file.
For more information on certutil, type certutil -H
Restart Domino Server.
Troubleshooting Information
Installation failure
Generate debug file by executing the following command:
java agent_Domino_W2K -debug -debugMessage
Check the debug messages in the debug file agent_Domino_W2K.class
Unable to start Domino Server
Check the Windows registry and verify whether the registry key HKEY_LOCAL_MACHINE\Software\Sun ONE\IS Domino Agent has the Install path set correctly to Agent_Install_Dir.
Domino Server starts with an error message "Unable to load filter".
Ensure that you have set the DSAPI filter correctly.
The Sun ONE Identity Server Policy Agent uninstaller displays a blank screen and hangs when Partial uninstallation type is selected.
To troubleshoot this problem:
Previous Contents Next
Copyright 2002 Sun Microsystems, Inc. All rights reserved.
Last Updated November 20, 2002