|
| Sun ONE Identity Server Policy Agent Guide |
This chapter provides a brief overview of Sun ONE Identity Server Policy Agents for web and web proxy servers, as well as some concepts you will need to understand before proceeding with the Installation program. The information in this chapter is common to Solaris, Windows and Linux operating systems.
Topics include:
How Policy Agents Work
Sun ONE Identity Server 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 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 6.0
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 Servers
Sun ONE Identity Server Policy Agents support the following servers running on the Solaris 8 operating system:
- Sun ONE Web Server 6.0 SPx
- Sun ONE Web Server 4.1 SP8
- Sun ONE Web Proxy Server 3.6 (in reverse proxy mode)
- Apache 1.3.26
- IBM HTTP Server 1.3.19
- Lotus Domino 5.0.10
Sun ONE Identity Server Policy Agents support the following servers running on the Solaris 9 operating system:
- Sun ONE Web Server 6.0 SPx
- Apache 1.3.26
Sun ONE Identity Server Policy Agents support the following server running on Red Hat Linux 7.2 operating system:
- Apache 1.3.26
Sun ONE Identity Server Policy Agents support the following servers running on the Windows 2000 operating system:
- Microsoft IIS 5.0
- Sun ONE Web Server 6.0 SPx
- Lotus Domino 5.0.10
Sun ONE Identity Server Policy Agents support the following server running on Windows NT 4.0 Service Pack 6:
- Microsoft IIS 4.0
Before You Begin Installation
You should be familiar with the following concepts before you start the Installation program:
- Java Runtime Environment 1.3.1
- The Web Server that Runs Sun ONE Identity Server Services vs. Remote Web Servers
- Configuring Agent for Multiple Web Server Instances on the Same Computer System
- Providing Failover Protection for Sun ONE Identity Server Agents
- Updating the Agent Cache
- Global Not-Enforced URL List
- Global Not-Enforced IP Address List
- Enforcing Authentication Only Without Enforcing Policies
- Forwarding LDAP User Attributes via HTTP Headers
- The AMAgent.properties File
- Setting the Fully Qualified Domain Name
- Cookie Reset Feature
- Configuring CDSSO
- Verifying a Successful Installation
Java Runtime Environment 1.3.1
You must have the Java Runtime Environment (JRE) 1.3.1 installed or available on a shared file system in order to run the graphical user interface (GUI) version of the Agent Installation program. Currently, JRE 1.3.1 or any version higher is certified for use with the Agent Installation program.See "Installation Using the Command-Line" for more information.
If you are running the Windows operating system, the Installation program will install JRE 1.3.1 if it is not detected.
The Web Server that Runs Sun ONE Identity Server Services vs. 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 6.0. 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 Agent for Multiple Web Server Instances on the Same Computer System
If you have multiple Web servers or Proxy servers installed on one computer system, you can install a different agent for each server or server instance.
For more information, see "Configuring 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 Sun ONE Identity Server Agents
When you install a Policy Agent, you can specify a failover or backup web server for running the 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 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, then follow the instructions in the subsequent sections 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 you 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.siroe.com:58080/amserver/UI/Login http://failover_Identity _Server.siroe.com:58080/amserver/UI/Login
The failover server name is configurable after it has been set during the installation. It is the second entry in this property following the primary Sun ONE Identity Server login URL separated by a space.
Note The protocol (for example, http or https) must be the same for both primary web server and the failover web server.
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 notification mechanism.
Cache Updates
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 alive 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 log-out or a session time-out. When notified of a session or policy change, the agent updates the corresponding entry in the cache. Apart from session updates, agents may also receive policy change updates. Policy changes include events such as a updating policy, deletion, or creation.
Sun ONE Identity Server Policy Agents will have the hybrid cache update mode switched on by default. This is triggered by the property com.sun.am.policy.am.notificationEnabled and is set to true in the AMAgent.properties file. 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, may not allow notifications to work in certain situations. In such cases, cache entry expiration is the only way an agent can update its cache.
Note The notification support is not available in the following instances:
Global Not-Enforced URL List
The global not-enforced URL list defines the resources that should not have any policies (either allow or deny) associated with them.
By default, policy agent denies access to all resources for the web server that it protects. However, various resources available through a web server (such as a web site or 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 for a web site. The user should be able to browse such pages without authenticating. These resources need to be on the global 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.
The reverse scenario would be when all resources for the web server are open to any users except a list of URLs. 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 global not-enforced URL list would become global 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.siroe.com:80/welcome.html http://mycomputer.siroe.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.siroe.com:80/welcome.html http://mycomputer.siroe.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 given access to any user.
Global 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 protect any web server resources against the accesses coming from the IP addresses in the list.
Enforcing Authentication Only Without Enforcing Policies
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 an user logs into the 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
Sun ONE Identity Server 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 Sun ONE Identity Server 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 AMAgent.properties file. To turn this feature on and off, use the following AMAgent.properties file property:
com.sun.am.policy.am.fetchHeaders
By default, this property is set to false, and the feature turned off. To turn on attribute forwarding, set this property to true. To configure the attributes that are to be forwarded in the HTTP headers, use the AMAgent.properties file property
com.sun.am.policy.am.headerAttributes
Below is an example section in the AMAgent.properties file which shows how this feature is used:
#
# 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.
#
# NOTE: In most cases, in a destination application where a
# "http_header_name" shows up as a request header, it will be
# prefixed by HTTP_, and all lower case letters will become upper
# case, and any - will become _; For example, "common-name" would
# become "HTTP_COMMON_NAME"
#
com.sun.am.policy.am.headerAttributes=cn|common-name,ou|organiza tional-unit,o|organization,mail|email,employeenumber|employee-nu mber,c|country
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 the Sun ONE Identity Server server is installed:
S1IS_Install_Dir/SUNWam/config/xml/amUser.xml
The attributes in this file could be either Sun ONE Identity Server User attributes or Sun ONE 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).
Note This feature is not available for the Sun ONE Web Proxy Server Agent.
The AMAgent.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:
- debugging
- policy agent
- FQDN map
- Sun ONE Identity Server services
- service and agent deployment descriptors
- session failover
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 AMAgent.properties file has comments before each property; refer to the file for more details.
Table 1-1 provides the default location for AMAgent.properties on the various supported servers.
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 re-installing the agent. However, if you must make manual changes, keep the following in mind:
- Make a backup copy of this file before you make changes.
- Trailing spaces are significant; use them judiciously.
- Use forward slash (/) to separate directories, not backlash (\). This holds true even on Windows systems.
- Spaces in the Windows file names are allowed.
Note If you do make changes to the AMAgent.properties file, you must restart the web server to make your changes take effect.
Setting the Fully Qualified Domain Name
To ensure appropriate user experience, it is necessary to enforce that the users use valid URLs to access resources protected by the agent. 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 property is a required configuration property without which the Web server may not startup correctly. This property is set during the agent installation and need not be modified unless absolutely necessary to accommodate deployment requirements. 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 malformed access URLs used by the users 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 match 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, the use of this feature must be done 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. 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, it can be implemented by specifying a map entry such as:
com.sun.am.policy.agents.fqdnMap=IP|IP
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 the user may use such as partial hostname or an IP address.
valid_hostname is the corresponding valid hostname which 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.
Cookie Reset Feature
This feature enables the Identity Server Policy Agent to reset some cookies in the browser session while redirecting to Identity Server for authentication. Currently, this feature is available only for the Policy Agents for IBM HTTP Server and Lotus Domino.
This feature is configurable through two properties in the AMAgent.properties file.
- Enable Cookie Reset
com.sun.am.policy.agents.cookie_reset_enabled=true
This property must be set to true, if this agent needs to reset cookies in the response while redirecting to Identity Server for authentication. By default, this is set to false.
- Cookie List
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 need to 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=siroe.com
Configuring CDSSO
The Cross Domain Single Sign-On (CDSSO) feature is configurable through two 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 feature is turned off. To turn on CDSSO, set this property to true. Set the URL where CDSSO is installed by specifying the URL in the following property:
com.sun.am.policy.agents.loginURL = http://mycomputer.domain:port/amcdsso/cdsso
For more information on configuring 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 was installed successfully. There are two things 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 Sun ONE Identity Server login page that uses LDAP authentication.
- Check the file AMAgent.properties. Make sure that each property is set properly.
Figure 1-2 Sun ONE Identity Server Login Page
