| Web Policy Agents Guide |
Chapter 1
Read This FirstSunTM 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.
Topics in this chapter include:
In related documentation, you might see Sun ONE Identity Server referred to as Sun Java™ System Identity Server and Sun Java™ System Access Manager. These three names refer to the same product, but different versions.
Web Policy AgentsWeb Policy Agents protect content on web servers and web proxy servers from unauthorized intrusions. They control access to services and web resources based on the policies configured by an administrator.
Uses for Web Policy Agents
Policy agents are installed on web servers for a variety of reasons. Here are three examples:
- 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. At the same time, the agent restricts external partners from gaining access to the proprietary information.
In each of these situations, a system administrator must set up policies that allow or deny users access to content on a web server. For information on setting policies and for assigning roles and policies to users, see the Sun ONE Identity Server Administration Guide.
How an Agent Interacts With Sun ONE Identity Server
Figure 1-1 illustrates how a policy agent installed on a remote web server interacts with Sun ONE Identity Server. When a user points a browser to a particular URL on a protected web server, the following interactions take place:
- The agent intercepts the request and validates the existing authentication credentials. If the existing authentication level is insufficient, the appropriate Sun ONE Identity Server authentication service will present a login page. The login page prompts the user for credentials such as username and password.
- The authentication service verifies that the user credentials are valid. For example, the default LDAP authentication service verifies that the username and password are stored in Sun ONE Directory Server. You might use other authentication modules such as RADIUS and Certificate modules. In such cases, credentials are not verified by Directory Server but are verified by the appropriate authentication module.
- If the user’s credentials are properly authenticated, the policy agent examines all the roles assigned to the user.
- Based on the aggregate of all policies assigned to the user, the individual is either allowed or denied access to the URL.
Figure 1-1 An Agent’s Interaction With Sun ONE Identity Server
Supported ServersWeb 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
Before You Begin InstallationRead the following sections carefully before you start the installation program:
Java Runtime Environment 1.3.1 or Higher
You must have Java Runtime Environment (JRE) 1.3.1 or higher installed or available on a shared file system in order to run the graphical user interface (GUI) of the agent installation program. Currently, JRE 1.3.1 or any version higher is certified for use with the agent installation program. See "Installing From the Command Line" for more information.
If you are running the installation program on the Windows operating system, the installation program will install JRE 1.3.1 or higher if it does not detect JRE on the system.
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. A remote web server in a Sun ONE Identity Server deployment is any web server other than the one that runs Sun ONE Identity Server. It is “remote” relative to the Sun ONE Identity Server’s dedicated web server.
Configuring the Agent for Multiple Web Server Instances on the Same Computer
If you have multiple web server or proxy server instances installed on one computer system, you can configure the agent for each server instance.
For information on how to do this, see "Configuring the Agent for Multiple Web Server Instances."
Note
Only one instance of Microsoft IIS server can be installed per computer system; you cannot install multiple Microsoft IIS agents on the same computer system.
Providing Failover Protection for Agents
When you install a policy agent, you can specify a failover or backup web server for running Sun ONE Identity Server. This is essentially a high availability option. It ensures that if the web server that runs Sun ONE Identity Server service becomes unavailable, the agent can still process access requests through the secondary or the failover web server running Sun ONE Identity Server service.
To set up failover protection for the policy agent, you must first install two different instances of Sun ONE Identity Server on two separate web servers. See the detailed instructions in the Sun ONE Identity Server Installation and Configuration Guide to do this and then follow the instructions in the subsequent chapters of this guide to install the appropriate agent. The agent installation program will prompt you for the host name and port number of the failover web server that you have configured to work with Sun ONE Identity Server. The following property in the AMAgent.properties file stores the failover server name and port:
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.
Updating the Agent Cache
Each agent maintains a cache that stores the policies for every user’s session. The cache can be updated by either a cache expiration mechanism or a notification mechanism.
Cache Updates
The agent maintains a cache of all active sessions. Once an entry is added to the cache, it remains valid for a period of time after which the entry is considered expired and later purged.
The property com.sun.am.policy.am.cacheEntryLifeTime in AMAgent.properties determines the number of minutes an entry will remain in the agent cache. Once the interval specified by this property has elapsed, the entry is dropped from the cache. By default, the expiration time is set to three minutes.
Hybrid Cache Updates
In this mode, cache entry expiration still applies. In addition, the agent gets notified by the Sun ONE Identity Server service about session changes. Session changes include events such as session logout or a session timeout. When notified of a session or a policy change, the agent updates the corresponding entry in the cache. Apart from session updates, agents can also receive policy change updates. Policy changes include events such as updating, deleting, and creating policies.
Sun ONE Identity Server web policy agents have the hybrid cache update mode switched on by default. This is triggered by the property com.sun.am.policy.am.notificationEnabled in the AMAgent.properties file, which is set to true. When the property is set to false, the agent updates its cache through cache entry expiration mechanism only.
Restrictions due to firewalls, as well as the type of web server in use, might not allow notifications to work. In such cases, notification is turned off.
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.
In a normal deployment situation, policy changes on the server are frequent, which requires sites to accept a certain amount of latency for agents to reflect policy changes. Each site decides the amount of latency time that is acceptable for the site’s specific needs. When setting the cacheEntryLifeTime property, set it the lower of the two:
Not-Enforced URL List
The not-enforced URL list defines the resources that should not have any policies (neither allow nor deny) associated with them.
By default, the policy agent denies access to all resources on the web server that it protects. However, various resources available through a web server (such as a web site or an application) might not need to have any policy enforced. Common examples of such resources include the HTML pages and .gif images found in the home pages of web sites. The user should be able to browse such pages without authenticating. These resources need to be on the not-enforced URL list. The property com.sun.am.policy.agents.notenforcedList will be used for this purpose. Wild cards can be used to define a pattern of URLs. Space is the separator between the URLs mentioned in the list.
There can be a reverse scenario when all the resources on the web server, except a list of URLs, are open to any user. In that case, the property com.sun.am.policy.agents.reverse_the_meaning_of_notenforcedList would be used to reverse the meaning of com.sun.am.policy.agents.notenforcedList. If it is set to true (by default it is set to false), then the not-enforced URL list would become the enforced list.
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.reverse_the_meaning_of_notenforcedList= true
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 be enforced by the agent on the two URLs mentioned in the notenforcedList. All other resources will be accessible to any user.
Not-Enforced IP Address List
The com.sun.am.policy.agents.notenforced_client_IP_address_list property is used to specify a list of IP addresses. No authentication is required for the requests coming from these client IP addresses.
In other words, the agent will not enforce policies for the requests originating from the IP addresses in the Not-Enforced IP Address list.
Enforcing Authentication Only
The property com.sun.am.policy.agents.do_sso_only is used to specify if only authentication is enforced for URLs protected by the agent. If this property is set to true (by default it is set to false), it indicates that the agent enforces authentication only, without enforcing policies. After a user logs onto Identity Server successfully, the agent will not check for policies related to the user and the accessed URLs.
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.
This feature is configurable through two properties in the AMAgent.properties file. To turn this feature on and off, use the following property from the AMAgent.properties file:
com.sun.am.policy.am.ldapattribute.mode
This property can be set to one of the following values:
When set to NONE, the agent does not fetch LDAP attributes from the server and ignores the headerAttributes property. In the other two cases, agents fetch the attribute.
To configure the attributes that are to be forwarded in the HTTP headers, use the following property:
com.sun.am.policy.am.headerAttributes
Below is an example section in the AMAgent.properties file, which shows how this feature is used:
By default, some LDAP user attribute names and HTTP header names are set to sample values.
To find the appropriate LDAP user attribute names, check the following XML file on the machine where Sun ONE Identity Server is installed:
S1IS_Install_Dir/SUNWam/config/xml/amUser.xml
The attributes in this file could be either Identity Server user attributes or Identity Server dynamic attributes. For explanation of these two types of user attributes, refer Sun ONE Identity Server Administration Guide.
The attribute and HTTP header names that need to be forwarded must be determined by the end-user applications on the web server that the agent is protecting. After all, these applications are the consumers of the forwarded header values (the forwarded information is used for the customization and personalization of web pages).
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.properties file includes information for the following configurations:
The AMAgent.properties file also contains configuration information on advanced features, such as forwarding LDAP user attributes through HTTP headers and POST data preservation. The file has comments before each property; refer to the file for more details. Appendix A of this guide also provides detailed description of each of the properties in this file.
Table 1-2 provides the default location for AMAgent.properties on the various supported servers.
Table 1-2 Locating AMAgent.properties on Different Platforms
Server
Location
All supported UNIX web servers
/etc/opt/SUNWam/agents/WebServer/config/_PathInstanceName/
where WebServer refers to one of the following:
Sun ONE Web Server 6.0
Microsoft Windows 2000\Agent_Install_Dir\es6\config\_PathInstanceName\
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.50
Microsoft Windows Server 2003 EE\Agent_Install_Dir\apache\config\apache_PortNumber
Changing the AMAgent.properties file can have serious and far-reaching effects. Remember that you can safely change many of the properties in this file by simply reinstalling the agent. However, if you must make manual changes, keep the following in mind:
Setting the Fully Qualified Domain Name
To ensure appropriate user experience, it is necessary that the users access resources protected by the agent using valid URLs. The configuration property com.sun.am.policy.agents.fqdnDefault provides the necessary information needed by the agent to identify if the user is using a valid URL to access the protected resource. If the agent determines that the incoming request does not have 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. This property is set during the agent installation and must not be modified unless absolutely necessary to accommodate deployment requirements. An invalid value for this property can result in the web server becoming unusable or the resources becoming inaccessible.
The property com.sun.am.policy.agents.fqdnMap provides another way by which the agent can resolve partial or malformed access URLs and take corrective action. The agent gives precedence to the entries defined in this property over the value defined in the com.sun.am.policy.agents.fqdnDefault property. If none of the entries in this property matches the hostname specified in the user request, the agent uses the value specified for com.sun.am.policy.agents.fqdnDefault property.
The com.sun.am.policy.agents.fqdnMap property can be used for creating a mapping for more than one hostname. This may be the case when the web server protected by this agent is accessible by more than one hostname. However, this feature must be used with caution as it can lead to the web server resources becoming inaccessible.
This property can also be used to override the behavior of the agent in cases where necessary. The format for specifying the property com.sun.am.policy.agents.fqdnMap is:
com.sun.am.policy.agents.fqdnMap = [invalid_hostname|valid_hostname][,...]
where:
invalid_hostname is a possible invalid hostname such as partial hostname or an IP address that the user may provide .
valid_hostname is the corresponding valid hostname that is fully qualified. For example, the following is a possible value specified for hostname xyz.domain1.com:
com.sun.am.policy.agents.fqdnMap = xyz|xyz.domain1.com, xyz.domain1|xyz.domain1.com
This value maps xyz and xyz.domain1 to the FQDN xyz.domain1.com.
This property can also be used in such a way that the agent uses the name specified in this map instead of the web server’s actual name.
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.com
Cookie Reset Feature
This feature enables the policy agent to reset some cookies in the browser session while redirecting to Identity Server for authentication.
This feature is configurable through two properties in the AMAgent.properties file.
This property gives the comma-separated list of cookies that need to be reset in the response while redirecting to Identity Server for authentication. This property is used only if the Cookie Reset feature is enabled.
Cookie details must be specified in the following format:
name[=value][;Domain=value]
For example,
com.sun.am.policy.agents.cookie_reset_list=LtpaToken, cookie1=value1, cookie2=value2;Domain=example.com
Configuring CDSSO
The Cross Domain Single Sign-On (CDSSO) feature is configurable through three properties in the file AMAgent.properties. To turn this feature on or off, use the following property in AMAgent.properties:
com.sun.am.policy.agents.cdsso-enabled=true
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. This property is used only if CDSSO is enabled. If you leave this property blank, then the fully qualified cookie domain for the agent server will be used for setting the cookie domain. In such a case, it is a host cookie and not a domain cookie.
For more information on configuring the CDSSO component, refer Sun ONE Identity Server Installation Guide.
Verifying a Successful Installation
After installing a policy agent, it is a good practice to make sure that the agent is installed successfully. There are two things that you can check to verify a successful agent installation.
- Access some web content on the web server where the agent is installed. If the agent is installed correctly, you should see the Sun ONE Identity Server login page. Figure 1-2 is an example of the Identity Server login page that uses LDAP authentication.
Figure 1-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."
