-
Web Policy Agents Guide Sun™ ONE Identity Server Policy Agents Version 2.
-
Sun Microsystems, Inc. 4150 Network Circle Santa Clara, CA 95054 U.S.A. Copyright 2004 Sun Microsystems, Inc. All rights reserved. Sun, Sun Microsystems, the Sun logo, Java, Solaris, Sun ONE, iPlanet, and all Sun, Java, and Sun ONE based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries. UNIX is a registered trademark in the United States and other countries, exclusively licensed through X/Open Company, Ltd.
-
Contents About This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 What You Are Expected to Know . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Identity Server’s Documentation Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Documentation Conventions Used in This Manual . . . . . . . . .
-
Verifying a Successful Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 Chapter 2 Policy Agents on Solaris and HP-UX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Before You Begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Installing the Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
-
Creating the Microsoft IIS 6.0 Agent Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 Creating the Apache 2.0.50 Agent Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 Configuring the Agent for Microsoft IIS 6.0 for a Web Site . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 Configuring the Agent for Apache 2.0.50 for a Web Site . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
-
Shared Secret Encryption Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Uninstalling the Policy Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Removing an Agent using the unconfig Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Uninstalling using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
-
com.sun.am.logFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . com.sun.am.serverLogFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . com.sun.am.logLevels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . com.sun.am.policy.am.username . . . . . . . . . . . . . . . . . . . . . .
-
com.sun.am.policy.agents.logout.cookie_reset_ list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . com.sun.am.policy.am.ldapattribute.cookiePrefix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . com.sun.am.policy.am.ldapattribute.cookieMax Age . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
-
About This Guide SunTM ONE Identity Server Policy Agents, version 2.1 comprise Web Policy Agents and J2EE Policy Agents. This guide offers an introduction to Web Policy Agents and describes how to install and configure these agents on web servers and proxy servers.
-
Identity Server’s Documentation Set Identity Server’s Documentation Set The Sun ONE Identity Server documentation set contains the following titles: • Product Brief provides an overview of the Sun ONE Identity Server and its features and functions. • Installation Guide provides details on how to install and deploy Sun ONE Identity Server on Solaris™, Linux and Windows® 2000 systems.
-
Documentation Conventions Used in This Manual Typographic Conventions This book uses the following typographic conventions: • Italic type is used within text for book titles, new terminology, emphasis, and words used in the literal sense. • Monospace font is used for sample code and code listings, API and language elements (such as function names and class names), filenames, pathnames, directory names, HTML tags, and any text that must be typed on the screen.
-
Related Information Related Information In addition to the documentation provided with Sun ONE Identity Server, there are several other sets of documentation that might be helpful. This section lists these and additional sources of information. iPlanet Directory Server Documentation iPlanet Directory Server 5.1 documentation can be found at http://docs.sun.com/db/coll/S1_ipDirectoryServer_51 iPlanet/Sun ONE Web Server Documentation iPlanet/Sun ONE Web Server documentation can be found at http://docs.sun.
-
Chapter 1 Read This First SunTM ONE Identity Server Policy Agents, version 2.1 comprises Web Policy Agents and J2EE Policy Agents. This chapter provides a brief overview of Web Policy Agents as well as some concepts you will need to understand before proceeding with the installation of these agents. The information in this chapter is common to all the supported operating systems.
-
Web Policy Agents • An agent on a human resources server prevents non-human resources personnel from viewing confidential salary information and other sensitive data. • An agent on an Operations web server allows only network administrators to view network status reports or to modify network administration records. • An agent on an Engineering web server allows authorized personnel from many internal segments of a company to publish and share research and development information.
-
Supported Servers An Agent’s Interaction With Sun ONE Identity Server Figure 1-1 Supported Servers Web Policy Agents, version 2.1 support the following web and proxy servers. This version of the web policy agents supports Sun ONE Identity Server, versions 6.0 SP1, 6.1 and 6.2. Note that the agent supported on Solaris 8 platform is generally also supported on Solaris 9 platform and vice versa. Table 1-1 Supported Servers and Platforms Agent for Supported Platform Sun ONE Web Server 6.
-
Supported Servers Agent for Supported Platform IBM Lotus Domino 6.0.1 Solaris 8 Microsoft Windows 2000 IBM Lotus Domino 5.0.11 Solaris 8 Microsoft Windows 2000 IBM HTTP Server 1.3.19 Solaris 8 Microsoft IIS 5.0 Microsoft Windows 2000 Apache 2.0.47 Red Hat Linux 9.0 IBM HTTP Server 1.3.26 Solaris 8 Solaris 9 Sun ONE Web Server 4.1 Solaris 8 Oracle9iAS Apache 1.3.29 Solaris 8 SAP Internet Transaction Server 2.0 Microsoft Windows 2000 Advanced Server Apache 2.0.
-
Before You Begin Installation Before You Begin Installation Read the following sections carefully before you start the installation program: • Java Runtime Environment 1.3.
-
Before You Begin Installation Remote Web Servers You can use the installation program to install a policy agent on the web server where Sun ONE Identity Server is installed. In Sun ONE documentation, this server is referred to as the web server that runs the Sun ONE Identity Server. You can also use the installation program to install additional policy agents on remote web servers in your enterprise.
-
Before You Begin Installation com.sun.am.policy.am.loginURL= http://primary_Identity _Server.example.com:58080/amserver/UI/Login http://failover_Identity _Server.example.com:58080/amserver/UI/Login The failover server name is configurable after it has been set during the installation. In the properties file, it is the second entry in this property following the primary Sun ONE Identity Server login URL separated by a space.
-
Before You Begin Installation The agent sets a timeout period on its cache entries. After its end of life, the cache entry is purged from the agent’s cache. The agent does not refetch the cache data. The next attempt to access the same entry from cache fails and the agent makes a round trip to the server and fetches it again to populate the cache. This lazy method of cache updating keeps the agent cache performing optimally and reduces network traffic.
-
Before You Begin Installation Here are a few examples: Scenario 1: com.sun.am.policy.agents.reverse_the_meaning_of_notenforcedList= false com.sun.am.policy.agents.notenforcedList = http://mycomputer.example.com:80/welcome.html http://mycomputer.example.com:80/banner.html In this case, authentication and policies will not be enforced on the two URLs listed in the notenforcedList. All other resources will be protected by the agent. Scenario 2: com.sun.am.policy.agents.
-
Before You Begin Installation Forwarding LDAP User Attributes via HTTP Headers The policy agent has the ability to forward LDAP user attribute values via HTTP headers to end-web applications. The LDAP user attribute values come from the server side of Sun ONE Identity Server. The policy agent behaves like a broker to obtain and relay user attribute values to the destination servlets, CGI scripts, or ASP pages. These applications can in turn use the attribute values to personalize page content.
-
Before You Begin Installation # # The policy attributes to be added to the HTTP header. The # specification is of the format # ldap_attribute_name|http_header_name[,...]. ldap_attribute_name # is the attribute in data store to be fetched and # http_header_name is the name of the header to which the value # needs to be assigned.
-
Before You Begin Installation The Agent Properties File The AMAgent.properties file stores configuration parameters used by the policy agent. From time to time, you may need to make changes to the default parameters in this file. For example, when you want to specify a different failover web server for running Sun ONE Identity Server. The AMAgent.
-
Before You Begin Installation Table 1-2 Locating AMAgent.properties on Different Platforms (Continued) Server Location Lotus Domino 5.0.11 or 6.0.1 Microsoft Windows 2000 \Agent_Install_Dir\domino\config\_PathInstanceName\ Microsoft IIS 5.0 Microsoft Windows 2000 \Agent_Install_Dir\iis\config\_PathInstanceName\ Microsoft IIS 6.0 Microsoft Windows Server 2003 EE \Agent_Install_Dir\iis6\config\_Identifier_IdentifierNumber Apache 2.0.
-
Before You Begin Installation a valid hostname in the URL, it redirects the user to the corresponding URL with a valid hostname. The difference between the redirect URL and the URL originally used by the user is only the hostname, which is changed by the agent to a fully qualified domain name (FQDN) as per the value specified in this property. This is a required configuration property without which the web server may not start up correctly.
-
Before You Begin Installation Say you want your server to be addressed as xyz.hostname.com whereas the actual name of the server is abc.hostname.com. The browser only knows xyz.hostname.com and you have specified policies using xyz.hostname.com at the Identity Server console. In this file, set the mapping as com.sun.am.policy.agents.fqdnmap = valid|xyz.hostname.
-
Before You Begin Installation By default, this property is set to false, and the feature is turned off. To turn on CDSSO, set this property to true. Set the URL where CDC controller is installed by specifying the URL in the following property: com.sun.am.policy.agents.cdcservletURL = http://nila.eng.example.com:58080/amserver/cdcservlet The third property, com.sun.am.policy.agents.cookieDomainList allows you to specify a list of domains in which cookies have to be set in a CDSSO scenario.
-
Before You Begin Installation Figure 1-2 2. Sun ONE Identity Server Login Page Check the file AMAgent.properties. Make sure that each property is set properly. For details about the properties in this file, see Appendix A, “AMAgent Properties.
-
Before You Begin Installation 30 Sun ONE Identity Server Policy Agents 2.
-
Chapter 2 Policy Agents on Solaris and HP-UX SunTM ONE Identity Server Policy Agents work in tandem with SunTM ONE Identity Server to control user access to web servers in an enterprise. This chapter explains how to install and configure the Web Policy Agents available for the web and proxy servers running on Solaris 8 and 9 and HP-UX 11.11 operating systems.
-
Before You Begin 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: • Supported Servers • Web Policy Agents • Java Runtime Environment 1.3.
-
Installing the Agent Installing the Policy Agent for a Web Server You must have root permissions when you run the agent installation program. 1. Unpack the product binary using the following command: # gunzip -dc binaryname.tar.gz| tar -xvof - 2. Run the setup program. You’ll find the program in the directory where you untarred the binaries. At the command line, enter the following: # ./setup 3. Set your JAVAHOME environment variable to a JDK version 1.3.1_04 or higher.
-
Installing the Agent Apache Binary Directory: Select the directory where the Apache binary, that is, httpd binary is installed. This field appears only when you are installing the agent for Apache Server. Lotus Domino Data directory: Enter the full path to the directory where the Domino data is located. The default data directory is /local/notesdata. This field is available only if you are installing the policy agent for Lotus Domino.
-
Installing the Agent ❍ NOTE 9. Apache web server with mod_ssl and EAPI flag enabled. Apache web server with mod_ssl support and EAPI flag disabled configuration is not supported by Sun ONE Identity Server policy agents. When you have entered all the information correctly, click Next. 10. Enter information about the web server that runs Sun ONE Identity Server. The policy agent will connect to this server.
-
Installing the Agent Agent Identity Server Shared Secret: Enter the password for the Identity Server internal LDAP authentication user (amldapuser). Re-enter Shared secret: Re-enter the password for the Identity Server internal LDAP authentication user. CDSSO Enabled: Check this box if you want to enable CDSSO. 11. When all the information is entered correctly, click Next. 12. Review the Installation Summary to be sure that the information you’ve entered is correct.
-
Installing the Agent 5. To search for the directory where you would like to install the agent, click Browse. To accept the default, click Next. 6. When prompted, provide the following information about the web proxy server where this agent will be installed: Host Name: Enter the FQDN of the system where the remote web server is installed. For example, mycomputer.example.com. Proxy Server Instance Directory: Enter the full path to the directory where the Sun ONE Web Proxy Server instance is located.
-
Installing the Agent Failover Server Port: Enter the port number of the secondary web server that runs Sun ONE Identity Server. If no failover host exists, then leave this field blank. Failover Server Deployment URI: Enter the location that was specified when Sun ONE Identity Server was installed. The default URI for Sun ONE Identity Server is /amserver. Failover Console Deployment URI: Enter the location that was specified when Sun ONE Identity Server console was installed.
-
Installing the Agent 2. Set your JAVAHOME environment variable to a JDK version 1.3.1_04 or higher. The installation requires that you set up your JAVAHOME variable correctly. However, in case you have incorrectly set the JAVAHOME variable, the setup script will prompt you for supplying the correct JAVAHOME value: Please enter JAVAHOME path to pick up java: 3. Type the full path to the directory where JDK is located and press Enter. 4.
-
Installing the Agent ❍ Failover Server Port ❍ Failover Server Deployment URI ❍ Failover Console Deployment URI ❍ Agent-Identity Server Shared secret ❍ Re-enter Shared secret ❍ CDSSO Enabled For more information on each of these items, see “Installing the Policy Agent for a Web Server.” The following text is displayed: Ready to Install 1. Install Now 2. Start Over 3. Exit Installation 7. When prompted, What would you like to do?, enter 1 to start the installation.
-
Installing the Agent 2. When prompted, provide the following information: Have you read, and do you accept, all of the terms of the preceding Software License Agreement? Enter yes. Install Sun ONE Identity Server Agent in this directory: Enter the full path to the directory in which you want to install the policy agent. 3.
-
Post-installation Tasks ❍ CDSSO Enabled For more information on each of these items, see “Installing the Policy Agent for a Web Proxy Server.” The following text is displayed: Ready to Install 1. Install Now 2. Start Over 3. Exit Installation 5. When prompted, What would you like to do?, enter 1 to start the installation. The following text is displayed: Product Result More Information 1. Sun ONE Identity Server Agent Installed Available 2. Done 6. To see log information, enter 1.
-
Post-installation Tasks 2. From the listed servers, select the required server. 3. Click Internet Protocols > HTTP tab. 4. At the DSAPI Filter File Names field, enter the file names as follows: ❍ ❍ For IBM Lotus Domino 5.0.11, enter Agent_Install_Dir/SUNWam/Agents/Domino/lib/libamdomino.so For IBM Lotus Domino 6.5, enter Agent_Install_Dir/SUNWam/agents/domino6/lib/libamdomino6.so 5. Click the Save and Close button to save the changes. 6.
-
Configuring the Agent for Multiple Web Server Instances Additionally, if Sun ONE Identity Server is running with SSL, the files cert7.db and key3.db must also allow ‘read’ access to the user the Domino Server is running as. These files are available in the directory specified by the property com.sun.am.sslCertDir in the AMAgent.properties file. For example, if the property is set as com.sun.am.sslCertDir = /opt/my-agents-dir, ensure that /opt/my-agents-dir/{cert7.db,key3.
-
Configuring the Agent for Multiple Web Server Instances NOTE On HP-UX 11.11, you must use the scripts config_es6 and unconfig_es6 to configure and unconfigure the agent for multiple web server instances. These scripts are available in the following directory: Agent_Install_Dir/agents/WS_TYPE/bin 1. To configure the agent for additional web server instances on a system, run the config script from the bin directory using the following command: # ./config 2.
-
Using Secure Sockets Layer (SSL) With an Agent NOTE Be sure to use the unconfig script to uninstall any agent that was installed using the config script—you cannot use the GUI installation program to uninstall agents that were installed from the command line. The GUI uninstallation program must be executed only after unconfiguring all the existing agents using the command-line unconfig script.
-
Using Secure Sockets Layer (SSL) With an Agent 1. Create a new key database using the key management utility (IKEYMAN). For information on creating new key database, see the documentation at: http://www-3.ibm.com/software/webservers/httpservers/doc/v1319/9atikeyu.htm#H DRKMU2G 2. Create a self-signed certificate using IKEYMAN. For information on creating a self-signed certificate, see the documentation at: http://www-3.ibm.com/software/webservers/httpservers/doc/v1319/9atikeyu.htm#H DRKMU4G 3.
-
Using Secure Sockets Layer (SSL) With an Agent Disabling the Agent’s Default Trust Behavior The following property in the AMAgent.properties file controls the agent’s trust behavior, and by default it is set to true: com.sun.am.trustServerCerts=true This means that the agent does not perform certificate checking. To Disable the Default Behavior 1. Set the following property to false: com.sun.am.trustServerCerts=false 2. Set the directory Cert DB in the file AMAgent.
-
Using Secure Sockets Layer (SSL) With an Agent Installing the Root CA Certificate on the Remote Web Server The root CA certificate that you install on the remote web server must be the same one that is installed on the web server that runs Sun ONE Identity Server. To Install the Root CA Certificate on Sun ONE Web Server See the instructions for installing a root CA certificate in the documentation that comes with the web server.
-
Using Secure Sockets Layer (SSL) With an Agent ❍ cert-file is the base-64 encoded root CA certificate file. For more information on the certutil utility, enter certutil -H for online Help. To verify that the certificate is properly installed, at the command line, enter the following: 4. # ./certutil -L -d . Trust database information will be displayed including the name of the root CA certificate you installed.
-
Using Secure Sockets Layer (SSL) With an Agent 3. Install root CA certificate. # /Agent_Install_Dir/SUNWam/agents/proxy/cert/certutil -N -d . # /Agent_Install_Dir/SUNWam/agents/proxy/cert/certutil -A -n cert-name -t "C,C,C" -d cert-dir -i cert-file In the commands above, the variables represent the following: ❍ cert-name can be any name for this root CA certificate. ❍ cert-dir is the directory where the certificate and key stores are located.
-
Using Secure Sockets Layer (SSL) With an Agent ❍ cert-name can be any name for this root CA certificate. ❍ cert-dir is the directory where the certificate and key stores are located. ❍ cert-file is the base-64 encoded root CA certificate file. For more information on the certutil utility, enter certutil -H for online Help. To verify that the certificate is properly installed, at the command line, enter the following: 4. # ./certutil -L -d .
-
Setting the REMOTE_USER Server Variable 3. In the command above, the variables represent the following: ❍ ❍ cert-name can be any name for this certificate. cert-dir is the directory where the certificate and key stores are located. The location is: Agent_Install_Dir/Agents/domino/cert ❍ cert-file is the base-64 encoded certificate file. For more information on certutil, type certutil -H 4. Restart Domino Web Server.
-
POST Data Preservation The AMAgent.properties file contains a property titled com.sun.am.policy.agents.client_ip_validation_enable, which by default is set to false. If you set this property value to true, client IP address validation will be enabled for each incoming request that contains an SSO token. If the IP address from which request was generated does not match the IP address issued for the SSO token, the request will be denied. This is essentially the same as enforcing a deny policy.
-
Shared Secret Encryption Utility Shared Secret Encryption Utility The policy agent stores the shared secret in the AMAgent.properties file. By default, this password is the Identity Server internal LDAP authentication user password. This can be changed on the server side by editing the AMConfig.properties file. The property com.sun.am.policy.am.password in the AMAgent.properties file is set with the encrypted shared secret while installing the agent.
-
Uninstalling a Policy Agent WS_TYPE can be es6, proxy, apache or domino depending on which web server the agent is protecting. On HP-UX 11.11, you must use the script unconfig_es6 instead of the unconfig script. You can find the script in the following directory: Agent_Install_Dir/agents/es6/bin Here is an example run of the unconfig script. # ./unconfig /web_server_root/https-server_instance Unconfiguring webserver ... done. NOTE If you are removing the agent for Lotus Domino 5.0.
-
Uninstalling a Policy Agent 7. Open the Domino console and restart the server by entering the following commands: tell http quit load http Uninstalling Using the GUI To uninstall an agent, you must run the uninstallation program. Follow the steps below: 1. In the directory where the agent is installed, at the command line, enter the following command: # ./uninstall_agent On HP-UX 11.11, use the following command: java uninstall_Sun_ONE_Identity_Server_Policy_Agent 2. Click Next on Welcome panel. 3.
-
Troubleshooting Ready to Uninstall 1. Uninstall Now 2. Start Over 3. Exit Uninstallation 2. When prompted, What next? enter 1 to begin uninstallation. The following text is displayed: Product 1. Sun ONE Identity Server Agent 2. Done Result Full More Information Available 3. To see log information, enter 1. To exit the uninstallation program, enter 2. 4. Restart the web server.
-
Troubleshooting • You might have a previously-installed agent and did not use the agent's uninstallation program to uninstall the agent. • The installation program's productregistry file may be corrupted. Solution: • Check that you have uninstalled any existing installation of the agent. • The productregistry file may be corrupted if there is no existing installation of the agent. This file is used by the installation program to track installed products. It is found in /var/sadm/install directory.
-
Troubleshooting ...... Sun ONE Identity Server Policy Agent 2.1 Sun ONE Identity Server Policy Agent The uninstallation program does not remove entries from the agent’s web server if there is another instance of web server configured using the Configuration script. Solution: You should remove all the instances of the agent using the unconfig script before running the uninstallation program.
-
Known Problems 5. Take the pid from the previous step and do pldd pid of the process | grep mtmalloc The output should show /usr/lib/libmtmalloc.so.1. The browser goes into a loop for a minute or so before displaying an access-denied page when a user tries to access a resource for which a policy with a time condition has been set and the time on the agent host and the Identity Server host are not in sync.
-
Known Problems Policies not working with Sun ONE Web Proxy Server agent. The resource names for setting policies for the reverse proxy agent should be the URLs qualified as “URL prefix (from client)” in the Sun ONE Web Proxy Server 3.6 administrative console. Agents are not effective anymore after the modification of Sun ONE Web Server configuration using the administrative console. Modifications to the configuration of the web server’s configuration files (obj.conf, magnus.
-
Chapter 3 Policy Agents on Microsoft Windows This chapter explains how to install and configure Web Policy Agents available for the web servers running on Microsoft Windows operating system.
-
Before You Begin Before You Begin Be sure that your are familiar with the concepts presented in Chapter 1, “Read This First.” The chapter includes brief but important information on the following topics: • Supported Servers • Web Policy Agents • Java Runtime Environment 1.3.
-
Overview of Policy Agents for Microsoft Windows Furthermore, some variety exists among the policy agents for Microsoft Windows in how they are installed and configured. The installation of the agents for Microsoft Windows can be categorized into two distinct types. Therefore, for purposes of written organization these agents have been divided in this chapter into the two following groups.
-
Overview of Policy Agents for Microsoft Windows The Agent Installation Types All the Installation Type I agents share the same installation steps. The agents for Domino 5 and 6 require additional configuration of the Domino server. Both the Installation Type II agents, Microsoft IIS 6.0 and Apache 2.0.50, also share the same installation steps. However, after the installation steps are completed, both of these agents require configuration. The configuration steps are divided into two sets of steps.
-
Installing and Configuring the Installation Type I Agents NOTE The policy agent for Microsoft IIS 6.0 is an ISAPI application. It is deployed as a wildcard application mapping to a web site. This implies that the agent for Microsoft IIS 6.0 when deployed for a particular web site intercepts every request for accessing the resources on that web site. It does authentication and policy evaluation. If all the conditions are met the agent allows access to the resource.
-
Installing and Configuring the Installation Type I Agents 2. Run the installation program by double-clicking setup.exe. 3. In the Welcome window, click Next. 4. Read the License Agreement. Click Yes to accept the license agreement. 5. Select the directory where you want to install the agent. 6. Enter the applicable information about the web server where this agent will be installed in the dialog box. The dialog box provides fields for entering the required information.
-
Installing and Configuring the Installation Type I Agents Table 3-2 Prompted Web Server Information Web Server Field Details Server Protocol If your web server has been configured for SSL, then select HTTPS; otherwise select HTTP. Agent Deployment URI Enter a Universal Resource Identifier (URI) on the agent. NOTE This URI is used to form the value of the com.sun.am.policy.agents.a genturiprefix property in AMAgent.properties. The value formed should be valid. The agent uses the value of the com.
-
Installing and Configuring the Installation Type I Agents 8. Provide the following information about the web server that runs Sun ONE Identity Server: Primary Server Host: Enter the FQDN of the system where the primary web server that runs Sun ONE Identity Server is installed. For example, myserver.example.com. Primary Server Port: Enter the port number for the web server that runs Sun ONE Identity Server.
-
Installing and Configuring the Installation Type I Agents 12. When the installation is complete, you can click Details to view details about the installation, or click Close to end the installation program. 13. Restart your computer. Restarting your computer is necessary for the agent to work properly. The installation modifies the system path by appending to it the location of the agent libraries. This change takes effect only after your computer is restarted.
-
Installing Any Agent from the Command Line • Configure the filter for each of the server partitions you want to support. You can configure the filter for the different partitions by performing the following steps: 1. In Lotus Domino Administrator, choose Administrator Tab > Server > All Server Documents. 2. From the listed servers, select the required server. 3. Now go to Internet Protocols > HTTP. 4.
-
Installing Any Agent from the Command Line 2. 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 Policy 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 the full path. 3.
-
Installing Any Agent from the Command Line ❍ CDSSO feature enabled For details on these items, see the corresponding information as described in “Installing and Configuring the Installation Type I Agents” on page 67. 5. When displayed, review the summary of installation information you’ve specified. Press Enter to continue, or enter exclamation mark (!) to exit the program. The following text is displayed: Ready to Install 1. Install Now 2. Start Over 3. Exit Installation What would you like to do 6.
-
Installing the Installation Type II Agents For the Installation Type I Agents, configuration is only necessary for Lotus Domino 5 and 6. You must configure the Domino DSAPI filter as explained in “Configuring the Domino DSAPI Filter” on page 71. For Installation Type II Agents, configuration is necessary for both agents. For detailed information, see “Configuring the Installation Type II Agents” on page 75.
-
Configuring the Installation Type II Agents 1. Creating the agent configuration file for the web site that is to be protected by the agent 2. Configuring the agent for that web site Ensure that you create the agent configuration file before you configure the agent.Refer to the proper section as follows: • “Creating the Microsoft IIS 6.0 Agent Configuration File” on page 76 • “Creating the Apache 2.0.50 Agent Configuration File” on page 79 • “Configuring the Agent for Microsoft IIS 6.
-
Configuring the Installation Type II Agents NOTE Make sure that you give a unique name for the configuration file since you will need the same file to unconfigure the agent. The script prompts for information as it progresses with the creation of the agent configuration file. The following is output from running the command. Microsoft (R) Windows Script Host Version 5.6 Copyright (C) Microsoft Corporation 1996-2001. All rights reserved Copyright c 2004 Sun Microsystems, Inc.
-
Configuring the Installation Type II Agents CDSSO Enabled [false]: ----------------------------------------------------Agent Configuration file created ==> defaultConfig Execute the below command for Agent Configuration : cscript.exe IIS6admin.vbs -config defaultConfig ----------------------------------------------------- 3.
-
Configuring the Installation Type II Agents CDSSO feature enabled ❍ For details on these items, see the corresponding information as described in “Installing and Configuring the Installation Type I Agents” on page 67. With the information you provide, the script creates the agent configuration file which you can use to configure the agent. For steps to configure the agent, see “Configuring the Agent for Microsoft IIS 6.0 for a Web Site” on page 81. Creating the Apache 2.0.
-
Configuring the Installation Type II Agents ----------------------------------------------------Apache 2.0.50 Server ----------------------------------------------------Enter the Agent Resource File Name [ApacheResource.en] : Fully Qualified Host Name : drake.red.iplanet.
-
Configuring the Installation Type II Agents 4.
-
Configuring the Installation Type II Agents 2. Run the following command: cscript.exe IIS6admin.vbs -config defaultConfig where defaultConfig is the agent configuration file. The script displays messages to indicate the progress of the configuration as shown in the following sample. Microsoft (R) Windows Script Host Version 5.6 Copyright (C) Microsoft Corporation 1996-2001. All rights reserved. Copyright c 2004 Sun Microsystems, Inc.
-
Configuring the Installation Type II Agents where Identifier_1 is the identifier of the web site for which the agent is being configured. NOTE If you want to configure the agent for multiple web sites, you must follow the above steps for each of the web sites. Configuring the Agent for Apache 2.0.50 for a Web Site Configure the agent for Apache 2.0.50 for a web site after you have created an agent configuration file.
-
Using Secure Sockets Layer (SSL) with an Agent 3. Once the configuration is complete, change to the directory \Agent_Install_Dir\Apache\config\apache_80 4. Optionally, open the AMAgent.properties file and change the value of the property com.sun.am.logLevels to all:5. Before you modify any of the agent properties, refer to Appendix A, “AMAgent Properties” on page 161 for more information. 5. Save the AMAgent.properties file. 6. Change to the directory where the Apache server was installed. 7.
-
Using Secure Sockets Layer (SSL) with an Agent The Agent’s Default Trust Behavior This section only applies when Identity Server itself is running SSL. By default, the policy agent installed on a supported web server will trust any server certificate presented over SSL by the web server that runs Sun ONE Identity Server; the agent does not check the root Certificate Authority (CA) certificate.
-
Using Secure Sockets Layer (SSL) with an Agent Installing the Root CA Certificate on Domino Web Server The CA certificate that you install on the Domino Web server must be the same one that is installed on the web server that runs Identity Server services. 1. Go to the following directory: Agent_Install_Dir\Agents\domino\utils 2. Add the same root CA certificate that is installed on the web server that runs Identity Server services into the existing certificate database.
-
Using Secure Sockets Layer (SSL) with an Agent Agent_Install_Dir\bin\certutil -L -d cert-dir You should see the root CA certificate added and listed in the output of the command. Example of certutil -L Output Table 3-3 Certificate Name Trust Attrubutes cert-name C,C,C p P c T C u w 4. Valid peer Trusted peer (implies c) Valid CA Trusted CA to issue client certs (implies c) Trusted CA to certs(only server certs for ssl) (implies c) User cert Send warning Restart Domino Web Server.
-
Using Secure Sockets Layer (SSL) with an Agent ❍ cert-file is the base-64 encoded root CA certificate file. For more information on the certutil utility, see the online help by entering the following command: certutil -H 3. To verify that the root CA certificate was installed properly in the certificate database, enter the following command: Agent_Install_Dir\bin\certutil -L -d cert-dir You should see the root CA certificate added and listed in the output of the command.
-
Using Secure Sockets Layer (SSL) with an Agent 4. To verify that the certificate is properly installed, at the command line, enter the following: \Agent_Install_Dir\bin\certutil -L -d cert-dir You should see the root CA certificate added and listed in the output of the command. See Table 3-3 on page 87 for an example of output after running the certutil -L command. 5. Restart IIS. Installing the Root CA Certificate on Apache 2.0.50 1. Go to the following directory: What is the directory for Apache 2.
-
Setting the REMOTE_USER Server Variable Setting the REMOTE_USER Server Variable The REMOTE_USER server environment variable is normally set by the agent to the user ID of the user who is accessing the page after being authenticated with Identity Server. By setting this variable to a specific user, the user becomes available to web applications (such as a CGI, servlet, or an ASP program). This feature makes it possible to personalize the content of displayed HTML pages to specific users.
-
POST Data Preservation The AMAgent.properties file contains a property titled com.sun.am.policy.agents.client_ip_validation_enable, which by default, is set to false. If you set this property value to true, client IP address validation will be enabled for each in-coming request that contains an SSO token. If the IP address from which request was generated does not match the IP address issued for the SSO token, the request will be denied. This is essentially the same as enforcing a deny policy.
-
Shared Secret Encryption Utility Shared Secret Encryption Utility The policy agent stores the shared secret in the AMAgent.properties file. By default, this shared secret is the Identity Server internal LDAP authentication user password. This can be changed on the server side by editing the AMConfig.Properties file. The property com.sun.am.policy.am.password in the AMAgent.properties file is set with the encrypted shared secret while installing the agent.
-
Disabling, Uninstalling, and Unconfiguring Microsoft Windows Policy Agents Disabling the Policy Agent Installed on Microsoft IIS 5.0 The following steps help you disable an agent installed on Microsoft IIS. To disable an agent on Microsoft IIS 1. Launch Internet Services Manager. ❍ 2. From the Start menu, choose Programs > Administrative Tools > Internet Services Manager. Check the filter status. a.
-
Disabling, Uninstalling, and Unconfiguring Microsoft Windows Policy Agents 6. Click \Agent_Install_dir\iis6\bin\amiis6.dll 7. Click on Remove. 8. Click Yes at the popup “Remove the selected Script Mapping(s)?.” 9. Click Ok. 10. Restart the application pool to which the web site belongs. 11. Restart the web site.
-
Disabling, Uninstalling, and Unconfiguring Microsoft Windows Policy Agents To uninstall the agent for Lotus Domino 1. Launch Lotus Domino Administrator. 2. Choose Administrator Tab > Server > All Server Documents. 3. From the listed servers, select the server you want to uninstall. 4. Click Internet Protocols > HTTP tab. 5. Remove the DSAPI filter file name specified for the agent and leave this field blank. 6. Click the Save and Close button to save the changes. 7.
-
Disabling, Uninstalling, and Unconfiguring Microsoft Windows Policy Agents To uninstall an agent from the command line 1. In the Agent_Install_Dir directory, at the command line, enter the following command: java uninstall_Sun_ONE_Identity_Server_Policy_Agent -nodisplay The uninstallation program displays the following text: 1. Uninstall Now 2. Start Over 3. Exit Uninstallation What would you like to do? 2. Enter 1 to start the uninstallation.
-
Disabling, Uninstalling, and Unconfiguring Microsoft Windows Policy Agents Unconfiguring the Agent for Microsoft IIS 6.0 From a Web Site Perform the following steps to unconfigure the agent for Microsoft IIS 6.0 from a web site. Make sure that you use the agent configuration file specific to the web site you want to unconfigure. If you need to unconfigure the agent from multiple web sites, you must repeat these steps for each of the web sites. If you want to uninstall the agent for Microsoft IIS 6.
-
Disabling, Uninstalling, and Unconfiguring Microsoft Windows Policy Agents Unconfiguring the Agent for Apache 2.0.50 From a Web Site Perform the following steps to unconfigure the agent for Apache 2.0.50 from a web site. Make sure that you use the agent configuration file specific to the web site you want to unconfigure. If you need to unconfigure the agent from multiple web sites, you must repeat these steps for each of the web sites. If you want to uninstall the agent for Apache 2.0.
-
Troubleshooting Uninstalling Installation Type II Policy Agents The steps for uninstalling the agent are the same for both Microsoft IIS 6.0 and Apache 2.0.50. Before running the uninstallation program, ensure that you have already unconfigured the agents from all the web sites for which they were configured as explained in the applicable section: • “Unconfiguring the Agent for Microsoft IIS 6.0 From a Web Site” on page 97 • “Unconfiguring the Agent for Apache 2.0.
-
Troubleshooting • You might have an existing installation of the agent. • You might have a previously-installed agent and did not use the agent's uninstallation program to uninstall the agent. • The installation program's productregistry file may be corrupted. Solution: • Check that you have uninstalled any existing installation of the agent. • The productregistry file may be corrupted if there is no existing installation of the agent.
-
Troubleshooting SUNWamcom Agent for ... 2.1 Agent for ... ...... Sun ONE Identity Server Policy Agent 2.1 Sun ONE Identity Server Policy Agent Unable to uninstall the agent from Windows Start menu > Settings > Control Panel > Add/Remove Programs. Possible Cause: Java's classpath may not be set correctly on the machine.
-
Troubleshooting The agent goes into an infinite loop if the users who are redirected to the resource mentioned in the property com.sun.am.policy.agents.accessDeniedURL do not have the “Get/allow policy” assigned to them. Solution: Assign “Get/allow policy” to all users of the resource mentioned in the com.sun.am.policy.agents.accessDeniedURL property. Microsoft IIS 5.
-
Troubleshooting h. Check your system path to ensure that the following directory is present: Agent_Install_Dir\bin i. If the filter did not load successfully check the following: • Check the path of the Agent DLL by clicking “Sun ONE Identity Server Agent” and then Edit. Ensure that the path in the text box labeled Executable is valid. • The agent also needs several DLL files. Check that the following exist in the directory Agents\bin: amsdk.dll ames6.dll libnspr4.dll libplc4.dll libplds4.
-
Troubleshooting The log is located by default at the Agent_Install_Dir directory. This is the best source of debug information for resolving initialization and agent operation issues. The log file directory is specified by the property: com.sun.am.policy.am.logFile in the AMAgent.properties file located in the directory: Agent_Install_Dir\iis\config\_PathInstanceName The property com.sun.am.policy.am.loglevels controls the verbosity of the log information.
-
Known Problems b. Select the Application Log. c. Check for agentError messages with source as Sun ONE Identity Server IIS agent. Known Problems Agents are not effective after modification of Sun ONE Web Server configuration using the admin console. The changes made by the agent installation to the server configuration files are overwritten by saving the changes in admin console.
-
Known Problems 106 Sun ONE Identity Server Policy Agents 2.
-
Chapter 4 Policy Agents on Red Hat, SuSE, and Debian Linux This chapter explains how to install and configure Web Policy Agents available for the web servers running on Red Hat Linux 7.2, Red Hat Linux 9.0 and Red Hat Advanced Server 2.1.
-
Pre-installation Tasks • Supported Servers • Web Policy Agents • Java Runtime Environment 1.3.
-
Pre-installation Tasks 2. Before you run configure, set an environment variable LIBS=-lpthread as shown in the table. Table 4-1 Setting the Environment Variable Shell Environment Variable sh LIBS=-lpthread;export bash export LIBS=-lpthread tcsh setenv LIBS '-lpthread' 3. Configure your Apache Web Server with the following flags: configure --enable-rule=SHARED_CORE --enable-shared=max 4. Rebuild and install Apache Web Server. 5. Install the Apache agent. Policy Agent for Apache 2.0.
-
Pre-installation Tasks Policy Agents for IBM Lotus Domino 6.0.2 and 6.5 If you are installing the agents for IBM Lotus Domino 6.5 or 6.0.2 on RedHat Advanced Server 2.1, make sure that C++ libraries from GCC 3.3.2 are installed on the system. This is due to a bug with exception handling in Domino Server on Red Hat Advanced Server 2.1. The GCC 3.3.2 libraries needed by the agents libraries are: • /usr/lib/libstdc++.so.5 • /usr/lib/libgcc_s.so.1 These can be built and installed from GCC 3.3.
-
Pre-installation Tasks Stopping and Starting the Apache Server The command for starting the Apache server is different when SSL is enabled. However, the command for stopping the Apache server is the same if SSL is enabled or not. To start the Apache server when SSL is enabled, use the following command. /opt/apache_install/bin/apachetl -D SSL -k start To start the Apache server when SSL is not enabled, use the following command.
-
Pre-installation Tasks ./config --prefix=/usr/local/openssl make clean make install 2. Ensure that openSSL is installed at /usr/local/openssl. 3. Add /usr/local/openssl into your PATH variable. Enabling SSL To compile Apache source by enabling SSL, follow these steps: 1. Change to the following directory: /opt/apache_src/httpd-2.0.52 2. Execute the following command: .
-
Installing the Agent Stopping and Starting the Apache Server The command for starting the Apache server is different when SSL is enabled. However, the command for stopping the Apache server is the same if SSL is enabled or not. To start the Apache server when SSL is enabled, use the following command. /opt/apache_install/bin/apachetl -D SSL -k start To start the Apache server when SSL is not enabled, use the following command.
-
Installing the Agent 2. Run the setup program. You’ll find the program in the directory where you untarred the binaries. At the command line, enter the following: # ./setup 114 3. In the Welcome page, click Next. 4. Read the License Agreement. Click Yes to agree to the license terms. 5. To search for the directory where you would like to install the agent, click Browse. To accept the default, click Next. Sun ONE Identity Server Policy Agents 2.
-
Installing the Agent 6. When prompted, provide the following information about the web server this agent will protect: Install Sun ONE Identity Server Policy Agent in this directory: Enter the full path to the directory where you want this agent to be installed, and then click Next. Host Name: Enter the FQDN of the machine where the web server is installed. For example, mycomputer.example.com Apache Configuration Directory: Specify the Apache server configuration directory where the httpd.
-
Installing the Agent 7. When all the information is entered correctly, click Next. 8. Enter information about the web server that runs Sun ONE Identity Server policy and management. The policy agent will connect to this server. Primary Server Host: Enter the FQDN of the system where the primary web server that runs Sun ONE Identity Server is installed. For example, myserver.example.com. Primary Server Port: Enter the port number for the web server that runs Sun ONE Identity Server.
-
Installing the Agent 10. Review the installation summary to be sure that the information you’ve entered is correct. Note that it displays the CDCServlet URL if you have checked the CDSSO Enabled box in the previous panel. If you want to make changes, click Back. If all the information is correct, click Next 11. In the Ready to Install page, click Install Now. 12.
-
Installing the Agent 5.
-
Post-installation Tasks 7. To see log information, enter 1. To exit the Installation program, enter 2. Post-installation Tasks After you have installed the policy agent, you must perform a set of post-installation tasks as explained in the following sections. Agent for IBM Lotus Domino 6.5 For the agent for IBM Lotus Domino 6.5 to work properly, make sure that the user that Domino server is running as has read permission to the following files: • Agent_Install_Dir/agents/domino6/lib/libamdomino6.
-
Configuring the Agent for Multiple Web Server Instances For example, if the property is set as com.sun.am.sslCertDir = /opt/my-agents-dir, ensure that /opt/my-agents-dir/{cert7.db,key3.db} has the necessary permissions by using the following command: chown notes:notes /opt/my-agents-dir/cert7.db /opt/my-agents-dir/key3.db Configuring the Domino DSAPI Filter Configure the DSAPI filter as explained here if you are installing the policy agent for IBM Lotus Domino 6.5.1: 1.
-
Configuring the Agent for Multiple Web Server Instances Configuring the Agent for Multiple Web Server Instances on the Same Computer Once you have installed an agent on your system, you can configure it for multiple web server instances on that system using a script that is copied to the system during the agent installation.
-
Using Secure Sockets Layer (SSL) with an Agent NOTE Be sure to use the unconfig_linux script to uninstall any agent that was installed using the config_linux script—you cannot use the GUI installation program to uninstall agents that were installed from the command line. The GUI uninstallation program must be executed only after unconfiguring all the existing agents installed using command-line unconfig script.
-
Using Secure Sockets Layer (SSL) with an Agent com.sun.am.trustServerCerts=false Installing the Root CA Certificate on the Remote Web Server The root CA certificate that you install on the remote web server must be the same as the one installed on the web server that runs Sun ONE Identity Server. To Install the Root CA Certificate You can use the certutil program to install the root CA Certificate on Apache web server. 1.
-
Setting the REMOTE_USER Server Variable Certificate Name Trust Attrubutes cert-name C,C,C p P c T C u w Valid peer Trusted peer (implies c) Valid CA Trusted CA to issue client certs (implies c) Trusted CA to certs(only server certs for ssl) (implies c) User cert Send warning Setting the REMOTE_USER Server Variable The REMOTE_USER server environment variable can be set to a Sun ONE Identity Server authenticated user or an anonymous user.
-
Shared Secret Encryption Utility The AMAgent.properties file contains a property named com.sun.am.policy.agents.client_ip_validation_enable, which by default is set to false. If you set this property to true, client IP address validation will be enabled for each in-coming request that contains an SSO token. If the IP address from which request was generated does not match the IP address issued for the SSO token, the request will be denied. This is essentially the same as enforcing a deny policy.
-
Uninstalling the Policy Agent Uninstalling the Policy Agent The following sections explain the procedure to uninstall a policy agent. Removing an Agent using the unconfig Script To remove an agent that was installed from the command line using the config_linux script, use the script unconfig_linux. The unconfig_linux script is located in the following directory: Agent_Install_Dir/agents/apache/bin Here is an example run of the unconfig_linux script. # .
-
Uninstalling the Policy Agent # ./uninstall_linux_apache_agent -nodisplay The following text is displayed: The uninstaller has detected the following agents on this system: 1. Agent 2.1 for Apache [/usr/local] 2. Exit Please select an installed agent from the following list: 2. Enter 1, to remove the product. The following text is displayed: Ready to Uninstall 1. Uninstall Now 2. Start Over 3. Exit Uninstallation 3. When prompted, What next? enter 1 to begin uninstallation.
-
Troubleshooting Troubleshooting Error message displayed during startup Apache server displays the following error message during startup after the agent is installed: Syntax error on line 1 of /etc/opt/SUNWam/agents/apache/config/_usr_local_apache_conf/dsame.conf: Invalid command 'LoadModule', perhaps mis-spelled or defined by a module not included in the server configuration .
-
Chapter 5 Single Sign-on Solution for Oracle Application Servers This chapter explains how you can deploy the Single Sign-on (SSO) solution for Oracle9iAS R1 and Oracle Application Server 10g using Sun ONE Identity Server.
-
Integration with Sun ONE Identity Server Integration with Sun ONE Identity Server Oracle 9iAS R1 or Oracle Application Server 10g can be integrated with Sun ONE Identity Server to achieve SSO functionality. In this type of integration, Sun ONE Identity Server sits in front of Login Server/Oracle SSO Server and provides user authentication only.
-
Deploying the Integrated SSO Solution For Oracle Application Server 10g Table 5-2 Software Requirements for the SSO Solution for Oracle Application Server 10g Software Supported Platforms Sun ONE Identity Server, version 6.1 Solaris 8 and 9 Web Policy Agent, version 2.1 Solaris 8 and 9 Oracle Application Server 10g Solaris 8 and 9 Deploying the Integrated SSO Solution The following sections present steps to deploy the integrated SSO solution for Oracle9iAS R1 and Oracle Application Server 10g.
-
Deploying the Integrated SSO Solution 2. Modify the default external authentication implementation, wwsso_auth_external, in the file ssoxnete.pkb. This file can be found in the directory $ORACLE_HOME/portal30/admin/plsql/sso. The only two functions that must be modified here are authenticate_user and get_Authentication_Name. The modified functions are documented below with the changes highlighted in bold.
-
Deploying the Integrated SSO Solution Code Example 5-2 Changes to the Function get_Authentication_Name BEGIN RETURN ’Sun ONE Identity Server’; END get_authentication_name; 3. Run ssonete.sql on the first computer to configure Login Server to operate in the external mode and load the new external authentication implementation for Sun ONE Identity Server, which was just saved to ssoxnete.pkb in the previous step.
-
Deploying the Integrated SSO Solution Deploying the Solution for Oracle Application Server 10g Follow these steps to deploy the SSO Solution for Oracle Application Server 10g. For this SSO solution, Oracle Portal was used as a partner application to verify the integration. 1. Install Oracle Application Server 10g including Oracle SSO Server and Oracle Portal. Make sure that Oracle Application Server 10g is installed using a fully qualified domain name (FQDN) for the server.
-
Deploying the Integrated SSO Solution 5. Install the policy agent, version 2.1 for Apache 1.3.29 on the same machine where Oracle SSO Server is running. The policy agent for Apache 1.3.29 can be downloaded from Sun at: http://wwws.sun.com/software/download/allproducts.html#id_server_agents Refer Chapter 2, “Policy Agents on Solaris and HP-UX” of this guide for detailed instructions to install the agent.
-
Deploying the Integrated SSO Solution Code Example 5-3 /** import import import import import import import import public SSOTPAMAuth.java java.io.PrintWriter; javax.servlet.http.HttpServletRequest; javax.servlet.http.HttpServletResponse; oracle.security.sso.ias904.toolkit.IPASAuthInterface; oracle.security.sso.ias904.toolkit.IPASAuthException; oracle.security.sso.ias904.toolkit.IPASUserInfo; oracle.security.sso.ias904.toolkit.IPASInsufficientCredException; java.net.
-
Deploying the Integrated SSO Solution 8. Add the following lines to your CLASSPATH environment variable: $ORACLE_HOME_INFRASTRUCTURE/j2ee/home/lib/servlet.jar:$/sso/lib/ipastoolkit.jar Note that $ORACLE_HOME_INFRASTRUCTURE must be replaced to point to the ORACLE_HOME directory where Oracle 10g Infrastructure is installed. 9. Go to the directory $ORACLE_HOME_INFRASTRUCTURE/j2ee/OC4J_SECURITY/applications/sso/web/ WEB-INF/classes and compile the file SSOTPAMAuth.
-
Configuring the Agent ❍ DEBUG: log details about program execution as well as errors, warnings, and messages The Oracle SSO Server debug file is defined by the property debugFile. The debug file provides debugging information to the Oracle SSO Server. For further information on how this file should be set, please refer to the Oracle Application Server 10g documentation. Additionally, if you want to see where Java exceptions and System.out.
-
Configuring the Agent do_sso_only Set this value to true so that the agent will just enforce user authentication (SSO) without enforcing policies (authorization). In this integration, Login Server handles authorization. com.sun.am.policy.agents.do_sso_only = true fqdnDefault This value is set by the agent installation program to the hostname where the agent is installed. Make sure that this value is a fully qualified domain name. It should be set to hostname.domain.
-
Configuring the Agent hostname where Sun ONE Identity Server is installed and port is the port where the amserver process is running. For example, if Sun ONE Identity Server is installed on the machine agent2.example.com and listens on port 58080, then this property should be set as follows: com.sun.am.policy.agents.cdcservletURL = http://agent2.example.com:58080/amserver/cdcservlet reverse_the_meaning_of_notenforcedList Set this value to true so that the notenforcedList becomes the enforced list. com.
-
Configuring the Agent logout.url This value specifies the logout URLs of Login Server and the partner applications. These URLs are never enforced by the agent. When the agent sees any of these URLs, it checks whether a valid session ID for the user still exists. If one does exist, the agent invalidates it and effectively logs the user out of Sun ONE Identity Server. The agent then passes the request onto Login Server so that the logout can be processed there.
-
Configuring the Agent Policy Agent for Oracle Application Server 10g You can configure the agent for Oracle Application Server 10g by modifying the following properties in the file AMAgent.properties: fetchHeaders Set this value to true so that additional policy response attributes can be introduced into the HTTP headers. com.sun.am.policy.am.fetchHeaders=true headerAttributes This value represents what policy attributes should be added to the HTTP header (if the value of fetchHeaders is true).
-
Configuring the Agent notenforcedList Since the property reverse_the_meaning_of_notenforcedList is set to true, this property becomes the list of URLs that the agent enforces (in other words, the URLs in this list require user authentication to grant access). For example, if the fully qualified hostname of the system where the Oracle 10g Infrastructure is installed is agent1.example.com and the port where the Oracle SSO Server is running is 7777, then this value should be set as follows: com.sun.am.policy.
-
Verifying the Deployment NOTE If additional Oracle Partner applications are used, then the logout pages for those applications must also be added to this list. logout.cookie_reset_list This property lists the cookies that need to be reset or removed upon log out from Oracle SSO Server. If Oracle Portal 3.0.9 is also used for the integration, cookies for both Oracle SSO Server and Oracle Portal must be present in this list as follows: com.sun.am.policy.agents.logout.
-
Troubleshooting Tips Troubleshooting Tips • If the integration fails, look for debugging clues from the log files for Login Server and the policy agent for Apache Web Server 1.3.29, and possibly those for Sun ONE Identity Server. • If you suspect that communication between the agent and Sun ONE Identity Server is problematic, replace the custom agent configuration file with the default version of the file, which protects all the elements on the protected port.
-
Troubleshooting Tips 146 Sun ONE Identity Server Policy Agents 2.
-
Chapter 6 Single Sign-On Solution for SAP Internet Transaction Server 2.0 This chapter describes the steps needed to integrate Sun ONE Identity Server into a Single Sign-On (SSO) environment with SAP’s Internet Transaction Server (ITS) 2.0. Topics in this chapter include: • Introduction • Architecture Details • Prerequisites • Installing PAS • Configuring the SAP Systems • Installing and Configuring the Policy Agent • SAP Template Files Introduction SAP ITS 2.
-
Architecture Details Sun ONE Identity Server along with Sun ONE Identity Server Policy Agent provides a natural integration between the SAP applications and non-SAP applications through the use of the SAP Pluggable Authentication Service (PAS). Architecture Details SSO is achieved through the use of PAS provided by SAP. PAS supports several types of external authentication methods, including X.509 Certificates, NTLM, NTPassword, LDAP, HTTP and dynamic libraries (DLL).
-
Installing PAS • Configure at least one SAP system to issue SAP SSO (SSO2 logon) tickets • Configure the other SAP systems to accept SSO2 logon tickets. • Ensure that the browser supports and accepts cookies because SSO2 logon tickets are saved as browser cookies. • Configure SAP Secure Network Connections (SNC) on the ticket-issuing SAP system, but not necessarily on the ticket-accepting system.
-
Configuring the SAP Systems Configuring the SAP Systems To set up the SSO environment, you need to configure at least one SAP system to issue SSO2 logon tickets and some other systems to accept the SSO2 logon tickets. The following sections provide steps to configure these systems. Configuring SAP R/3 System and the ITS instance As stated in the section Prerequisites, the connection between AGate and the ticket-issuing SAP system need to be configured for SNC.
-
Configuring the SAP Systems • 3. Entry for certificate activated Create a generic entry for AGate in the extended user access control list. This list is available in the table USRACLEXT: ❍ Enter an asterisk (*) in the User field. ❍ Enter AGate’s SNC name in the SNC name field 4. If you require external user name mapping, you need to maintain the mapping in the table USREXTID. 5. In the ITS component’s AGATE global.srvc file, configure these parameters: Table 6-2 Parameters in global.
-
Configuring the SAP Systems Table 6-3 Parameters in global.srvc Parameter Value ~password (space) ~cookies 1 ~mysapcomusesso2cookie 1 ~mysapcomnosso1cookie 1 ~mysapcomssonoits 1 ~mycomgetsso2cookie 1 ~secure 0 ~type 2 3. Set the following parameters in the application server’s profile on the ticket issuing SAP R/3 system by modifying DEFAULT.PFL: Table 6-4 Parameters in DEFAULT.
-
Configuring the SAP Systems Table 6-5 Parameters in global.srvc Parameter Value ~login (space) ~password (space) ~mysapcomusesso2cookie 1 2. On all of the component systems’ application servers, set the following profile parameters: Table 6-6 Parameters in the Component Systems’ Application Servers Parameter Value login/accept_sso2_ticket 1 login/create_sso2_ticket 0 3. Execute the Transaction SSO2 using the SSO administration wizard on the SAP R/3 system. 4.
-
Configuring the SAP Systems The sapdll.srvc service file must be configured as follows. This file must be located under SAP Install_dir/SAP/ITS/2.0/ADM/services. Table 6-7 Parameter Value ~login test ~password test ~theme 99 ~xgateway sapextauth ~extauthtype DLL ~extauthmodule \path_to_extauth.dll ~extid_type UN ~properties_file \path_to_paslibrary_config_file ~exitUrl http://s1is_host:port/amserver/UI/Logout ~client 000 ~language en ~mysapcomgetsso2cookie 1 ~redirectHost host.
-
Installing and Configuring the Policy Agent Installing and Configuring the Policy Agent Once you have configured the SAP R/3 systems and Sun ONE Identity Server, you can install Sun ONE Identity Server Policy Agent, version 2.1 for Sun ONE Web Server 6.0. For details on installing and configuring the policy agent, see Chapter 2 of this guide.
-
SAP Template Files Table 6-8 Required Parameters in global.srvc Parameter Value ~client 000 ~cookies 1 ~exiturl http://s1is_host:port/amserver/UI/Logout ~login (space) ~password (space) ~xgateway sapdiag ~xgateways sapxgadm,sapdiag,sapxgwfc,sapxginet,sapxgbc,sapextauth ~mysapcomgetsso2cookie 1 ~mysapcomusesso2cookie 1 ~mysapcomnosso1cookie 1 ~mysapcomssonoits 1 SAP Template Files Along with the SAP Service file (sapdll.
-
SAP Template Files Code Example 6-1 Template file login.html , ou=, o= // with this jscript example you can build your own distiguished name for your directory // // This example can be used, if no Base DN is set in the service file! // Remark: All values must not be case sensitive.
-
SAP Template Files Code Example 6-1 Template file login.html ‘end‘ ‘end‘ ‘if (~extauthtype == "LDAP")‘ ‘else‘ ‘end‘ Template file extautherror.
-
SAP Template Files Template file redirect.html Code Example 6-3 Template file redirect.html
160 content="0; URL=‘~ExtAuthRedirectURL‘"> Sun ONE Identity Server Policy Agents 2.
-
Appendix A AMAgent Properties The configuration of Web Policy Agents is largely determined by a set of properties present in the file AMAgent.properties. This appendix describes the properties in this file. NOTE All property names in this file are case-sensitive. com.sun.am.cookieName Description The name of the cookie passed between Sun ONE Identity Server and the SDK. Valid Values The default value is iPlanetDirectoryPro.
-
Valid Values The URL for the naming service Example com.sun.am.namingURL =http://nila.eng.example.com/amserver/namingservice com.sun.am.policy.am.loginURL Description This property stores the URL of the login page on the Identity Server. If you have a failover server, you can enter its URL after a space after the primary server URL. See example. Valid Values URL of the login page on the Identity Server. Example com.sun.am.policy.am.loginURL=http://nila.eng.example.
-
Valid Values URL of the Sun ONE Identity Server login page where the agent library must authenticate. Example com.sun.am.policy.am.library.loginURL = http://nila.eng.example.com:58080/amserver/UI/Login com.sun.am.logFile Description This property stores the name of the file to be used for logging messages. By default, the agent creates a directory called webserver_instance_dir under the /SUNWam/agents/debug directory (or the directory that you specify) and stores the log file in that directory.
-
com.sun.am.logLevels Description This property allows to set the logging level for the specified logging categories. Valid Values The value of the property should be in this format: [:][,[:]]* The currently used module names are: AuthService, NamingService, PolicyService, SessionService, PolicyEngine, ServiceEngine, Notification, PolicyAgent, RemoteLog and all. The “all” module can be used to set the logging level for all the logging modules.
-
com.sun.am.policy.am.username Description This property stores the user name to use for the Application authentication module. Valid Values UrlAccessAgent. This is a hardcoded value and must not be changed. Examples com.sun.am.policy.am.username = UrlAccessAgent com.sun.am.policy.am.password Description This property stores the encrypted password to use for the Application authentication module. Valid Values The shared secret between the agent and the Identity Server it protects.
-
Valid Values The absolute path to the directory. Example com.sun.am.sslCertDir = /opt/SUNWam/servers/alias com.sun.am.certDbPrefix Description Set this property if the certificate databases in the directory specified by the previous property have a prefix. Valid Values Any text string that you want to use as the prefix. This text will be prefixed to the name of the certificate databases. Example com.sun.am.certDbPrefix = prefix com.sun.am.
-
com.sun.am.notificationEnabled Description This policy determines if the policy SDK should use the Identity Server notification mechanism to maintain the consistency of its internal cache. If the value is false, then a polling mechanism is used to maintain cache consistency. Valid Values true or false. Example com.sun.am.notificationEnabled = true com.sun.am.notificationURL Description This property stores the URL to which notification messages should be sent if notification is enabled.
-
Valid Values true or false Example com.sun.am.policy.am.urlComparison.caseIgnore = true com.sun.am.policy.am.cacheEntryLifeTime Description This property determines the amount of time (in minutes) an entry remains valid after it has been added to the cache. The default value for this property is 3 minutes. Valid Values The amount of time in minutes Example com.sun.am.policy.am.cacheEntryLifeTime=3 com.sun.am.policy.am.
-
com.sun.am.policy.am.fetchHeaders Description This property enables/disables the additional policy response attributes to be introduced into the HTTP headers. The value can be true or false. Valid Values true or false. Example com.sun.am.policy.am.fetchHeaders=false com.sun.am.policy.am.headerAttributes Description This property determines the policy attributes to be added to the HTTP header.
-
com.sun.am.policy.am.loadBalancer_enable Description This property indicates whether a load balancer is used for Identity Server services. Valid Values true or false. Example com.sun.am.policy.am.loadBalancer_enable = false com.sun.am.policy.agents.version Description This property is meant for product versioning, please do not modify it. Example com.sun.am.policy.agents.version=2.1 com.sun.am.policy.agents.logAccessType Description This property allows to set the URL access logging level.
-
Example com.sun.am.policy.agents.logAccessType = LOG_DENY com.sun.am.policy.agents.agenturiprefix Description The agent uses this property to support some essential functions such as notification and post-data preservation. Valid Values Its value should be http://host.domain:port/agent_deployment_uri where host, domain and port are FQDN and port number of the web server where the agent is installed and agent_deployment_uri is the URI where the web server will look for agent's related HTML pages.
-
com.sun.am.policy.agents.instanceName Description This property stores the unique identifier for this agent instance. Valid Values This property is not currently used by the agent. Example com.sun.am.policy.agents.instanceName = unused com.sun.am.policy.agents.do_sso_only Description This property indicates whether the agent will just enforce user authentication (SSO) without enforcing policies (authorization). Valid Values true or false Example com.sun.am.policy.agents.do_sso_only = false com.sun.am.
-
Example com.sun.am.policy.agents.accessDeniedURL =http://nila.eng.example.com:58080/urlaccessdenied.html com.sun.am.policy.agents.urlRedirectParam=go to Description This property allows the user to configure the URL Redirect parameter for different auth modules. Valid Values By default this parameter is set to goto. Example com.sun.am.policy.agents.urlRedirectParam=goto com.sun.am.policy.agents.
-
NOTE The property com.sun.am.policy.agents.fqdnMap provides another way by which the agent can resolve malformed access URLs used by the users and take corrective action. This property can also be used to override the behavior of the agent in cases where necessary. For example, if it is required that no corrective action such as a redirect be used for users who access the web server resources using raw IP address, you can implement this by specifying a map entry such as: com.sun.am.policy.agents.
-
At runtime, the agent refers to this map in order to take corrective actions for users who may have typed in a URL with malformed hostname. If none of the entries in this map matches the hostname specified in the user request, the agent uses the com.sun.am.policy.agents.fqdnDefault property. WARNING: Invalid value for this property can result in the web server becoming unusable or the resources becoming inaccessible. NOTE This property can be used for creating a mapping for more than one hostname.
-
Example com.sun.am.policy.agents.cookie_reset_enabled=true com.sun.am.policy.agents.cookie_reset_list Description This property gives the comma separated list of cookies, that need to be included in the Redirect Response to Sun ONE Identity Server. This property is used only if the Cookie Reset feature is enabled. Valid Values The cookie details need to be specified in the following format name[=value][;Domain=value] If Domain is not specified, then the default agent domain is used to set the cookie.
-
com.sun.am.policy.agents.unauthenticatedUser Description This property stores the User Id to be returned if a user is accessing global allow page and is not authenticated. Valid Values Any user id that you want to display for the unauthenticated user. Example com.sun.am.policy.agents.unauthenticatedUser=anonymous com.sun.am.policy.agents.anonRemoteUserEna bled Description Use this property to enable/disable REMOTE_USER processing for anonymous users. Valid Values true or false Example com.sun.am.
-
Valid Values The list of URLs for which authentication is required. Wildcards can be used to define a pattern of URLs. The URLs specified may not contain any query parameters. Example com.sun.am.policy.agents.notenforcedList = SERVER_PROTO://SERVER_HOST:SERVER_PORTSERVER_DEPLOY_URI/UI/* SERVER_PROTO://SERVER_HOST:SERVER_PORTCONSOLE_DEPLOY_URI/* com.sun.am.policy.agents.
-
Example com.sun.am.policy.agents.notenforced_client_IP_address_list =194.164.10.2 com.sun.am.policy.agents.is_postdatapreserve_ enabled Description This property enables/disables POST data preservation. By default its value is set to false. Valid Values true or false. Example com.sun.am.policy.agents.is_postdatapreserve_enabled = false com.sun.am.policy.agents. postcacheentrylifetime Description This property determines the number of minutes any POST data will remain valid in the web server cache.
-
com.sun.am.policy.agents.cdsso-enabled Description This property indicates if the Cross-Domain Single Sign On URL is enabled. Valid Values true or false Example com.sun.am.policy.agents.cdsso-enabled=true com.sun.am.policy.agents.cdcservletURL Description This property indicates the URL the user will be redirected to after a successful login in a CDSSO scenario. Valid Values The URL to which the user will be redirected. Example com.sun.am.policy.agents.cdcservletURL = http://sina.eng.example.
-
Valid Values true or false Example com.sun.am.policy.agents.client_ip_validation_enable = false com.sun.am.policy.agents.logout.url Description This property indicates the application’s Logout URL This URL is not enforced by policy. When the agent sees this URL, it checks whether a valid session ID for the user still exists. If one does exist, the agent invalidates it, thus logging the user off Sun ONE Identity Server. Valid Values The logout URLs used by the protected applications. Example com.sun.am.
-
Example com.sun.am.policy.agents.logout.cookie_reset_list = iPlanetDirectoryPro;Domain=, iPlanetDirectoryPro;Domain=iplanet.com com.sun.am.policy.am.ldapattribute.cookiePrefix Description If a value is specified for this field, any cookie set will have its prefix set to this value. For example, if the property is set to MY_COOKIE_PREFIX_, for the LDAP attribute email, the cookie name will be MY_COOKIE_PREFIX_email.This property is used when the user wants to set the LDAP attribute through a COOKIE.
-
com.sun.am.policy.agents.getClientHostname Description This property indicates whether to get the client’s hostname through DNS reverse lookup for use in policy evaluation. Valid Values true or false. By default, the value is true if the property does not exist or if it is any value other than false. Example com.sun.am.policy.agents.getClientHostname = true com.sun.am.policy.am.ldapattribute.
-
com.sun.am.policy.am.fetchFromRootResource Description By default, when a policy decision for a resource is needed, the agent gets and caches the policy decision of the resource and all the resources from the root of the resource down, from the Identity Server. For example, if the resource is http://host/a/b/c, the root of the resource is http://host/. This is because more resources on the same path are likely to be accessed subsequently.
-
Index A agent cache updating 19 agents cache update hybrid cache 19 cache updates 19 failover protection 18 how they work 13 installation CLI-based 38 GUI-based 32 list 15 overview 13 properties file 24 supported platforms 15 uninstallation 57 on Windows 2000 92 Windows command-line 96 AMAgent Properties description 161 AMAgent properties location 24 Apache 1.3.
-
Section E E required version 17 encryption shared_secret on Windows 92 shared_secret on Linux 125 shared_secret on Solaris 55 Error Codes 189 L load balancer client IP address validation 54 client IP validation on Windows 91 F failover web server 18 FQDN setting 26 not-enforced IP Address list 21 not-enforced URL list 20 O I IBM HTTP Server configuring 46 Identity Server related information 12 installation verifying 28 installing agent on Windows 2000 agents installation on Windows 72 Apache agent
-
Section R R remote web server 18 REMOTE_USER variable on Linux 124 CLI mode 96 updating agent cache 19 V S SAP template files 156 SAP ITS agent shared libraries 155 SAP systems configuring for SSO 150 shared libraries SAP ITS agent 155 shared secret encryption on Linux 125 on Solaris 55 on Windows 92 Solaris patches 12 support 12 SSL Ready Apache agent 34 SSO for Oracle9iAS 129 Sun ONE support 12 support professional services 12 Solaris 12 Sun ONE 12 verifying installation 28 W web agent installation C
-
Section W 188 Sun ONE Identity Server Policy Agents 2.
-
Appendix B Error Codes This appendix lists the error codes you may encounter while installing and configuring Web Policy Agents. It also provides explanation for the codes. 0. AM_SUCCESS The operation completed successfully. 1. AM_FAILURE The operation did not complete successfully. Please refer to the log file for more details. 2. AM_INIT_FAILURE The C SDK initialization routine did not complete successfully. All the other APIs may be used only if the initialization went through successfully. 3.
-
5. AM_SESSION_FAILURE The session operation did not succeed. The operation may be any of the operations provided by the session API. 6. AM_POLICY_FAILURE The policy operation failed. Details of policy failure may be found in the log file. 7. This is a reserved error code. 8. AM_INVALID_ARGUMENT The API was invoked with one or more invalid parameters. Check the input provided to the function. 9. This is a reserved error code. 10. This is a reserved error code. 11.
-
18. AM_INVALID_SESSION The session token provided to the API was invalid. The session may have timed out or the token is corrupted. 19. AM_INVALID_ACTION_TYPE This exception occurs during policy evaluation, if such an action type does not exist for a given policy decision appropriately found for the resource. 20. AM_ACCESS_DENIED The user is denied access to the resource for the kind of action requested. 21. AM_HTTP_ERROR There was an HTTP protocol error while contacting the Identity server. 22.
-
27. AM_NOTIF_NOT_ENABLED This error is thrown if the notification registration API is invoked when the notification feature is disabled in the configuration file. 28. AM_ERROR_DISPATCH_LISTENER Error during notification registration. 29. AM_REMOTE_LOG_FAILURE This error code indicates that the service that logs messages to Sun ONE Identity Server has failed. The details of this error can be found in the agent’s log file. 192 Sun ONE Identity Server Policy Agents 2.
