内に含まその他のドキュメントサポート リソース |  PDF 文書ファイルをダウンロードする (833 KB)
Chapter 5 Managing Policy Agent 2.2 for IBM WebSphere Portal Server 5.1.0.2After installing Policy Agent 2.2 for IBM WebSphere Portal Server 5.1.0.2 and performing the required post-installation steps, you must adjust the agent configuration to your site's specific deployment. This chapter describes how to modify the agent accordingly. This chapter focuses on methods available for managing this J2EE agent, specifying the features you can configure and the tasks you can perform using each method as follows:
Key Features and Tasks Performed With the J2EE AMAgent.properties Configuration FileThe J2EE agent AMAgent.properties configuration file is a text file of configuration properties that you can modify to change J2EE agent behavior.  Caution – The content of the J2EE agent AMAgent.properties configuration file is very sensitive. Changes made can result in changes in how the agent works. Errors made can cause the agent to malfunction. This section describes the most important details of the J2EE agent AMAgent.properties configuration file, such as how specific properties can be modified to produce specific results. The topics described are typically those of greatest interest in real-world deployment scenarios. This section does not cover every property in the file. For a list and description of every property, see Appendix B, J2EE Agent AMAgent.properties Configuration File in Policy Agent 2.2. The following is the location of the AMAgent.properties file; PolicyAgent-base/AgentInstance-Dir/config For more information about the Policy Agent 2.2 directory structure, see J2EE Agent Directory Structure in Policy Agent 2.2.
Hot-Swap Mechanism in J2EE AgentsCertain property keys in the J2EE agent AMAgent.properties configuration file are hot-swap enabled. The value for these keys, when altered, are dynamically loaded by the agent such that it is not necessary to restart the deployment container for these changes to take effect. However, in cases where the property is explicitly identified as not enabled for hot-swap or in cases when the hot-swap mechanism is disabled on the system, the deployment container must be restarted for the changes to take effect. When the agent is deployed on a deployment container where Access Manager has been configured, the hot-swap mechanism is disabled by default and cannot be used. The hot-swap mechanism is controlled by the following configuration property: com.sun.am.policy.config.load.interval The valid values for this property is any unsigned integer including 0, which indicates the amount of time in seconds after which the agent will check for changes to the configuration. A setting of 0 disables the mechanism. By default, this mechanism is set to 0 and is, therefore, disabled. This mechanism is primarily provided to facilitate the development and testing of the application in a controlled development or test environment. The best practice, and this must be emphasized, is to disable this feature for production systems to ensure optimal utilization of system resources. Also, in a production system by disabling this feature, any accidental changes to the agent configuration will not take effect until the deployment container has been restarted. The property that controls the hot-swap mechanism itself is hot-swap enabled. This means that if the hot-swap mechanism is enabled and you change the value of this property, the new value will take effect after the last hot-swap load interval expires. This can be therefore used to dynamically disable the entire hot-swap system. For example consider the following situation:
When the value of the load interval is set to 0 during the startup of the deployment container, the hot-swap mechanism will be disabled and cannot be enabled without restarting the server and ensuring that this value is set to a value greater than 0. List Constructs in the J2EE AMAgent.properties Configuration FileCertain property keys in the J2EE agent AMAgent.properties configuration file are specified as lists. A list construct has the following format: <key>[<index>] = <value>
Note – Properties that are specified in this manner must follow the preceding format, otherwise they will be treated as invalid or missing properties. More than one property can be specified for this key by changing the value of <index>. This value must start from the number 0 and increment by 1 for each entry added to this list. If certain indices are missing, those indices are ignored and the rest of the specified values are loaded at adjusted list positions. Duplicate index values result in only one value being loaded in the indexed or adjusted indexed position. Example 5–1 Example of List Constructs in J2EE AMAgent.properties Filecom.sun.am.policy.example.list[0] = value0 com.sun.am.policy.example.list[1] = value1 com.sun.am.policy.example.list[2] = value2 Map Constructs in the J2EE AMAgent.properties Configuration FileCertain property keys in the J2EE agent are specified as maps. A map construct has the following format: <key>[<name>]=<value>
Note – Properties that are specified in this manner must follow the preceding format, otherwise they will be treated as invalid or missing properties. For a given <name>, there may only be one entry in the configuration for a given configuration key (<key>). If multiple entries with the same <name> for a given configuration key are present, only one of the values will be loaded in the system and the other values will be discarded. Example 5–2 Example of Map Constructs in J2EE AMAgent.properties Filecom.sun.am.policy.example.map[AL] = ALABAMA com.sun.am.policy.example.map [AK] = ALASKA com.sun.am.policy.example.map [AZ] = ARIZONA J2EE Property Configuration: Application Specific or GlobalCertain property keys in the J2EE agent AMAgent.properties configuration file can be configured for specific applications. Therefore, the agent can use different values of the same property for different applications as defined in the configuration file. Properties that are not configured for specific applications apply to all the applications on that deployment container. Such properties are called global properties. An application specific property has the following format: <key>[<appname>]=<value>
Note – When an application specific configuration is not present, the agent uses different mechanisms to identify a default value. Configurations are possible where the default value is used as the value specified for the same key without any application specific suffix [<appname>]. The following settings for a single property serve as an example: com.sun.identity.agents.config.example[Portal] = value1 com.sun.identity.agents.config.example[DefaultWebApp] = value2 com.sun.identity.agents.config.example = value3 The preceding example illustrates that for applications other than the ones deployed on the root context and the context /Portal, the value of the property defaults to value3. Application Specific configuration properties must follow the rules and syntax of the map construct of configuration entries. Example 5–3 Example of Application Specific and Global Configurationcom.sun.identity.agents.config.example[Portal] = value1 com.sun.identity.agents.config.example[BankApp] = value2 com.sun.identity.agents.config.example[DefaultWebApp] = value3 J2EE Agent Filter ModeNote – With Agent for IBM WebSphere Portal Server 5.1.0.2, “J2EE_POLICY” mode has an unconventional meaning. For this agent, J2EE_POLICY mode actually enables single sign-on (SSO) only. This is the only mode supported by this agent. Set the J2EE agent filter mode to J2EE_POLICY with Agent for IBM WebSphere Portal Server 5.1.0.2. The following configuration property in the J2EE agent AMAgent.properties configuration file is used to set the mode of the agent filter: com.sun.identity.agents.config.filter.mode Therefore set this property as follows: com.sun.identity.agents.config.filter.mode = J2EE_POLICY The J2EE_POLICY mode enables the agent filter and agent realm to work together with various Access Manager services to ensure SSO. Enabling Failover in J2EE AgentsThe agent allows basic failover capabilities. This helps you ensure that if the primary Access Manager instance for which the agent has been configured becomes unavailable, the agent will switch to the next Access Manager instance as specified in the J2EE agent AMAgent.properties configuration file. This setup can be achieved by implementing the following steps.
|
To Enable Failover in J2EE Agents
com.sun.identity.agents.config.profile.attribute.fetch.mode = REQUEST_ATTRIBUTE |
The key is the profile attribute name and the value is the name under which that attribute will be made available.
com.sun.identity.agents.config.profile.attribute.mapping[cn]=CUSTOM- Common-Name com.sun.identity.agents.config.profile.attribute.mapping[mail]=CUSTOM- Email com.sun.identity.agents.config.profile.attribute.fetch.mode = REQUEST_ATTRIBUTE com.sun.identity.agents.config.profile.attribute.mapping[] = |
Fetching Session Attributes in J2EE Agents
To obtain user-specific information by fetching profile attributes, assign a mode to the session attribute property and map the session attributes to be populated under specific names for the currently authenticated user. The following example first demonstrates how to assign the REQUEST_ATTRIBUTE mode for fetching session attributes and then demonstrates a way to map those attributes:
- Assigning a Mode to Session Attributes
-
com.sun.identity.agents.config.session.attribute.fetch.mode = REQUEST_ATTRIBUTE
The key is the session attribute name and the value is the name under which that attribute will be made available.
- Mapping Session Attributes
-
com.sun.identity.agents.config.session.attribute.mapping[UserToken]= CUSTOM-userid com.sun.identity.agents.config.session.attribute.fetch.mode = REQUEST_ATTRIBUTE com.sun.identity.agents.config.session.attribute.mapping[] =
Fetching Policy Response Attributes in J2EE Agents
To obtain user-specific information by fetching policy response attributes, assign a mode to the policy response attribute property and map the policy response attributes to be populated under specific names for the currently authenticated user. The following example first demonstrates how to assign the REQUEST_ATTRIBUTE mode for fetching policy response attributes and then demonstrates a way to map those attributes:
- Assigning a Mode to Policy Response Attributes
-
com.sun.identity.agents.config.response.attribute.fetch.mode = REQUEST_ATTRIBUTE
The key is the policy response attribute name and the value is the name under which that attribute will be made available.
- Mapping Policy Response Attributes
-
com.sun.identity.agents.config.response.attribute.mapping com.sun.identity.agents.config.response.attribute.fetch.mode = REQUEST_ATTRIBUTE com.sun.identity.agents.config.response.attribute.mapping[] =
Using this property for mapping policy response attributes, you can specify any number of attributes that are required by the protected application. For example, if the application requires the attributes cn and mail, and it expects these attributes to be available under the names COMMON_NAME and EMAIL_ADDR, then the configuration setting would be as follows:
com.sun.identity.agents.config.response.attribute.mapping[cn] = COMMON_NAME
com.sun.identity.agents.config.response.attribute.mapping[mail] = EMAIL_ADDR
Methods for Fetching Attributes in J2EE Agents
The attribute types can be fetched by different methods as follows:
-
HTTP Headers
-
Request Attributes
-
Cookies
Fetching Attributes as HTTP Headers
When the agent is configured to provide the LDAP attributes as HTTP headers, these attributes can be retrieved using the following methods on the javax.servlet.http.HttpServletRequest interface:
long getDateHeader(java.lang.String name)
java.lang.String getHeader(java.lang.String name)
java.util.Enumeration getHeaderNames()
java.util.Enumeration getHeaders(java.lang.String name)
int getIntHeader(java.lang.String name)
The property that controls the parsing of a date value from an appropriate string as set in the LDAP attribute is the following:
com.sun.identity.agents.config.attribute.date.format
This property defaults to the value EEE, d MMM yyyy hh:mm:ss z and should be changed as necessary.
Multi-valued attributes can be retrieved as an instance of java.util.Enumeration from the following method:
java.util.Enumeration getHeaders(java.lang.String name)
Fetching Attributes as Request Attributes
When the agent is configured to provide the LDAP attributes as request attributes, the agent populates these attribute values into the HttpServletRequest as attributes that can later be used by the application as necessary. These attributes are populated as java.util.Set objects, which must be cast to this type before they can be successfully used.
Fetching Attributes as Cookies
When the agent is configured to provide the LDAP attributes as cookies, the necessary values are set as server specific cookies by the agent with the path specified as “/.”
Multi-valued attributes are set as a single cookie value in a manner that all values of the attribute are concatenated into a single string using a separator character that can be specified by the following configuration entry:
com.sun.identity.agents.config.attribute.cookie.separator
One of the tasks of the application is to parse this value back into the individual values to ensure the correct interpretation of the multi-valued LDAP attributes for the logged on user.
When you are fetching attributes as cookies, also use the cookie reset functionality to ensure that these cookies get cleaned up from the client browser when the client browser’s session expires. For more information, see Using Cookie Reset Functionality in J2EE Agents.
Common Attribute Fetch Processing Related Properties
This section lists the most common configuration properties that are used to influence attribute fetching.
- com.sun.identity.agents.config.attribute.cookie.separator
-
This property allows you to assign a character to be used to separate multiple values of the same attribute when it is being set as a cookie. This property is set in the following manner:
com.sun.identity.agents.config.attribute.cookie.separator = |
- com.sun.identity.agents.config.attribute.cookie.encode
-
This property is a flag that indicates if the value of the attribute should be URL encoded before being set as a cookie. This property is set in the following manner:
com.sun.identity.agents.config.attribute.cookie.encode = true
- com.sun.identity.agents.config.attribute.date.format
-
This property allows you to set the format of date attribute values to be used when the attribute is set to HTTP header. This format is based on the definition as provided in java.text.SimpleDateFormat. This property is set in the following manner:
com.sun.identity.agents.config.attribute.date.format = EEE, d MMM yyyy hh:mm:ss z
Configuring FQDN Handling in J2EE Agents
To ensure appropriate user experience, the use of valid URLs by users to access resources protected by the agent must be enforced. This functionality is controlled by three separate properties:
- com.sun.identity.agents.config.fqdn.check.enable
-
Enables FQDN
- com.sun.identity.agents.config.fqdn.default
-
Stores the default FQDN value
- com.sun.identity.agents.config.fqdn.mapping[]
-
Sets FQDN mapping
The configuration property for the default FQDN provides the information required 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 now changed by the agent to a fully qualified domain name (FQDN) as per the value specified in this property.
The property FQDN Map 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 entries defined in this property over the value defined in the default FQDN property. If none of the entries in this property matches the hostname specified in the user request, the agent uses the value specified for default FQDN property to take the necessary corrective action.
The FQDN Map property can be used for creating a mapping for more than one hostname. This can be done when the deployment container protected by this agent can be accessed using more than one hostname. As an example, consider a protected deployment container that can be accessed using the following host names:
-
www.externalhostname.com
-
internalhostname.interndomain.com
-
IP address
In this case, assuming that www.externalhostname.com is the default FQDN, then the FQDN Map can be configured as follows to allow access to the application for users who will use the hostname internalhostname.interndomain.com or the raw IP address, say 192.101.98.45:
com.sun.identity.agents.config.fqdn.mapping [internalhostname.interndomain.com] = internalhostname.interndomain.com |
com.sun.identity.agents.config.fqdn.mapping [192.101.98.45] = 192.101.98.45
Using Cookie Reset Functionality in J2EE Agents
The agent allows you to reset certain cookies that may be present in the user’s browser session if the user’s Access Manager session has expired. This feature is controlled by the following configuration properties:
com.sun.identity.agents.config.cookie.reset.enable = false com.sun.identity.agents.config.cookie.reset.name[0] = com.sun.identity.agents.config.cookie.reset.domain[] = com.sun.identity.agents.config.cookie.reset.path[] =
The preceding four properties can be used to specify the exact details of the cookie that should be reset by the agent when a protected resource is accessed without a valid session.
The com.sun.identity.agents.config.cookie.reset.name property specifies a list of cookie names that will be reset by the agent when necessary. Each entry in this list can correspond to a maximum of one entry in the com.sun.identity.agents.config.cookie.reset.domain property and the com.sun.identity.agents.config.cookie.reset.path property, both of which are used to define the cookie attributes - the domain on which a particular cookie should be set and the path on which it will be set.
When using this feature, ensure that the correct values of the domain and path are specified for every cookie entry in the cookie list. If these values are inappropriate, the result might be that the cookie is not reset in the client browser.
When a cookie entry does not have an associated domain specified in the domain map, it is handled as a server cookie. Similarly, when a cookie entry does not have a corresponding path entry specified, the anticipated cookie path is “/.”
Enabling Port Check Functionality in J2EE Agents
In situations when Access Manager and the deployment container are installed on the same system but on different ports, certain browsers may not send the HOST header correctly to the agent in situations where there are redirects involved between Access Manager Authentication Service and the agent. In such situations, the agent, relying on the availability of the port number from the deployment container, might misread the port number that the user is trying to access.
When such a situation occurs, it can have a severe impact on the system since the agent now senses a resource access that in reality did not occur and consequently the subsequent redirects as well as any policy evaluations may fail thereby making the protected application inaccessible to the end user.
This situation can be controlled by enabling port check functionality on the agent. This is controlled by the following configuration property:
com.sun.identity.agents.config.port.check.enable
When this property is set to true, the agent verifies the correctness of the port number read from the request against its configuration. The configuration that provides the reference for this checking is set by the following property:
com.sun.identity.agents.config.port.check.setting
This property allows the agent to store a map of various ports and their corresponding protocols. When the agent is installed, this map is populated by the preferred port and protocol of the agent server as specified during the installation. However, if the same agent is protecting more than one HTTP listeners, you must add that information to the map accordingly.
When the agent discovers an invalid port in the request, it takes corrective action by sending some HTML data to break the redirection chain so that the browser can reset its HOST header on the subsequent request. This content is read from the file that resides in the locale directory of agent installation. The name of the file is controlled by the following property:
com.sun.identity.agents.config.port.check.file
This property can also be used to specify the complete path to the file that may be used to achieve this functionality. This file contains special HTML that uses a META-EQUIV REFRESH tag in order to allow the browser to continue automatically when the redirect chain is broken. Along with this HTML, this file must contain the string am.filter.request.url, which is dynamically replaced by the actual request URL by the agent.
You can modify the contents of this file or specify a different file to be used, if necessary, so long as it contains the am.filter.request.url string that the agent can substitute in order to construct the true request URL with the correct port. The contents of this file should be such that it should either allow the user to automatically be sent to this corrected location or let the user click on a link or a button to achieve the same result.
Key Features and Tasks Performed With the J2EE agentadmin Program
The agentadmin program is a utility used to perform a variety of tasks from required tasks, such as installation to optional tasks, such as displaying version information. This section summarizes the tasks that can be performed with the agentadmin program. Many of the tasks performed with this program are related to installation or uninstallation. For detailed information about the options available with this program, see Role of the agentadmin Program in a J2EE Agent for Policy Agent 2.2.
In this section, the options are listed for your quick review to help you get a sense of how the agentadmin program fits in with the other methods of managing J2EE agents, which are all discussed in this chapter.
The location of the agentadmin program is as follows:
PolicyAgent-base/bin
The following table lists options that can be used with the agentadmin command and gives a brief description of the specific task performed with each option.
Note –
In this section, the options described are the agentadmin program options that apply to all J2EE agents. Options that only apply to specific J2EE agents are relatively uncommon and are described where necessary within the corresponding J2EE agent guide.
Table 5–1 The agentadmin Program: Supported Options
|
Option |
Task Performed |
|---|---|
|
--install |
Installs a new agent instance |
|
--uninstall |
Uninstalls an existing Agent instance |
|
--listAgents |
Displays details of all the configured agents |
|
--agentInfo |
Displays details of the agent corresponding to the specified agent IDs |
|
--version |
Displays the version information |
|
--encrypt |
Encrypts a given string |
|
--getEncryptKey |
Generates an Agent Encryption key |
|
--uninstallAll |
Uninstalls all agent instances |
|
--getUuid |
Retrieves a universal ID for valid identity types |
|
--usage |
Displays the usage message |
|
--help |
Displays a brief help message |
Key Features and Tasks Performed With the J2EE Agent API
The agent runtime provides access to all the Access Manager application program interfaces (API) that can be used to further enhance the security of the application. Besides the Access Manager API, the agent also provides a set of API that allow the application to find the SSO token string associated with the logged-in user. These API can be used from within the web container or the EJB container of the deployment container. These are agent utility API. However, an equally viable option is to use client SDK public API directly to fetch the SSO token.
Note –
Certain containers, such as Apache Tomcat Servlet/JSP Container and IBM WebSphere Portal Server do not have an EJB container. Hence, the EJB related agent API would not be applicable for such containers.
The subsections that follow illustrate the available agent API that can be used from within an application. The J2EE agent API have changed in Policy Agent 2.2 as explained in this section. This section includes an example of the new API in use, see Usage of New J2EE Agent API in Policy Agent 2.2.
Class AmFilterManager
com.sun.identity.agents.filter.AmFilterManager
Available API for Class AmFilterManager
-
public static com.sun.identity.agents.filter.AmSSOCache getAmSSOCacheInstance() throws com.sun.identity.agents.arch.AgentException
Note –Deprecated: This method has been deprecated. The best practice is not to use this method, but to use the new public API for this AmFilterManager class as follows:
public static com.sun.identity.agents.filter.IAmSSOCache getAmSSOCache()
This method returns an instance of Class AmSSOCache, which can be used to retrieve the SSO token for the logged-in user. This method can throw AgentException if an error occurs while processing this request.
-
public static com.sun.identity.agents.filter.IAmSSOCache getAmSSOCache()
This method returns an instance of IAmSSOCache interface, which can be used to retrieve the SSO token for the logged-in user.
Interface IAmSSOCache
com.sun.identity.agents.filter.IAmSSOCache
Available API for Interface IAmSSOCache
public String getSSOTokenForUser(Object ejbContextOrServletRequest)
This method can be used to retrieve the SSO token for the logged-in user. If called from the web tier, this method passes an instance of javax.servlet.http.HttpServletRequest as an argument. If called from the EJB tier, this method passes an instance of javax.ejb.EJBContext as an argument. This method eradicates the necessity of using two separate methods in AmSSOCache to retrieve the SSO token.
Class AmSSOCache
com.sun.identity.agents.filter.AmSSOCache
Note –
Deprecated: This class and its methods have been deprecated. The best practice is not to use the methods in this class, but to use the unified API in com.sun.identity.agents.filter.IAmSSOCache.
Available API for Class AmSSOCache
-
public java.lang.String getSSOTokenForUser(javax.servlet.http.HttpServletRequest request)
Note –Deprecated: This method has been deprecated as explained in the Note in Class AmSSOCache.
This method returns the SSO token for the logged-in user whose request is currently being processed in the web container within the deployment container. This method can return null if the requested token is not available at the time of this call.
-
public java.lang.String getSSOTokenForUser(javax.ejb.EJBContext context)
Note –Deprecated: This method has been deprecated as explained in the Note in Class AmSSOCache.
This method returns the SSO token for the logged on user whose request is currently being processed in the deployment container’s EJB tier. This method can return null if the requested token is not available at the time of this call.
Usage of New J2EE Agent API in Policy Agent 2.2
The following example demonstrates the new J2EE agent API in use.
Example 5–4 Usage of New J2EE Agent API
-
Web Tier Use Case:
String ssotoken = AmFilterManager.getAmSSOCache().getSSOTokenForUser(HTTPRequest);
-
EJB Tier Use Case:
String ssotoken = AmFilterManager.getAmSSOCache().getSSOTokenForUser(EJBContext);
Caution – This public API can only retrieve the SSOToken object in EJB context if the value of the following property in the J2EE agent AMAgent.properties file is set to true as shown:
com.sun.identity.agents.config.user.principal = true