J2EE Policy Agents Guide |
Chapter 3
Agent ConfigurationThis chapter explains how to enable and use various features of J2EE Policy Agents and also provides a complete description of the configuration parameters that are present in the agent configuration file AMAgent.properties.
The following topics are included in this chapter:
Once the agent is installed on your system, you must perform certain agent configuration tasks to take advantage of a rich set of features that can customize the agent deployment for the benefit of the deployed and protected applications, the performance of the entire system, and for fine-tuning your security policies as per your security requirements. Some of the agent features such as Web-Tier declarative security support require you to modify this configuration in order to enable them.
The agent configuration is largely controlled by a set of properties in a file called AMAgent.properties. For Solaris platform installations, this file is located under a unique directory under /etc/opt/SUNWam/j2ee_agents directory based on the instance of application server that it applies to. On other platforms this file is located under a unique directory under Agent_Install_Dir/j2ee_agents/config directory.
General Notes on the Agent Configuration FileThis section describes a few details that must be noted when referring to the agent configuration.
Hot-Swap Mechanism
Certain properties in this configuration file are hot-swap enabled. The value of these properties, when altered, are dynamically loaded by the agent such that it is not necessary to restart the application server 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 application server must be restarted for the changes to take effect.
List Constructs in the Configuration File
Certain properties in the AMAgent.properties file are specified as lists. A list construct is defined as follows:
Format:
<key>[<index>]=<value>
Where
key is the configuration key
index is a positive number starting from 0 that increments by 1 for every value specified in this list.
value is one of the values specified in this list.
Example
com.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 Configuration File
Certain property keys in the AMAgent.properties file are specified as Maps. A Map construct is defined as follows:
Format
<key>[<name>]=<value>
Where
key is the configuration key
name is a string that forms the lookup key as available in the Map
value is the value associated with the name in the Map
Example
com.sun.am.policy.example.map[AL] = ALABAMA
com.sun.am.policy.example.map[AK] = ALASKA
com.sun.am.policy.example.map[AZ] = ARIZONA
Agent Filter ModesThe agent installation program as well as the agent configuration file allow you to set the agent filter in one of the five available modes of operation. Depending upon your security requirements, you may choose the mode that best suits your requirement. The following configuration property is used to control the mode of the agent filter:
com.sun.am.policy.amFilter.mode
The value for this property can be one among the following:
Regardless of what mode the agent filter is operating in, the agent realm will continue to function, if configured. This can therefore lead to a situation where the agent realm component may malfunction or may result in the negative evaluation of J2EE security policies configured in the application’s deployment descriptors or being used through the J2EE programmatic security API. To avoid this, you may disable the agent realm component, if necessary. The sections that follow describe the different agent filter modes and also tell you how to disable the agent realm.
Agent Filter Mode - NONE
This mode of operation effectively disables the agent filter. When operating in this mode, the agent filter allows all requests to pass through. However, if the logging is enabled, the agent filter will still log all the requests that it intercepts.
Although this mode disables the agent filter from taking any action on the incoming requests other than logging, it has no effect on the agent realm that may still be configured in your application server and may get invoked by the deployed application if the deployed application has J2EE security policies in its descriptors or uses programmatic security. With the agent filter disabled, these applications will fail to evaluate the J2EE security policies correctly and as a result the deployed application may malfunction.
In order to fully disable the agent, you must therefore ensure that the agent realm is not active. Refer to the section Disabling the Agent Realm to find out how the agent realm can be disabled for your agent installation.
Once you have disabled the agent realm and the filter mode is set to NONE, it is functionally equivalent to not having the agent in your system at all.
Note
When the agent filter is operating in this mode, any declarative J2EE security policy or programmatic J2EE security API calls will return a negative result regardless of the user.
Agent Filter Mode - SSO_ONLY
This is the least restrictive mode of operation for the agent filter. In this mode, the agent simply ensures that all users who try to access protected web resources are authenticated using Sun ONE Identity Server’s authentication service. In this mode of operation the agent realm is not used and can be safely disabled. Refer to the section on Disabling the Agent Realm to find out how the agent realm can be disabled for your agent installation.
Note
When operating in this mode, any declarative J2EE security policy or programmatic J2EE security API calls evaluated for the application will result in negative evaluation.
Agent Filter Mode - J2EE_POLICY
In this mode, the agent filter and agent realm together work with various Sun ONE Identity Server services to ensure the correct evaluation of J2EE Policies. These policies may be configured using the declarative security in the application’s deployment descriptors, or may be implicit in the code of the application in the cases where it uses the J2EE programmatic security APIs. Any URL policies defined in Sun ONE Identity Server do not take effect in this mode of filter operation.
In case the deployed application uses declarative security in the web-tier, you must configure the agent to enable this feature. Refer to the section on Enabling Web-Tier Declarative Security to find out more details on how to enable this feature. When running in the J2EE_POLICY mode, the agent ensures that the security principal is set in the system for every authorized user access.
In the J2EE_POLICY mode, the agent will not enforce any applicable URL Policies as defined in Identity Server.
Agent Filter Mode - URL_POLICY
In this mode, the agent filter is used to enforce various URL policies that may be defined in Sun ONE Identity Server. This mode does not require the agent realm to be functional and can therefore be safely disabled. Refer to the section on Disabling the Agent Realm to find out how the agent realm can be disabled.
Agent Filter Mode - ALL
This is the most restrictive mode of the agent filter. In this mode, the filter enforces both J2EE policies and URL policies as defined in Sun ONE Identity Server. This mode of operation requires that the agent realm be configured in the Application Server. When running in the ALL mode, the agent ensures that the security principal is set in the system for every authorized access.
It is strongly recommended that this mode of operation be used for deployed production systems.
Disabling the Agent RealmIn certain situations you may want to disable the agent realm to better suit your deployment requirements. The following sections explain how you can do this for your application server:
Agent for Sun ONE Application Server 7.0
Use the following steps to disable the agent realm for Sun ONE Application Server 7.0:
- Log in to the Sun ONE Application Server Administration Server.
- Click on the node for the server name on which the agent has been installed. This expands the server menu on the left hand panel.
- In the expanded tree under the server name node, click on the Security node. This displays the general security settings for this server instance on the right hand panel.
- On the right hand panel, change the value of Default Realm to file. If the application server was configured to use a different realm than file before the agent was installed, you must choose that value from the pull-down menu instead.
- Restart your Application Server to ensure the changes take effect.
The above mentioned steps disable the agent realm for Sun ONE Application Server. To enable the agent realm again, follow steps 1-3 and in step 4 change the value of Default Realm to agentRealm.
Agent for BEA WebLogic Server 6.1 SP2
Use the following steps to disable the agent realm for BEA WebLogic Server.
- Log in to the WebLogic Administration Console.
- On the left pane click the Security node. The console displays the Security configuration of the WebLogic Server in the right pane.
- In the right pane, click the Filerealm tab. The console displays the details of the current File Realm.
- In the form that is displayed on the right pane, under Caching Realm, select the value none from the pull down menu and click on the Apply button. If your server was configured to use a different caching realm before the agent was installed, you must choose that value from the pull down menu.
- Restart the WebLogic Server for the changes to take effect.
The above mentioned steps disable the agent realm for BEA WebLogic Server. To enable the agent realm again, follow steps 1-3 and in step 4 change the value of Caching Realm to Agent Caching Realm.
Agent for IBM WebSphere Application Server 5.0/5.1
Use the following steps to disable the agent realm for WebSphere Application Server:
- Log in to the WebSphere Administration Console.
- Click on the Security node on the left hand panel. This expands the Security node on the left hand panel.
- Under the Security node, click on the Global Security link. This displays the Global Security configuration screen on the right hand panel.
- On the right hand panel either disable the checkbox General Preferences -> Enabled, or select a User Registry other than Custom in General Preferences -> Active User Registry.
- Restart your Application Server to ensure that the changes take effect.
The above mentioned steps disable the agent realm for WebSphere Application Server. To enable the agent realm, follow steps 1-3 and in step 4, simply check the Enabled checkbox under General Preferences -> Enabled on the Global Security Configuration page and make sure that the Active User Registry is set to Custom.
Agent for Oracle 9iAS and Oracle 10g
Use the following steps to disable the agent realm for Oracle 9iAS and Oracle 10g:
- Go to the OC4J instance directory and edit application.xml. The path to this file is typically as follows:
- Comment out the <user-manager> element in the XML. If you ever uninstall the agent, remember to uncomment the <user-manager> element before uninstalling the agent so that the agent can remove it using the uninstallation program.
- Restart the OC4J instance through Enterprise Manager or any command line tool.
Agent for Sun Java System Application Server 8.1
Use the following steps to disable the agent realm for Sun Java System Application Server 8.1:
- Log in to the Sun Java System Application Server 8.1 Administration console.
- In the left-hand pane, select the Configurations node.
- Select the instance_name-config node where your agent is installed.
where instance_name is the name of that particular server instance.
- In the expanded tree under the server name node, click the Security node.
This displays the general security settings for this server instance on the right hand panel.
- In the right-hand pane, change the value of Default Realm to file.
If the application server was configured to use a different realm than file before the agent was installed, you must choose that value from the pull-down menu instead.
- Restart your Application Server to ensure the changes take effect.
The above mentioned steps disable the agent realm for Sun Java System Application Server 8.l. To enable the agent realm again, follow steps 1-4 and in step 5 change the value of Default Realm to agentRealm.
Hot-Swap ConfigurationThe agent supports hot-swap configuration that allows you to modify the agent configuration properties and have them take effect without requiring you to restart the application server on which the agent is installed. It should be noted that not all properties in the agent configuration file are hot-swap enabled, which implies that for properties that are not hot-swap enabled, you must restart the server to ensure that any changes to these property values take effect.
This 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. This mechanism can be disabled by setting the value 0 for this configuration property.
This mechanism is primarily provided to facilitate the development and testing of your application in a controlled development or test environment. It is strongly recommended that this feature be disabled 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 application server 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:
- The application server is started with the load interval set to 10 seconds. Therefore, in every 10 seconds any changes made to the agent configuration are picked up by the agent.
- Consider the case that you modify the load interval value while the application server is running and set it to 0. When the last load interval completes, the agent will pick up this new value. Since the value is set to 0 the agent will disable the hot-swap mechanism for the entire system.
- Once disabled, the configuration changes made to the agent configuration file will not be sensed by the agent. Therefore, even if you reset the value of this property now to any other number, it will not enable the hot-swap mechanism unless the application server is restarted.
In the case when the value of the load interval is set to 0 during the startup of the application server, 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.
Enabling Web-Tier Declarative SecurityCertain applications may require the use of web-tier declarative security that enforces role-based access control over web resources such as Servlets, JSPs, HTML files and any other resource that can be represented as a URI. This type of security is enforced by adding security-constraint elements to the deployed application’s web.xml deployment descriptor.
Typically security-constraint elements are tied with auth-constraint elements that identify the role membership that will be enforced when a request for a protected resource is made by the client browser. The following example illustrates this idea:
This fragment of deployment descriptor can be used to ensure that access to the report generation servlet is allowed only to those users who are members of the role called Manager.
In order for such a construct to work, you must make the necessary modifications to the agent configuration file to ensure it can identify and handle such requests. This can be done by following these steps:
- Ensure that a login-config element is specified for the web application that is being protected and that the login-config element has the auth-method set to FORM. The supporting form-login-config element is also required.
- The form-login-page element of form-login-config should be added as one of the values for the following property in the agent configuration file:
com.sun.am.policy.amFilter.login.formList
As an example, consider the following login-config element of a protected application:
<login-config>
<auth-method>FORM</auth-method>
<form-login-config>
<form-login-page>/jsp/login.jsp</form-login-page>
<form-error-page>/block.html</form-error-page>
</form-login-config>
</login-config>
Notice how the form-login-page is specified for the supporting form-login-config element. This value must be set for the following property in the agent configuration file as shown here:
com.sun.am.policy.amFilter.login.formList[0] = /Portal/jsp/login.jsp
Notice that the value of the form-login-page as specified in the deployment descriptor is not the same as what is specified in the agent configuration file. The difference being that when you enter this value in the agent configuration file, you must prefix it with the context path for the application on which this form-login-page is going to be used. In this particular example, the context path of the application is “/Portal”.
Similarly, if you have more than one application deployed that require web-tier declarative security, you must add their respective form-login-pages to the agent configuration file. For example, other entries could possibly be:
com.sun.am.policy.amFilter.login.formList[1] = /BankApp/SignOn
com.sun.am.policy.amFilter.login.formList[2] = /ERP/LoginServlet
Please ensure that each such element added to this list has a unique index entry. Having duplicate indexed entries can result in the loss of data and consequently result in the malfunction of the application. To learn more about the way such list properties are specified in the agent configuration file, refer to the section on General Notes on the Agent Configuration File.
Once you have configured the web application’s deployment descriptor to use the form-login mechanism for web-tier declarative security and have added the full URI of the form-login-page for each such application in the agent configuration file, the web-tier declarative security is enabled for these applications.
Note
- When a protected application is configured for web-tier declarative security handling by the agent, it must be redeployed with a form-login configuration as described in this section. This configuration requires that two application resources be specified in the application’s web.xml deployment descriptor: one for the form-login-page and the other for the form-error-page. Regardless of whether the resource corresponding to the form-login-page exists in the application or not (this depends on how the agent is configured to handle the form-login requests), the resource corresponding to the form-error-page must be present in the application. This resource is directly invoked by the application server to indicate authentication failures and, optionally, authorization failures. If the application does not contain a valid form-error-page matching the URI specified in this deployment descriptor, it could result in HTTP 404 errors when the container chooses to display this error page.
- A real form-error-page is not necessary for the applications protected by the policy agents for Oracle 9iAS R2 and Oracle 10g and for Tomcat Server 4.1.27, which support the property com.sun.am.policy.amFilter.login.errorList. This property can be used to configure the agent to handle form-error-page requests for applications that do not have a form-error-page to begin with.
- For applications that do not contain a form-login-page, you can specify any URI as long as that URI does not conflict with any application resource and the matching value has been added to the configuration property com.sun.am.policy.amFilter.login.formList.
- By default, the agent is configured to intercept all form-login requests and handle them without invoking the actual form-login-page resource as specified in the web.xml of the protected application. Thus, when using a default installation of the agent, the application is not required to have a resource corresponding to the form-login-page element specified in web.xml. This allows for the configuration of web-tier declarative security for applications that were not designed to use the form-login mechanism and instead relied on other login schemes available in J2EE specification. This behavior of the agent can be changed so that it allows the form-login requests to be handled by actual resources that exist within the application by changing the agent configuration properties as applicable. For details on how this can be done, please refer to the section Customizing Agent Response for Form Login.
- If the agent filter is operating in the URL_POLICY mode, any necessary URL policies to allow access to the form-error-page resource must be created for all users.
To further customize the behavior of the application when using web-tier declarative security, please refer to the details provided in the section Web-Tier Security Details.
Configuring a Web Application to Enable Web-Tier Declarative Security
The instructions in this section are applicable only to the agents for Oracle 10g and Macromedia JRun 4.
All the applications that are protected by web-tier declarative security must define a form-login page that does a client-side redirect to itself. For example, if the form-login-page AMLogin.html is deployed at the <context-root> for the web application /SampleApp, the page should contain the following HEAD element:
A sample form-login HTML page called AMLogin.html is shipped with the policy agent for reference and can be located in Agent_Install_Dir/locale. When using this sample file, make sure to substitute the <CONTEXT_URI> tag with the URI of the protected application and copy the file to the <context-root> of the web application.
Once you have made this change, you will have to include this file in the web application archive or make it available in the directory where the web application resides.
Note
This sample file only serves as a reference for HTML-based form-login pages. If the form-login page format is different than HTML, the user must ensure to update their form-login pages.
Web-Tier Security Details
When the application server’s web container gets a request for a resource that is protected by the web-tier declarative security-constraint, it must evaluate the credentials of the user against the agent realm to ensure that only authorized requests go through. In order to process such a request, the application server requires the user to sign on using the specified form login page as mentioned in the form-login-config element of the web.xml descriptor. Based on the specification of the FORM authentication mechanism, it is required that the user submits a valid user name as j_username and a valid password as j_password to the special URI j_security_check using the HTTP POST method of form submission.
The agent, once configured to support web-tier declarative security for the given application can isolate the request for accessing form-login-page and instead can stream out some data to the client browser. This data contains the user’s login name and temporary encrypted password, which in turn uses Javascript to do automatic form submission as required. This gives the user a seamless Single Sign-On experience since the user does not have to re-login in order to access the protected resources for a deployed application that uses web-tier declarative security.
By default, the content that the agent sends to the client browser on intercepting a request for the form login page is read from the file called FormLoginContent.txt located in the locale directory of the agent installation. This file contains the following html code:
<html>
<head>
<title>Security Check</title>
</head>
<body onLoad="document.security_check_form.submit()">
<form name="security_check_form" action="j_security_check" method="POST">
<input type="hidden" value="am.filter.j_username" name="j_username">
<input type="hidden" value="am.filter.j_password" name="j_password">
</form>
</body>
</html>
Before the agent streams out the contents of this file, it replaces all occurrences of the string am.filter.j_username by the appropriate user name. Similarly, all occurrences of the string am.filter.j_password are replaced by a temporary encrypted string that acts as a one-time password for the user.
Customizing Agent Response for Form Login
The agent configuration file allows you to completely control the contents that are sent out to the user when the application server requires a form login from the user.
Using the agent configuration file, you can customize the agent response in the following ways:
- Modify the content of the FormLoginContent.txt file to suit your UI requirements as necessary. You must ensure that whatever modifications you do, the file must eventually submit the j_username and j_password to the action j_security_check via HTTP POST method.
- You can specify the name of a different file using the property com.sun.am.policy.amFilter.login.filename in the agent configuration file. If you specify the file name, you must ensure that it exists within the locale directory of the agent installation.
If you wish that this file be used from another directory, you can simply specify the full path to this new file.
You must ensure that whatever modifications you do, the file must eventually submit the j_username and j_password to the action j_security_check via HTTP POST method.
- If you have more than one application and would like to have an application-specific response to the form login requests, you can instruct the agent to allow the form login request to proceed to the actual form login page. This can be done by setting the value of the configuration property com.sun.am.policy.amFilter.login.use.internal as false.
In this situation, you must ensure that the resource that receives this request extracts the am.filter.j_username and am.filter.j_password from the HttpServletRequest as attributes and uses that to ensure that eventually a submit of these values as j_username and j_password is done to the action j_security_check via HTTP POST method.
The following JSP fragment demonstrates how this can be done:
<form action="j_security_check" method="POST">
<%
String user = (String) request.getAttribute("am.filter.j_username");
String password = (String) request.getAttribute("am.filter.j_password");
%>
<ul>
<li>Your username for login is: <b><%=user%></b></li>
<li>Your password for login is: <b><%=password%></b></li>
</ul>
<input type=hidden name="j_username" value="<%=user%>">
<input type=hidden name="j_password" value="<%=password%>">
<input type="submit" name="submit" value="CONTINUE">
</form>
This mechanism would therefore allow you to have an application-specific form-login handling mechanism.
Enabling FailoverThe agent allows basic failover capabilities. This helps you ensure that if the primary Sun ONE Identity Server for which the agent has been configured becomes unavailable, the agent will switch to the next Sun ONE Identity Server as specified in the agent configuration file.
This setup can be achieved by the following steps:
- Provide a list of Sun ONE Identity Server Authentication services URLs that may be used by the agent to authenticate users who do not have sufficient credentials to access the protected resources. This can be done by using the following property:
com.sun.am.policy.amFilter.loginURL
You may specify more than one Login URL as follows:
com.sun.am.policy.amFilter.loginURL[0] = first_login_url
com.sun.am.policy.amFilter.loginURL[1] = second_login_url
com.sun.am.policy.amFilter.loginURL[2] = third_login_url
- Provide a list of Sun ONE Identity Server Naming service URLs that may be used by the agent to get access to the various other service URLs that may be needed to serve the logged on user. This can be done by using the following property:
com.iplanet.am.naming.url
More than one naming service URL may be specified as a space delimited list of URLs. The following example illustrates this idea:
com.iplanet.am.naming.url = first_url second_url
Note
The failover capability of the agent is limited to login and naming services. The URL Policy Service and Remote Logging service do not support failover in this release of the agent.
This implies that the failover feature would work only when the agent filter mode is set to either SSO_ONLY or J2EE_POLICY. Certain other configuration settings may also be required in order to ensure that the failover mechanism works correctly. For more information, please refer to the Sun ONE Identity Server Programmer’s Guide.
Login Attempt LimitWhen a user tries to access a protected resource without having authenticated with Sun ONE Identity Server’s authentication services, the request is treated as a request with insufficient credentials. The default action taken by the agent when it encounters such a request is to redirect the user to the next available Login URL as configured in the agent configuration file.
It may be possible that despite the repeated redirects done by the agent, the user is unable to furnish the necessary credentials. In such a case, the agent can be directed to block such a request. This is configured using the Login Attempt Limit configuration property. The configuration property that controls this behavior is the following:
com.sun.am.policy.amFilter.login.attempt.limit
If a non-zero positive value is specified for this property in the agent configuration file, the agent will only allow that many attempts before it blocks the access request without the necessary credentials. When set to a value of zero, this feature is disabled.
It is strongly recommended to enable this feature in order to guard against potential denial-of-service attacks on your system.
Redirect Attempt LimitThe processing of requests by the agent can result in redirects for the client browser. Such redirects can happen when the user has not authenticated with Sun ONE Identity Server’s authentication service, lacks the sufficient credentials necessary to access a protected resource and a variety of other reasons.
While the agent ensures that only the authenticated and authorized users get access to the protected resources, there is a remote possibility that due to misconfiguration of the system, the client browser may be put into an infinite redirection loop.
The Redirect Attempt Limit configuration property allows you to guard against such potential situations by ensuring that after a given number of consecutive requests from a particular user that result in the same exact redirect, the agent blocks the user request. This blocking of the request is only temporary and is removed the moment the user makes a request that does not result in the same redirect or results in access being granted to the protected resource. The configuration property that controls this feature is:
com.sun.am.policy.amFilter.redirect.attempt.limit
If a non-zero positive integer is specified as the value of this property, the agent will break the redirection loop after the specified number of requests result in the same redirects. When its value is set to zero, this feature is disabled.
It is highly recommended that this feature be enabled to protect the system from such situations. Further, it can also help in breaking potential denial of service attacks.
Not-Enforced ListThe agent configuration file allows you to specify a list of URIs that are treated as not-enforced. Access to these resources is always granted by the agent. The configuration property that controls this list is as follows:
com.sun.am.policy.amFilter.notenforcedList
It is recommended that if your deployed application has pages that use a bulk of graphics that do not need the agent protection, such content be added to the agent’s Not-Enforced list to ensure the optimal utilization of the system resources. Following is an example of the entries that you may specify in the Not-Enforced list:
com.sun.am.policy.amFilter.notenforcedList[0] = /images/*
com.sun.am.policy.amFilter.notenforcedList[1] = /public/*.html
com.sun.am.policy.amFilter.notenforcedList[2] = /registration/*
This will enable the agent to focus on enforcing access control only over requests that do not match these given URI patterns. The use of a wildcard (*) is allowed to indicate the presence of one or more characters in the URI pattern being specified.
Inverting the Not-Enforced List
In situations where only a small portion of the deployed application needs protection, you can configure the agent to do just that by inverting the Not-Enforced list. This results in the agent enforcing access control over the entries that are specified in the Not-Enforced list and allowing access to all other resources on the system. This feature is controlled by the following property:
com.sun.am.policy.amFilter.notenforcedList.invert
If you set the value true for this property, it would make the entries specified in the not-enforced list as enforced entries and the rest of the application resources will be treated as not-enforced.
Caution
When the not-enforced list is inverted, the number of resources for which the agent will not enforce access control are potentially very large. The use of this feature should therefore be done with extreme caution and only after extensive evaluation of the security requirements of the deployed applications.
Note
- If an Access Denied URI is specified, it will always be not-enforced by the agent regardless of the configuration of not-enforced list. This is necessary to ensure that the agent can use the Access Denied URI to block any unauthorized access for protected system resources.
- When configuring access denied URIs within the deployment descriptor of the web application, you must ensure that these values are added to the Not-Enforced List of the agent. Failing to do so can result in application resources becoming inaccessible by the user.
- Any resource that has been added to the Not-Enforced list must not access any protected resource. If it does so, it can result in unauthorized access to protected system resources. For example, if a servlet that has been added to the not-enforced list, in turn sends the request to another servlet, which is protected, it can potentially lead to unauthorized access to the protected servlet.
Enabling LDAP AttributesCertain applications may rely on the presence of user-specific profile information in some form in order to process the user requests appropriately. The agent provides the functionality that can help such applications appropriately by making the LDAP attributes from the user’s profile available in various forms.
The agent allows the fetching of LDAP Attributes and can make them available in one of the following three forms:
The property that controls this feature is the following:
com.sun.am.policy.amFilter.ldapattribute.mode
The value for this property can be one from NONE, HEADER, REQUEST_ATTRIBUTE, and COOKIE. Based on the set value, the agent retrieves the necessary LDAP attributes available for the logged on user and makes them available to the application appropriately. The attributes that are fetched by the agent and the names by which they are made available are controlled by the following property:
com.sun.am.policy.amFilter.ldapattribute.map
Using this property, 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 your configuration setting would be as follows:
com.sun.am.policy.amFilter.ldapattribute.map[cn] = COMMON_NAME
com.sun.am.policy.amFilter.ldapattribute.map[mail] = EMAIL_ADDR
LDAP 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.am.policy.amFilter.ldapattribute.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 method:
java.util.Enumeration getHeaders(java.lang.String name)
LDAP 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.
LDAP 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.am.policy.amFilter.ldapattribute.separator
It is the responsibility of the application 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.
If you are using the policy agent for BEA WebLogic Server 7.0 SP2 or BEA WebLogic Server 8.1, you may choose to encode the cookie values that are set using the value of the following property:
com.sun.am.policy.amFilter.ldapattribute.cookie.encode=true
This is required if the LDAP Attributes that you specify have special characters that are not allowed in cookie values. If the value of this property is set to false and if the LDAP Attributes contain special characters, the agent may behave inconsistently. Note that this property is applicable only to the agents for BEA WebLogic Server 7.0 SP2 and BEA WebLogic Server 8.1.
It is highly recommended that when you are using this mode of LDAP attributes, you should also be using 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 the section Using Cookie Reset Functionality.
Configuring FQDN HandlingTo ensure appropriate user experience, it is necessary to enforce that the users use valid URLs to access resources protected by the agent. This functionality is controlled by two separate properties - the default FQDN specified as the property:
com.sun.am.policy.amFilter.fqdn.default
and the FQDN Map, which is specified as the following property:
com.sun.am.policy.amFilter.fqdn.map
The configuration property for default FQDN 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 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 application server protected by this agent can be accessed using more than one hostname. As an example, consider a protected application server that can be accessed using the following hostnames:
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.am.policy.amFilter.fqdn.map[internalhostname.interndomain.com] = internalhostname.interndomain.com
com.sun.am.policy.amFilter.fqdn.map[192.101.98.45] = 192.101.98.45
Using Cookie Reset FunctionalityThe agent allows you to reset certain cookies that may be present in the user’s browser session if the user’s Sun ONE Identity Server session has expired. This feature is controlled by the following configuration properties:
com.sun.am.policy.amFilter.cookieReset.cookieList
com.sun.am.policy.amFilter.cookieReset.domainMap
com.sun.am.policy.amFilter.cookieReset.pathMap
The above three 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 Cookie Reset List 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 Cookie Reset Domain Map property and the Cookie Reset Path Map 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, you must 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, it may result in the cookie not being reset in the client browser.
When a cookie entry does not have an associated domain specified in the domain map, it is assumed that it is a server cookie. Similarly, when a cookie entry does not have a corresponding path entry specified, it is assumed that the cookie path is set to “/”.
Enabling Port Check FunctionalityIn situations when Sun ONE Identity Server and the application server 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 Sun ONE Identity Server’s authentication service and the agent. In such situations, the agent, relying on the availability of the port number from the application server may 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.am.policy.amFilter.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.am.policy.amFilter.port.check.map
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 agent server’s preferred port and protocol 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.am.policy.amFilter.port.check.filename
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 above mentioned 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.
AMAgent.properties ReferenceThe configuration file AMAgent.properties contains the necessary configuration properties needed for the agent to function correctly. It also contains the necessary information needed for the Sun ONE Identity Server SDK to function correctly in a client installation mode as used by the agent.
This section provides a listing of all agent configuration properties in the AMAgent.properties file with a brief explanation and examples.
Note
Among the agent properties, the following are not available in version 2.1 of policy agents for BEA WebLogic 6.0SP2/7.0SP2/8.1, IBM WebSphere 5.0/5.1, and Sun ONE Application Server 7.0. For these agents, these properties were introduced in version 2.1.1.
Also note that these properties are currently not available for PeopleSoft 8.3/8.4/8.8 agent.
Agent Filter Mode
Property
com.sun.am.policy.amFilter.mode
Description
This property governs the mode of operation of the agent. The various modes of agent operation dictate the necessary processing that the agent would perform on a user request.
Valid Values
The valid value for this property can be one of the five strings: NONE, SSO_ONLY, J2EE_POLICY, URL_POLICY, and ALL. Any other value will be treated as an incorrect entry and the agent will default to the ALL mode of operation.
Note
Mode NONE
In this mode of operation, the agent does not take any action on the user request and is effectively disabled. Access to all user requests is therefore granted. Please read the Caution section after the description of mode ALL.
Mode SSO_ONLY
In this mode of operation, the agent enforces Single Sign On for the user using Sun ONE Identity Server Authentication Service.
Mode J2EE_POLICY
In this mode of operation, the agent enforces J2EE policies such as those configured in the deployment descriptors of the protected application or are implicit in the deployed application using the J2EE programmatic security API.
Mode URL_POLICY
In this mode of operation, the agent enforces URL policies as defined in Sun ONE Identity Server.
Mode ALL
In this mode of operation, the agent enforces the J2EE policies as well as the URL policies. Access to the protected resource is granted only if the user meets the success criteria for all applicable policies.
Caution
When this property is set to NONE, the agent will grant access to all protected resources. This mode of operation should not be used in deployed production systems at any time as it can result in unauthorized access to the protected system resources. This mode of operation is provided only to facilitate troubleshooting of the application in well controlled development and test environment and should not be used in any other environment.
Hot-Swap Enabled
Yes
Applicable Modes of Operation
NA
Example
com.sun.am.policy.amFilter.mode = ALL
See Also
Configuration Reload Interval
Property
com.sun.am.policy.config.load.interval
Description
This property specifies the time in seconds after which the agent will poll the configuration file for changes. This configuration controls the entire hot-swap mechanism of the agent and may also be used to disable the hot-swap mechanism.
Valid Values
Unsigned integer value, including 0, which indicates the amount of time in seconds after which the agent will poll the configuration file for any changes.
Note
- When set to 0, the hot-swap mechanism will be disabled.
- This property is hot-swap enabled, which means that the value of this property can be loaded dynamically. However, if the value is set to 0 at any time, the hot-swap mechanism will become disabled for the entire system and can only be enabled again by restarting the system.
- During the system startup, if the value of this property is 0, the hot-swap mechanism will be disabled and cannot be enabled unless the system is restarted with this property set to a non-zero value.
- It is recommended that the value for this property be set to 0 for deployed production systems to ensure optimal performance.
Hot-Swap Enabled
Yes
Applicable Modes of Operation
NONE, SSO_ONLY, URL_POLICY, J2EE_POLICY, ALL
Example
com.sun.am.policy.config.load.interval = 300
See Also
Language Code
Property
com.sun.am.policy.locale.language
Description
This property specifies the Locale for agent operation.
Valid Values
Must be a valid ISO Language Code.
Note
For more information, refer to ISO 639 specification: http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt
Hot-Swap Enabled
No. If you change the value of this property, it will take effect only after you restart the application server.
Applicable Modes of Operation
NONE, SSO_ONLY, URL_POLICY, J2EE_POLICY, ALL
Example
com.sun.am.policy.locale.language = en
See Also
Country Code
Property
com.sun.am.policy.locale.country
Description
This property specifies the Locale for agent operation.
Valid Values
Must be a valid ISO Country Code.
Note
For more information, refer to ISO 3166 specification: http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html
Hot-Swap Enabled
No. If you change the value of this property, it will take effect only after you restart the application server.
Applicable Modes of Operation
NONE, SSO_ONLY, URL_POLICY, J2EE_POLICY, ALL
Example
com.sun.am.policy.locale.country = US
See Also
Registered Module List
Property
com.sun.am.policy.amAgent.moduleList
Description
This property specifies the registered modules in the system. This property is set during the agent installation and should not be changed at any time.
Valid Values
As set during agent installation. Any other value is not valid.
Note
- This property is set during agent installation and must not be changed at any time.
- This property must conform to the rules and format of LIST construct as described in "List Constructs in the Configuration File" section.
Hot-Swap Enabled
No
Applicable Modes of Operation
NONE, SSO_ONLY, URL_POLICY, J2EE_POLICY, ALL
Example
com.sun.am.policy.amAgent.moduleList[0] = com.sun.identity.agents.filter.AmFilterModule
See Also
General Notes on the Agent Configuration File
Login URL
Property
com.sun.am.policy.amFilter.loginURL
Description
This property specifies the login URLs to be used by the agent to redirect incoming users without sufficient credentials to Sun ONE Identity Server authentication service.
Valid Values
The complete URL to be used as the redirect URL in order to send users without sufficient credentials to Sun ONE Identity Server authentication service.
Note
- This property is set during agent installation and need not be changed unless absolutely necessary.
- This property must conform to the rules and format of LIST construct as described in the General Notes on the Agent Configuration File section.
Hot-Swap Enabled
Yes
Applicable Modes of Operation
SSO_ONLY, URL_POLICY, J2EE_POLICY, ALL
Example
com.sun.am.policy.amFilter.loginURL[0] = http://www.mycompany.com:58080/amserver/UI/Login
See Also
Counter Cookie Name
Property
com.sun.am.policy.amFilter.counter.cookie.name
Description
This property specifies the name of the cookie that will be used to track the number of unsuccessful login attempts made by the user.
Valid Values
The name of the cookie to be issued by agent in order to track the number of unsuccessful login attempts made by the user.
Note
This property is set during agent installation and need not be changed unless absolutely necessary.
Hot-Swap Enabled
Yes
Applicable Modes of Operation
SSO_ONLY, URL_POLICY, J2EE_POLICY, ALL
Example
com.sun.am.policy.amFilter.counter.cookie.name = amFilterParam
See Also
- Discussion on Login Attempt Limit
Login Attempt Limit
Property
com.sun.am.policy.amFilter.login.attempt.limit
Description
This property specifies the number of unsuccessful login attempts that a user can make using a single browser session, Once this limit is reached, the agent will block the user request.
Valid Values
Unsigned integer value, including 0, which indicates the number of unsuccessful login attempts that are allowed for any user trying to gain access to protected resources.
Hot-Swap Enabled
Yes
Applicable Modes of Operation
SSO_ONLY, URL_POLICY, J2EE_POLICY, ALL
Example
com.sun.am.policy.amFilter.login.attempt.limit = 5
See Also
- Discussion on Login Attempt Limit
URL Decode SSO Token Flag
Property
com.sun.am.policy.amFilter.ssotoken.urldecode
Description
This property indicates if the SSO Token needs to be URL decoded by the agent before it may be used.
Valid Values
Hot-Swap Enabled
Yes
Applicable Modes of Operation
SSO_ONLY, URL_POLICY, J2EE_POLICY, ALL
Example
com.sun.am.policy.amFilter.ssotoken.urldecode = true
Goto Parameter Name
Property
com.sun.am.policy.amFilter.goto.parameter.name
Description
This property specifies the goto Parameter name to be used by the agent when redirecting the user to the appropriate authentication service. The value of this parameter is used by the authentication service to redirect the user to the original requested destination.
Valid Values
A string value that represents the goto parameter name as expected by the authentication service.
Hot-Swap Enabled
Yes
Applicable Modes of Operation
SSO_ONLY, URL_POLICY, J2EE_POLICY, ALL
Example
com.sun.am.policy.amFilter.goto.parameter.name = goto
Session Binding Flag
Property
com.sun.am.policy.amFilter.session.binding
Description
This property specifies if the agent will enforce session binding with authentication.
Valid Values
- true: indicates that session binding will be enforced
- false: indicates that session binding will not be enforced
Note
- When enforced, the agent will invalidate the user's local session in the application server if the user does not have a valid SSO token.
- When enforced, the agent will create the user's local session in the application server if the user has a valid SSO token but does not have an active local session yet.
- When not enforced, the agent will preserve the user's local session state in the application server irrespective of whether the user has an active local session or not.
- The value of this property is set during the installation and must not be changed unless absolutely necessary.
Hot-Swap Enabled
Yes
Applicable Modes of Operation
J2EE_POLICY, ALL
Example
com.sun.am.policy.amFilter.session.binding = true
Not-Enforced List
Property
com.sun.am.policy.amFilter.notenforcedList
Description
This property specifies a list of patterns that can be used to evaluate if the requested URI does not require the protection enforced by the agent.
Valid Values
- Valid values must comply with the syntax of this property.
- The valid values can be exact URIs or patterns consisting of wild-card character '*' to indicate zero or more characters.
Note
- This property must conform to the rules and format of LIST construct as described in "List Constructs in the Configuration File".
- No default value is specified for this property during installation. Values for this property must be specified as necessary.
- This property is commented out during agent installation and should be uncommented if its use is necessary.
Hot-Swap Enabled
Yes
Applicable Modes of Operation
SSO_ONLY, URL_POLICY, J2EE_POLICY, ALL
Examples
com.sun.am.policy.amFilter.notenforcedList[0]=*.gif
com.sun.am.policy.amFilter.notenforcedList[1]=/public/*
com.sun.am.policy.amFilter.notenforcedList[2]=/images/*
See Also
- Discussion on Not-Enforced List
Not-Enforced List Inversion Flag
Property
com.sun.am.policy.amFilter.notenforcedList.invert
Description
This property indicates if the not-enforced list will be interpreted as the enforced list by the agent, thereby treating all request URIs not present in this list as not-enforced.
Valid Values
- true: indicates that the not-enforced list will be interpreted as the enforced list by the agent.
- false: indicates that the not-enforced list will be interpreted as the not-enforced list by the agent.
Note
- Valid but inappropriate value of this property may lead to the application being unreachable by the users or may result in unauthorized access to protected system resources.
- The value of this property should be changed only if necessary with extreme caution as it can possibly result in unauthorized access to the protected system resources.
Hot-Swap Enabled
Yes
Applicable Modes of Operation
SSO_ONLY, URL_POLICY, J2EE_POLICY, ALL
Example
com.sun.am.policy.amFilter.notenforcedList.invert = false
See Also
- Discussion on Not-Enforced List
Not-Enforced-List Cache Enable Flag
Property
com.sun.am.policy.amFilter.notenforcedList.enableCache
Description
This property specifies if the request URIs that are evaluated as enforced or not-enforced may be cached to increase performance of the system.
Valid Values
Hot-Swap Enabled
Yes
Applicable Modes of Operation
SSO_ONLY, URL_POLICY, J2EE_POLICY, ALL
Example
com.sun.am.policy.amFilter.notenforcedList.enableCache = true
See Also
- Discussion on Not-Enforced List
Not-Enforced-List Cache Size
Property
com.sun.am.policy.amFilter.notenforcedList.cacheSize
Description
This property specifies the number of entries that will be kept in the cache of not-enforced URIs and enforced URIs by the agent.
Valid Values
Non-zero unsigned integer indicating the number of enforced as well as not-enforced request URIs to be cached during runtime.
Note
- Values that are valid but not suited for the deployment scenario may result in degradation of system performance.
- The value for optimal system performance will depend on the type of application deployed, the number of possible request URIs in the deployed application, the user load on the system, the expiration time set for cache entries and a host of other deployment specific factors.
- To determine the most optimal value of this property, the application should be load tested in a controlled test environment before being deployed for production.
Hot-Swap Enabled
Yes
Applicable Modes of Operation
SSO_ONLY, URL_POLICY, J2EE_POLICY, ALL
Example
com.sun.am.policy.amFilter.notenforcedList.cacheSize = 1000
See Also
- Discussion on Not-Enforced List
Not-Enforced-List Cache Expiration Time
Property
com.sun.am.policy.amFilter.notenforcedList.cacheTime
Description
This property specifies the amount of time in seconds that will be used to evaluate if a cached entry can be removed from the cache to free up resources for new cache entries.
Valid Values
Non-zero unsigned integer indicating the time in seconds that will be used as the cache expiration time for entries in the cache during cleanup operation.
Note
- Values that are valid but not suited for the deployment scenario may result in degradation of system performance.
- The value for optimal system performance will depend on the type of application deployed, the number of possible request URIs in the deployed application, the user load on the system, the cache size set for cache entries and a host of other deployment specific factors.
- To determine the most optimal value of this property, the application should be load tested in a controlled test environment before being deployed for production.
Hot-Swap Enabled
Yes
Applicable Modes of Operation
SSO_ONLY, URL_POLICY, J2EE_POLICY, ALL
Example
com.sun.am.policy.amFilter.notenforcedList.cacheTime = 300
See Also
- Discussion on Not-Enforced List
Access Denied URI
Property
com.sun.am.policy.amFilter.accessDeniedURI
Description
This property specifies the Access Denied URI used by the agent to block unauthorized access requests.
Valid Values
The URI within the deployed application that must be used as the access denied URI to block incoming requests when necessary.
Note
- This property is common for all deployed applications.
- This property must specify a URI that is always available on the system. Failure to do so can result in HTTP 404 errors being sent to the end-user.
- In case when this property is not specified the agent uses HTTP Status Code 403 (Forbidden) to indicate a blocked access.
Hot-Swap Enabled
Yes
Applicable Modes of Operation
SSO_ONLY, URL_POLICY, J2EE_POLICY, ALL
Example
com.sun.am.policy.amFilter.accessDeniedURI = /errors/forbidden.html
See Also
Discussion on Not-Enforced List
LDAP Date Header Attribute Format String
Property
com.sun.am.policy.amFilter.ldapattribute.date.format
Description
This property specifies the format of Date/Time value to be expected as a result of an attribute lookup. This is required when using the specialized get methods of the javax.servlet.http.HttpServletReqeust interface that return Date values for headers.
Valid Values
Valid java.text.SimpleDateFormat Time Format Syntax string. For more information, please refer to http://java.sun.com/j2se/1.3/docs/api/java/text/SimpleDateFormat.html
Hot-Swap Enabled
Yes
Applicable Modes of Operation
SSO_ONLY, URL_POLICY, J2EE_POLICY, ALL
Example
com.sun.am.policy.amFilter.ldapattribute.date.format = EEE, d MMM yyyy hh:mm:ss z
See Also
- Discussion on Enabling LDAP Attributes
LDAP Attribute Map
Property
com.sun.am.policy.amFilter.ldapattribute.map
Description
This property specifies the LDAP Attributes to be populated under specific names for the currently authenticated user.
Valid Values
- Valid values must comply with the syntax of this property.
- The specified LDAP Attribute should be a valid attribute.
- The specified name should be valid name for the specified mode of setting these attributes as mentioned in the configuration value for the property LDAP Attribute Fetch Mode.
Note
- This property must conform to the rules and format of MAP construct as described in "Map Constructs in the Configuration File".
- Please ensure that the specified Names do not conflict with existing names in the system for the specified fetch mode. Failing to do may result in the loss of the existing data in the system.
- Any number of such properties may be specified as long as they are valid properties conforming to the above stated requirements.
- This property is commented out during agent installation and should be uncommented if necessary.
Hot-Swap Enabled
Yes
Applicable Modes of Operation
SSO_ONLY, URL_POLICY, J2EE_POLICY, ALL
Example
com.sun.am.policy.amFilter.ldapattribute.map[cn]=COMMON_NAME
See Also
- Discussion on Enabling LDAP Attributes
LDAP Attribute Fetch Mode
Property
com.sun.am.policy.amFilter.ldapattribute.mode
Description
This property specifies how the LDAP Attributes are made available to the protected application.
Valid Values
The valid value for this property should be any one of the strings: NONE, HEADER, REQUEST_ATTRIBUTE, or COOKIE.
Note
- When set to NONE, the LDAP attributes are not fetched by the agent.
- When set to HEADER, the LDAP attributes are populated as HTTP Headers. Multi-valued attributes are available in this mode using the method javax.servlet.http.HttpServletRequest.getHeaders(java.lang.String name)
- When set to REQUEST_ATTRIBUTE, the LDAP attributes are populated as request attributes. These attributes are available as java.util.Set objects and can be obtained using the method javax.servlet.http.HttpServletRequest.getAttribute(java.lang.String name)
- When set to COOKIE, the LDAP attributes are populated as cookies for the current user. Multi-valued attributes are available as a concatenated string separated by characters as defined in the property LDAP Attribute Cookie Separator Character.
- When set to COOKIE, it is advisable that the corresponding cookie names be also added to the Cookie Reset List property and that the Cookie Reset Enable flag be switched to true.
- Multi-valued attributes are available in all modes. Please refer to Enabling LDAP Attributes to find out more about how multi-valued attributes can be accessed from within a protected application.
- This property value is set to NONE during agent installation and should be changed as necessary.
Hot-Swap Enabled
Yes
Applicable Modes of Operation
SSO_ONLY, URL_POLICY, J2EE_POLICY, ALL
Example
com.sun.am.policy.amFilter.ldapattribute.mode = REQUEST_ATTRIBUTE
See Also
- Discussion on Enabling LDAP Attributes
LDAP Attribute Cookie Separator Character
Property
com.sun.am.policy.amFilter.ldapattribute.separator
Description
This property specifies a character, which is used by the agent to set the value of LDAP Attributes as cookies in the case where more than one value for the given attribute is available.
Valid Values
A single character that can be used by the agent to concatenate various values of a multi-valued LDAP attribute for the logged on user so that it can be set as a single cookie.
Note
- This property is not used when the value of the property LDAP Attribute Fetch Mode is set to any value other than COOKIE.
- This property is not used for attributes that are single-valued.
- The character specified by this property should not appear as a character within any LDAP attribute value.
- This property is set during agent installation and should be changed as necessary.
Hot-Swap Enabled
Yes
Applicable Modes of Operation
SSO_ONLY, URL_POLICY, J2EE_POLICY, ALL
Example
com.sun.am.policy.amFilter.ldapattribute.separator = |
See Also
- Discussion on Enabling LDAP Attributes
LDAP Attribute Cookie Encode
Property
com.sun.am.policy.amFilter.ldapattribute.cookie.encode
Description
This property specifies whether the LDAP Attribute needs to be encoded before being set as a cookie.
Valid Values
Hot-Swap Enabled
Yes
Applicable Modes of Operation
SSO_ONLY, URL_POLICY, J2EE_POLICY, ALL
Example
com.sun.am.policy.amFilter.ldapattribute.cookie.encode = true
See Also
FQDN Default
Property
com.sun.am.policy.amFilter.fqdn.default
Description
This property specifies the default fully qualified name of the host where the agent is installed. This property is used by the agent to take corrective action in the case where the user may have typed in an incorrect URL such as by specifying partial hostname or using an IP address to access the protected resources.
Valid Values
The fully qualified domain name of the host where the agent is installed.
Note
- This property is required for the agent to function correctly. An invalid value for this property can lead to the system becoming inaccessible by the end users.
- This property is set during the agent installation and should be changed only if absolutely necessary.
- This property along with the values set in FQDN Map property govern how the agent handles access requests that do not present a fully qualified host name in the request URLs.
- Mappings specified in the FQDN Map property take precedence over the value specified for this property.
Hot-Swap Enabled
Yes
Applicable Modes of Operation
SSO_ONLY, URL_POLICY, J2EE_POLICY, ALL
Example
com.sun.am.policy.amFilter.fqdn.default = www.mycompany.com
See Also
- Discussion on Configuring FQDN Handling
FQDN Map
Property
com.sun.am.policy.amFilter.fqdn.map
Description
The FQDN Map is a simple map that enables the agent to take corrective action in the case where the users may have typed in an incorrect URL such as by specifying partial hostname or using an IP address to access protected resources.
Valid Values
Valid values must comply with the syntax of this property which represent invalid FQDN values mapped to their corresponding valid counterparts.
Note
- This property must conform to the rules and format of MAP construct as described in "Map Constructs in the Configuration File".
- The names used in this map are partial or incorrect FQDN Names that the user may use to access the system. The corresponding values are their valid counterparts.
- Mappings specified in this property take precedence over the value specified for the Default FQDN property.
- This property is commented out during agent installation and should be uncommented, if necessary.
Hot-Swap Enabled
Yes
Applicable Modes of Operation
SSO_ONLY, URL_POLICY, J2EE_POLICY, ALL
Example
com.sun.am.policy.amFilter.fqdn.map[myserver]=myserver.mydomain.com
See Also
J2EE Authentication Handler
Property
com.sun.am.policy.amFilter.j2ee.auth.handler
Description
This property specifies the J2EE Authentication Handler to be used by the agent in order to authenticate the logged on user with the application server. This property is necessary for J2EE_POLICY mode and ALL modes of operation.
Valid Values
As set during agent installation. Any other value is not valid.
Hot-Swap Enabled
Yes
Applicable Modes of Operation
SSO_ONLY, URL_POLICY, J2EE_POLICY, ALL
See Also
- Discussion on Agent Filter Modes
- Discussion on Enabling Web-Tier Declarative Security
J2EE Logout Handler
Property
com.sun.am.policy.amFilter.j2ee.logout.handler
Description
This property specifies the J2EE Logout Handler to be used by the agent in order to log out the logged on user from the application server. This property is necessary for J2EE_POLICY mode and ALL modes of operation.
Valid Values
As set during agent installation. Any other value is not valid.
Hot-Swap Enabled
Yes
Applicable Modes of Operation
J2EE_POLICY, ALL
Example
com.sun.am.policy.amFilter.j2ee.logout.handler = com.sun.identity.agents.filter.GenericJ2EELogoutHandler
See Also
Login Form List
Property
com.sun.am.policy.amFilter.login.formList
Description
This property specifies the list of URIs that represent form-login-page as specified in the form-login-config elements of the protected application's deployment descriptors (web.xml) along with the context path of the deployed application. This property is used by the agent to intercept login request and take appropriate action.
Valid Values
- Valid values must comply with the syntax of this property.
- Valid values should be as specified in the form-login-page element of web.xml of the deployed application along with the context path of the application.
Note
- This property must conform to the rules and format of LIST construct as described in the General Notes on the Agent Configuration File section.
- The value of form-login-page in the web.xml of the deployed application is only a part URI which must be preceded with the context path of the application. For instance, if the application context path is /Portal and the value of form-login-page is /jsp/login.jsp, then the actual value for this configuration becomes /Portal/jsp/login.jsp.
- Failure to set this property correctly can result in malfunction of the agent resulting in the application or portions thereof becoming inaccessible.
Hot-Swap Enabled
Yes
Applicable Modes of Operation
J2EE_POLICY, ALL
Examples
com.sun.am.policy.amFilter.login.formList[0] = /Portal/jsp/login.jsp
com.sun.am.policy.amFilter.login.formList[1] = /BankApp/LoginForm.html
See Also
- Discussion on Enabling Web-Tier Declarative Security
Form Login Use Internal Flag
Property
com.sun.am.policy.amFilter.login.use.internal
Description
This property specifies if the agent must use internal content for handling form login requests.
Valid Values
- true: indicates that internal content will be used for form login requests.
- false: indicates that internal content will not be used for form login requests.
Note
- When set to false, the agent expects the application to handle form login requests in a manner that complies with the agent requirements. Please refer to the discussion on Enabling Web-Tier Declarative Security for more information on this mechanism.
- When set to true, the agent uses internal content as specified in a file named FormLoginContent.txt available in the agent installation directory, which can be modified as required. Please refer to the discussion on Enabling Web-Tier Declarative Security for more information on this mechanism.
- This property defaults to true and should only be changed if the corresponding form login pages have been modified as required by the agent. Please refer to the discussion on Enabling Web-Tier Declarative Security for more information on this mechanism.
Hot-Swap Enabled
Yes
Applicable Modes of Operation
J2EE_POLICY, ALL
Example
com.sun.am.policy.amFilter.login.use.internal = true
See Also
- Discussion on Enabling Web-Tier Declarative Security
Form Login Content File Name
Property
com.sun.am.policy.amFilter.login.filename
Description
This property specifies the name of the file that has the necessary content needed to handle form login requests.
Valid Values
- Name of a file that exists in the locale directory of the agent installation, or
- The complete path to a file that exists on the system and is readable by the server process on which the agent is installed.
Note
- This property does not apply if the value of the property Form Login Use Internal Flag is set to false.
- The file specified by the value of this property must have read permissions for the server process on which the agent is installed.
- The file specified by the value of this property must comply with the agent requirements needed to handle form login requests accordingly. Please refer to Enabling Web-Tier Declarative Security for further details on how this mechanism works.
- This property is set during agent installation and should not be changed unless absolutely necessary.
Hot-Swap Enabled
Yes
Applicable Modes of Operation
J2EE_POLICY, ALL
Example
com.sun.am.policy.amFilter.login.filename = CustomFormLoginContent.txt
See Also
- Discussion on Enabling Web-Tier Declarative Security
Preserve Referer for Form Login Flag
Property
com.sun.am.policy.amFilter.login.preserve.referer
Description
This property specifies if the referer should be used as the post authentication destination URL when a user does not have sufficient credentials to access the protected resource.
Valid Values
Hot-Swap Enabled
Yes
Applicable Modes of Operation
J2EE_POLICY, ALL
Example
com.sun.am.policy.amFilter.login.preserve.referer = true
See Also
- Discussion on Enabling Web-Tier Declarative Security
Default Referer Map for Form Login
Property
com.sun.am.policy.amFilter.login.referer.map
Description
This property specifies the application specific URI that will be used in case the referer is not set during the form-login sequence and the Preserve Referer flag has been enabled.
Valid Values
The URI to be used for a given application protected by this agent.
Note
- This property must conform to the rules and format of MAP construct as described in "Map Constructs in the Configuration File".
- The names used in this map are context path names of the application without the leading ’/’ character.
- If the entry in this map applies to the default web application, the string “DEFAULT_WEB_APP” should be used for the name.
- The values specified in this map can be any valid URIs on the protected application server.
- This property is commented out during agent installation and should be uncommented if its use is necessary.
- This property is not used if the value of the property Preserve Referer is set as false.
Hot-Swap Enabled
Yes
See Also
Examples
com.sun.am.policy.amFilter.login.referer.map[Portal]=/Portal/index.html
com.sun.am.policy.amFilter.login.referer.map[BankApp]=/BankApp/welcome.htm l
Applicable Modes of Operation
J2EE_POLICY, ALL
Cookie Reset Enable Flag
Property
com.sun.am.policy.amFilter.cookieReset.enable
Description
This property specifies if the Cookie Reset mechanism will be enabled for the agent. When enabled, the agent will reset various cookies as specified in by the property Cookie Reset List when the user tries to access a protected resource with insufficient credentials.
Valid Values
Hot-Swap Enabled
Yes
Applicable Modes of Operation
SSO_ONLY, URL_POLICY, J2EE_POLICY, ALL
Example
com.sun.am.policy.amFilter.cookieReset.enable = true
See Also
- Discussion on Using Cookie Reset Functionality
Cookie Reset List
Property
com.sun.am.policy.amFilter.cookieReset.cookieList
Description
This property specifies a list of cookie names that must be reset when a user tries to access a protected resource with insufficient credentials. This property does not take effect if the Cookie Reset Enable Flag property is set to false.
Valid Values
Valid values must comply with the syntax of this property.
Note
- This property must conform to the rules and format of LIST construct as described in "List Constructs in the Configuration File".
- This property is set during the agent installation and must not be changed unless absolutely necessary.
- Invalid or inappropriate value for this property may result in unauthorized access to protected system resources.
Hot-Swap Enabled
Yes
Applicable Modes of Operation
SSO_ONLY, URL_POLICY, J2EE_POLICY, ALL
Example
com.sun.am.policy.amFilter.cookieReset.cookieList[0] = SESSIONID
See Also
- Discussion on Using Cookie Reset Functionality
Cookie Reset Domain Map
Property
com.sun.am.policy.amFilter.cookieReset.domainMap
Description
This property specifies a Map, which links the cookie names as specified in the Cookie Reset List property to domain names that would be used when resetting those cookies. This property does not take effect if the Cookie Reset Enable Flag property is set to false.
Valid Values
- Valid values must comply with the syntax of this property.
- Each value should be associated with the correct cookie name as specified in the property Cookie Reset List. The domain names should conform to the requirements of HTTP Cookie domain names.
Note
- This property must conform to the rules and format of MAP construct as described in "Map Constructs in the Configuration File".
- This property is set during the agent installation and must not be changed unless absolutely necessary.
- Invalid or inappropriate value for this property may result in unauthorized access to protected system resources.
Hot-Swap Enabled
Yes
Applicable Modes of Operation
SSO_ONLY, URL_POLICY, J2EE_POLICY, ALL
Example
com.sun.am.policy.amFilter.cookieReset.domainMap[SESSIONID] = mycompany.com
See Also
- Discussion on Using Cookie Reset Functionality
Cookie Reset Path Map
Property
com.sun.am.policy.amFilter.cookieReset.pathMap
Description
This property specifies a Map, which links the cookie names as specified in the Cookie Reset List property to paths that would be used when resetting those cookies. This property does not take effect if the Cookie Reset Enable Flag property is set to false.
Valid Values
- Valid values must comply with the syntax of this property.
- Each value should be associated with the correct cookie name as specified in the property Cookie Reset List. The path values should conform to the requirements of HTTP Cookie paths.
Note
- This property must conform to the rules and format of MAP construct as described in "Map Constructs in the Configuration File".
- This property is set during the agent installation and must not be changed unless absolutely necessary.
- Invalid or inappropriate value for this property may result in unauthorized access to protected system resources.
Hot-Swap Enabled
Yes
Applicable Modes of Operation
SSO_ONLY, URL_POLICY, J2EE_POLICY, ALL
Example
com.sun.am.policy.amFilter.cookieReset.pathMap[SESSIONID] = /
See Also
- Discussion on Using Cookie Reset Functionality
Audit Log Level
Property
com.sun.am.policy.amFilter.audit.level
Description
This property specifies the audit log level used by the agent that dictates the output of audit logs for various user accesses. This property applies to all accessed URLs in the system, which are protected by the agent.
Valid Values
The valid value for this property could be any one of the strings: NONE, LOG_ALLOW, LOG_DENY, or LOG_BOTH.
Note
- When set to NONE, no audit logs are recorded by the agent.
- When set to LOG_ALLOW, only access requests that are granted are logged.
- When set to LOG_DENY, only access requests that are denied are logged.
- When set to LOG_BOTH, all access requests are logged.
- Invalid value specified for this property would result in the agent defaulting to LOG_BOTH.
Hot-Swap Enabled
Yes
Applicable Modes of Operation
NONE, SSO_ONLY, URL_POLICY, J2EE_POLICY, ALL
Example
com.sun.am.policy.amFilter.audit.level = LOG_ALLOW
See Also
Redirect Counter Cookie Name
Property
com.sun.am.policy.amFilter.redirect.cookie.name
Description
This property specifies the name of the cookie that will be used to track the number of successive single point redirects made for the user.
Valid Values
A string that represents the name of the cookie to be issued by the agent in order to track the number of single point redirects made for the user.
Note
This property is set during agent installation and must not be changed unless absolutely necessary.
Hot-Swap Enabled
Yes
Applicable Modes of Operation
NONE, SSO_ONLY, URL_POLICY, J2EE_POLICY, ALL
Example
com.sun.am.policy.amFilter.redirect.cookie.name = amFilterRDParam
See Also
- Discussion on Redirect Attempt Limit
Redirect Attempt Limit
Property
com.sun.am.policy.amFilter.redirect.attempt.limit
Description
This property specifies the number of successive single point redirects that a user can make using a single browser session, which will trigger the blocking of the user request.
Valid Values
Unsigned integer value, including 0, which indicates the number of successive redirect attempts that are allowed for any user trying to gain access to protected resources.
Hot-Swap Enabled
Yes
Applicable Modes of Operation
NONE, SSO_ONLY, URL_POLICY, J2EE_POLICY, ALL
Example
com.sun.am.policy.amFilter.redirect.attempt.limit = 10
See Also
- Discussion on Redirect Attempt Limit
Legacy User Agent Support Flag
Property
com.sun.am.policy.amFilter.legacy.support.enable
Description
This property specifies if the agent protected applications will be accessed by legacy browsers. When enabled, the agent will be able to take specific action for such browsers to ensure that the features not supported by such browsers do not come in the way of agent functionality.
Valid Values
Hot-Swap Enabled
Yes
Applicable Modes of Operation
SSO_ONLY, URL_POLICY, J2EE_POLICY, ALL
Example
com.sun.am.policy.amFilter.legacy.support.enable = true
See Also
Legacy User Agent List
Property
com.sun.am.policy.amFilter.legacy.userAgent
Description
This property specifies a list of User-Agent strings that may be used to identify legacy browsers. Certain legacy browsers do not handle the client side redirect request correctly when the redirect source and destination URLs are the same. In such cases, browsers identified by this list of User-Agent strings are sent to an intermediate location before being redirected to the original location.
Valid Values
- Valid values must comply with the syntax of this property.
- Each value in this list must be a valid pattern that can match the value of the HTTP header “user-agent” as sent by a legacy browser.
- The value string may also use a wild card character '*' to indicate one or more values together.
Note
- This property must conform to the rules and format of LIST construct as described in "List Constructs in the Configuration File".
- This property is set during the agent installation and must not be changed unless absolutely necessary.
- Invalid or inappropriate value for this property may result in excessive redirects for the logged on user, which may degrade the overall system performance.
Hot-Swap Enabled
Yes
Applicable Modes of Operation
SSO_ONLY, URL_POLICY, J2EE_POLICY, ALL
Example
com.sun.am.policy.amFilter.legacy.userAgent[0] = Mozilla/4.7*
See Also
Legacy User-Agent Intermediate Redirect URI
Property
com.sun.am.policy.amFilter.legacy.redirect.uri
Description
This property specifies the URI to which the agent will redirect the legacy browsers if necessary.
Valid Values
A valid URI that belongs to the application, which is the primary application for this server.
Note
- Invalid value specified for this property can result in the application becoming inaccessible.
- This property does not come into effect if there are no values specified for the property Legacy User-Agent List or the value specified for the property Legacy User Agent Support flag is false.
- This property is set during agent installation and must not be changed unless absolutely necessary.
Hot-Swap Enabled
Yes
Applicable Modes of Operation
SSO_ONLY, URL_POLICY, J2EE_POLICY, ALL
Example
com.sun.am.policy.amFilter.legacy.redirect.uri = /Portal/dummy_uri
See Also
Port Check Enable Flag
Property
com.sun.am.policy.amFilter.port.check.enable
Description
This property specifies if the agent will use the default port mapping as specified in the property Port Map to resolve issues arising from incorrect HOST header values as sent by various browsers.
Valid Values
- true: indicates that the port mapping is enabled.
- false: indicates that the port mapping is disabled.
Note
- Invalid or inappropriate value specified for this property can result in the system becoming inaccessible to certain browsers.
- This property is set during agent installation and must be changed only if absolutely necessary.
- This property is useful when the agent and the Sun ONE Identity Server authentication service are installed on the same host but different ports. In such situations, certain browsers may not reset the HOST header correctly when being redirected back to the agent-protected resource.
Hot-Swap Enabled
Yes
Applicable Modes of Operation
SSO_ONLY, URL_POLICY, J2EE_POLICY, ALL
Example
com.sun.am.policy.amFilter.port.check.enable = true
See Also
Port Check Map
Property
com.sun.am.policy.amFilter.port.check.map
Description
This property specifies a Map of various ports where the agent-enabled listeners operate. This property is necessary to ensure that the resource policies are evaluated correctly even if the client provided HOST header value is invalid.
Valid Values
- Valid values must comply with the syntax of this property.
- The names specified for this map should be valid port numbers and the corresponding values must either be http or https.
Note
- This property must conform to the rules and format of MAP construct as described in "Map Constructs in the Configuration File".
- Please ensure that the listeners operating on each of these ports match the protocol scheme that is mentioned in their values.
- Invalid or inappropriate value specified for this property can result in the system becoming inaccessible.
- This property is set during agent installation and should be changed as necessary.
Hot-Swap Enabled
Yes
Applicable Modes of Operation
SSO_ONLY, URL_POLICY, J2EE_POLICY, ALL
Example
com.sun.am.policy.amFilter.port.check.map[80] = http
See Also
Port Check Content File Name
Property
com.sun.am.policy.amFilter.port.check.filename
Description
This property specifies the name of the file that has the necessary content needed to handle requests that need port correction.
Valid Values
- Name of a file that exists in the locale directory of the agent installation, or
- The complete path to a file that exists on the system and is readable by the server process on which the agent is installed.
Note
- This property does not apply if the value of the property Port Check Enable Flag is set to false.
- The file being pointed to by the value of this property must have read permissions for the server process on which the agent is installed.
- The file being pointed to by the value of this property must comply with the agent requirements needed to handle invalid port requests accordingly. Please refer to the section Enabling Port Check Functionality for further details of how this mechanism works.
- This property is set during agent installation and should not be changed unless absolutely necessary.
Hot-Swap Enabled
Yes
Applicable Modes of Operation
SSO_ONLY, URL_POLICY, J2EE_POLICY, ALL
Example
com.sun.am.policy.amFilter.port.check.filename = CustomPortCheckContent.txt
See Also
Fetch All Operation Flag
Property
com.sun.am.policy.amRealm.allow.fetch.all
Description
This property specifies if the agent should allow a fetch all operation, which may be needed to achieve console integration of the application server with Sun ONE Identity Server.
Valid Values
- true: indicates that fetch all operation is allowed
- false: indicates that fetch all operation is not allowed
Note
- When set, the list of users and roles as defined in Sun ONE Identity Server may become available in the application server's console.
- Since this setting can enable the application server administrator to see Sun ONE Identity Server principals in the console, it should be used with caution.
- The default value of this setting is set during agent installation and should be changed as necessary.
Hot-Swap Enabled
Yes
Applicable Modes of Operation
J2EE_POLICY, ALL
Example
com.sun.am.policy.amRealm.allow.fetch.all = false
People Container Level
Property
com.sun.am.policy.amRealm.peoplecontainer.level
Description
This property specifies the people container level to be used when searching for principals in Sun ONE Identity Server.
Valid Values
Non-zero unsigned integer representing the People Container Level in Sun ONE Identity Server, which may be used when searching for principals.
Note
This property is set during agent installation and need not be changed unless absolutely necessary.
Hot-Swap Enabled
Yes
Applicable Modes of Operation
J2EE_POLICY, ALL
Example
com.sun.am.policy.amRealm.peoplecontainer.level = 1
See Also
Organization DN
Property
com.sun.am.policy.amRealm.organization.dn
Description
This property specifies the DN for the organization, which will be used to search principals in Sun ONE Identity Server.
Valid Values
String representing the organization DN for the organization for which this agent has been installed.
Note
This property is set during agent installation and must not be changed unless absolutely necessary.
Hot-Swap Enabled
Yes
Applicable Modes of Operation
SSO_ONLY, URL_POLICY, J2EE_POLICY, ALL
Example
com.sun.am.policy.amRealm.organization.dn = dc=example,dc=com
See Also
Audit Log Disposition
Property
com.sun.am.policy.amAgentLog.disposition
Description
This property specifies the disposition of audit log that the agent will use when writing audit log messages.
Valid Values
The valid values for this property is any string from the following: LOCAL, REMOTE, ALL
Note
- When set to LOCAL, the audit logs are kept on the local system where the agent is installed.
- When set to REMOTE, the audit logs are sent to the remote system where the Sun ONE Identity Server Log Service is available.
- When set to ALL, the audit logs are kept on the local system as well as sent to the remote system where the Sun ONE Identity Server Log Service is available.
- In the event that the value is set to REMOTE and the agent is unable to send the log message to the remote system, the log message will be written to the local system where agent is installed.
Hot-Swap Enabled
Yes
Applicable Modes of Operation
NONE, SSO_ONLY, URL_POLICY, J2EE_POLICY, ALL
Example
com.sun.am.policy.amAgentLog.disposition = REMOTE
See Also
Audit Log Local File Name
Property
com.sun.am.policy.amAgentLog.local.file
Description
This property specifies the file name used by the agent to capture audit logs on the system where the agent is installed.
Valid Values
String representing the complete path name of the file to be used by agent to record audit messages.
Hot-Swap Enabled
Yes
Applicable Modes of Operation
NONE, SSO_ONLY, URL_POLICY, J2EE_POLICY, ALL
Example
com.sun.am.policy.amAgentLog.local.file = /var/opt/logs/agent.log
See Also
Audit Log Local File Rotate Flag
Property
com.sun.am.policy.amAgentLog.local.file.rotate.enable
Description
This property specifies if the file used by the agent for capturing audit messages on the local system should be rotated or not.
Valid Values
Hot-Swap Enabled
Yes
Applicable Modes of Operation
NONE, SSO_ONLY, URL_POLICY, J2EE_POLICY, ALL
Example
com.sun.am.policy.amAgentLog.local.file.rotate.enable = true
See Also
Audit Log Local File Rotation Size
Property
com.sun.am.policy.amAgentLog.local.file.rotate.size
Description
This property specifies the size (in bytes) of the file used by the agent for capturing audit messages on the local system, beyond which this file should be rotated. This property does not take effect unless the value of the property Audit Log Local File Rotation Flag is set to true.
Valid Values
Non-zero unsigned integer indicating the size in bytes to be used to evaluate when the log file needs to be rotated.
Note
- Default value of this property is 52428800 bytes (~ 50 MB) and should be changed as necessary.
- This property is not used if the Audit Log Local File Rotate Flag is set to false
Hot-Swap Enabled
Yes
Applicable Modes of Operation
NONE, SSO_ONLY, URL_POLICY, J2EE_POLICY, ALL
Example
com.sun.am.policy.amAgentLog.local.file.rotate.size = 52428800
See Also
Audit Log Remote File Name
Property
com.sun.am.policy.amAgentLog.remote.file
Description
This property specifies the remote file name to be used by the agent for capturing audit messages on the remote system where the Sun ONE Identity Server Log service is available.
Valid Values
A String representing the file name (without a path) that will be used by the Sun ONE Identity Server Log service on the remote system to capture the audit messages sent by the agent.
Note
- If the file name specified by this property is already in use by another entity in the Sun ONE Identity Server network environment, the audit messages sent by this agent will be captured in the same file.
- Invalid value specified for this property can result in the audit messages being lost by the system, which may not be available in the Local audit log file as well.
Hot-Swap Enabled
Yes
Applicable Modes of Operation
NONE, SSO_ONLY, URL_POLICY, J2EE_POLICY, ALL
Example
com.sun.am.policy.amAgentLog.remote.file = myAgentLog
See Also
Bypass Principal List
Property
com.sun.am.policy.amRealm.bypass.auth.principalList
Description
This property specifies a list of principals that are bypassed by the agent for authentication and search purposes.
Valid Values
As set by the agent installation program. Any other value will be invalid.
Note
- This property is only used for the BEA WebLogic Server 6.1 SP2, BEA WebLogic Server 7.0 SP2, and BEA WebLogic Server 8.1 agents.
- Invalid or inappropriate value specified for this property can lead to the system becoming inaccessible for some or all users.
- This property must conform to the rules and format of LIST construct as described in the General Notes on the Agent Configuration File section.
Hot-Swap Enabled
Yes
Applicable Modes of Operation
J2EE_POLICY, ALL
Example
com.sun.am.policy.amRealm.bypass.auth.principalList[0] = system
See Also
General Notes on the Agent Configuration File
PeopleSoft User Mapping
Property
com.sun.am.policy.amPeopleSoft.user.mapping
Description
This property specifies the way PeopleSoft user is mapped to Sun ONE Identity Server user.
Valid Values
The valid value for this key can be one of the three strings: USE_DN, LDAP, or HTTP_HEADER. Any other value will be treated as an incorrect entry and the agent will default to USE_DN.
Mode USE_DN
In this mode of user mapping, the user ID from SSO token is used as the mapping attribute. user ID of the Sun ONE Identity Server user should be the same as that of the PeopleSoft user.
Note
The following property is not used in this mode: com.sun.am.policy.amPeopleSoft.user.attribute.name
Mode LDAP
In this mode of user mapping, PeopleSoft user is set as an LDAP attribute in Sun ONE Identity Server’s user profile. Name of the LDAP attribute should be specified in the following property:
com.sun.am.policy.amPeopleSoft.user.attribute.name
Mode HTTP_HEADER
In this mode, HTTP header contains the PeopleSoft user id. The name of the LDAP attribute should be specified in the following property:
com.sun.am.policy.amPeopleSoft.user.attribute.name
Hot-Swap Enabled
No
Example
com.sun.am.policy.amPeopleSoft.user.mapping = USE_DN
See Also
User Attribute Containing PeopleSoft User
User Attribute Containing PeopleSoft User
Property
com.sun.am.policy.amPeopleSoft.user.attribute.name
Description
This property specifies the name of the attribute which contains the PeopleSoft user ID.
Valid Values
In the LDAP mode of user mapping, it should be a valid LDAP attribute name and in the HTTP_HEADER mode of user mapping, it should be the name of HTTP Header containing PeopleSoft user ID.
Note
Valid but inappropriate value of this property may lead to the application being unreachable by the users.
Hot-Swap Enabled
No
Examples
com.sun.am.policy.amPeopleSoft.user.attribute.name = employeenumber
com.sun.am.policy.amPeopleSoft.user.attribute.name = CUSTOM-HEADER
See Also:
Validate SSO Token in PeopleCode flag
Property
com.sun.am.policy.amPeopleSoft.peoplecode.validate.sso
Description
This property specifies if the validation of SSO token should be done in PeopleSoft application server for extra security.
Valid Values
true: indicates that the validation will be done
false: indicates that no validation will be performed
Hot-Swap Enabled
No
Example
com.sun.am.policy.amPeopleSoft.peoplecode.validate.sso = true
URL Decode SSO Token Flag
Property
com.sun.am.policy.amPeopleSoft.ssotoken.urldecode
Description
This property indicates if the SSO Token needs to be URL decoded by the agent before it is used in PeopleCode.
Valid Values
true: indicates that the token should be URL Decoded.
false: indicates that the token should not be URL Decoded.
Note
Valid but inappropriate value of this property may lead to the application being unreachable by the users.
Hot-Swap Enabled
No
Example
com.sun.am.policy.amPeopleSoft.ssotoken.urldecode = true
Authentication Module
Property
com.sun.am.policy.amPeopleSoft.auth.module
Description
This property specifies the authentication module to be used for ensuring secure access to the protected resources.
Valid Values
A string representing the name of the authentication module to be used which can be set as the URI parameter when redirecting the user to Sun ONE Identity Server Authentication Service.
Note
The value of this property is set during installation and must not be changed unless absolutely necessary.
Hot-Swap Enabled
Yes
Example
com.sun.am.policy.amPeopleSoft.auth.module = LDAP
Goto URL
Property
com.sun.am.policy.amPeopleSoft.goto.url
Description
This property indicates the destination address for users who have successfully authenticated using the Sun ONE Identity Server Authentication service.
Valid Values
A string representing the complete and fully qualified URL of the PeopleSoft application where the users will be directed after successful sign on.
Hot-Swap Enabled
Yes
Examples
com.sun.am.policy.amPeopleSoft.goto.url = http://www.mycompany.com:8001/servlets/iclientservlet/peoplesoft8/?cmd=start
com.sun.am.policy.amPeopleSoft.goto.url = http://www.mycompany.com:8001/psp/ps/EMPLOYEE/ERP/h/?tab=DEFAULT
com.sun.am.policy.amPeopleSoft.goto.url = http://www.mycompany.com:8001/psp/ps/EMPLOYEE/HRMS/h/?tab=DEFAULT
Display Resource Root
Property
com.sun.am.policy.amPeopleSoft.display.resource.root
Description
This property specifies the directory where all the files that can be displayed to the user are available to the agent.
Valid Values
A string representing the complete path to the directory where the files that can be displayed are kept.
Note
- If the value of this property is incorrect, the agent will not be able to display the necessary content to the user and would therefore default to redirecting the user to the Sun ONE Identity Server Authentication Service for login.
- Any file that is displayed to the user from this directory is parsed by the agent before display and all occurrences of AUTH_LOGIN_URL are replaced by the actual login URL. If no occurrences of this string are found, no replacement is done.
Hot-Swap Enabled
Yes
Example
com.sun.am.policy.amPeopleSoft.display.resource.root = /www/public_html
Default Display Resource File Name
Property
com.sun.am.policy.amPeopleSoft.display.resource.default
Description
This property specifies the name of the default HTML file that the agent will display to the user if the query parameter cmd=display is passed in the request.
Valid Values
A string representing the name of the HTML file that must be displayed to the user when cmd=display is passed to the AgentAuthenticatorServlet. This file should exist in the directory specified in the Display Resource Root property and should be readable by the WebLogic Server process.
Note
- If this file is not available for any reason, the AgentAuthenticatorServlet will default to redirecting the user to the Login URL instead.
- The AgentAuthenticatorServlet will try to replace all occurrences of the string AUTH_LOGIN_URL with the appropriate login URL. If the contents of this file do not have any occurrences of this string, no replacement will be done.
- If another query parameter of the form resource=name is passed, the AgentAuthenticatorServlet will ignore this property and instead use the following property which specifies the Display Resource Map to determine the file name of the file to be displayed to the user.
- This property is set during the installation and must not be replaced unless absolutely necessary.
Hot-Swap Enabled
Yes
Example
com.sun.am.policy.amPeopleSoft.display.resource.default = display.html
Display Resource Map
Property
com.sun.am.policy.amPeopleSoft.display.resource.map
Description
This property specifies a map which relates various names that can be mapped to actual HTML files in the Display Resource Root directory. When the AgentAuthenticatorServlet is invoked with the query parameters cmd=display and resource=name, the agent uses this map to identify the file name associated with the passed name value.
When found, the AgentAuthenticatorServlet will replace all occurrences of the string AUTH_LOGIN_URL in the text of this file and display the resulting text to the end user.
Valid Values
Valid values must comply with the syntax of this property. See Note and Example.
The specified file name in this map must correspond to a real HTML file that exists in the Display Resource Root directory and this file should be readable by the agent process.
Note
- The syntax of this property is: com.sun.am.policy.amPeopleSoft.display.resource.map[name]=filename, where name is the resource parameter value passed into the AgentAuthenticatorServlet and filename is the actual name of the HTML file that must be processed for display.
- Any number of such properties may be specified as long as they are valid properties conforming to the requirements stated above.
Hot-Swap Enabled
Yes
Examples
com.sun.am.policy.amPeopleSoft.display.resource.map[logout] = logout.html
com.sun.am.policy.amPeopleSoft.display.resource.map[error] = error.html
CDSSO Enable Flag
Property
com.sun.am.policy.amFilter.cdsso.enabled
Description
This property specifies if Cross Domain Single Sign On (CDSSO) is enabled for this agent. This property should be enabled if the agent resides in a DNS domain which is different from the Sun ONE Identity Server domain.
Valid Values
Hot-Swap Enabled
Yes
See Also
Example
com.sun.am.policy.amFilter.cdsso.enabled = true
Applicable Modes of Operation
SSO_ONLY, URL_POLICY, J2EE_POLICY, ALL
CDC Servlet URL
Property
com.sun.am.policy.amFilter.cdsso.cdcServletURL[0]
Description
This property specifies the CDC Servlet URLs to be used by the agent to redirect incoming users without sufficient credentials to the Sun ONE Identity Server authentication service when CDSSO is enabled.
Valid Values
A string that represents the complete URL to be used as the redirect URL in order to send users without sufficient credentials to Sun ONE Identity Server authentication service.
Note
This property is set during agent installation and must not be changed unless absolutely necessary.
This property must conform to the rules and format of LIST construct as described in the section General Notes on the Agent Configuration File.
Hot-Swap Enabled
Yes
See Also
Example
com.sun.am.policy.amFilter.cdsso.cdcServletURL[0] = http://www.mycompany.com:58080/cdcservlet
Applicable Modes of Operation
SSO_ONLY, URL_POLICY, J2EE_POLICY, ALL
CDSSO Intermediate Redirect URI
Property
com.sun.am.policy.amFilter.cdsso.redirect.uri
Description
This property specifies the URI to which the CDSSO Controller will redirect the authentication responses. A valid value must be supplied if the CDSSO is enabled. By default, the value will be sunwCDSSORedirectURI.
Valid Values
A valid URI that belongs to the primary application on this server.
Note
- If an invalid value is specified for this property, it can result in CDSSO not functioning and the application becoming inaccessible.
- This property comes into effect only if CDSSO has been enabled.
- This property is set during agent installation to sunwCDSSORedirectURI by default and must not be changed unless absolutely necessary.
Hot-Swap Enabled
Yes
Example
com.sun.am.policy.amFilter.cdsso.redirect.uri = /sunwCDSSORedirectURI
See Also
Applicable Modes of Operation
SSO_ONLY, URL_POLICY, J2EE_POLICY, ALL
CDSSO Request Cookie Name
Property
com.sun.am.policy.amFilter.cdsso.cookie.name
Description
This property specifies the name of the cookie that will be used to keep track of the user requested resource when CDSSO is enabled.
Valid Values
A string that represents the name of the cookie to be issued by the agent in order to keep track of the user requested resource when CDSSO is enabled.
Note
This property is set during agent installation and need not be changed unless absolutely necessary.
Hot-Swap Enabled
Yes
Example
com.sun.am.policy.amFilter.cdsso.cookie.name = amFilterCDSSORequest
See Also
Applicable Modes of Operation
SSO_ONLY, URL_POLICY, J2EE_POLICY, ALL
CDSSO Liberty Assertion Validity Clock Skew Factor
Property
com.sun.am.policy.amFilter.cdsso.clock.skew
Description
This property specifies a skew factor (time in seconds) to be used by the agent to determine the validity of the CDSSO AuthnResponse assertion. This property provides a means to avoid request denials caused by expired assertions, which are related to network latency.
Valid Values
Unsigned integer value, including 0, which indicates the amount of time in seconds that will be used by the agent to create an interval window based on the system time of the agents’ host machine for validating the assertions.
Hot-Swap Enabled
Yes
See Also
Example
com.sun.am.policy.amFilter.cdsso.clock.skew = 90
Applicable Modes of Operation
SSO_ONLY, URL_POLICY, J2EE_POLICY, ALL
Login Form Error List
Property
com.sun.am.policy.amFilter.login.errorList
Description
This property specifies the list of URIs that represent the form-error-page as specified in the form-login-config elements of the protected application’s deployment descriptors (web.xml) along with the context path of the deployed application. This property is used by the agent to intercept error page requests and take appropriate action.
Valid Values
- Values of this property must comply with the syntax of this property.
- Values should be as specified in the form-error-page element of web.xml of the deployed application along with the context path of the application.
Note
- This property is applicable only to the agents for Oracle 9iAS R2, Oracle 10g and Tomcat Server 4.1.27.
- This property must conform to the rules and format of LIST construct as described in the section General Notes on the Agent Configuration File.
- The value of form-error-page in web.xml of deployed application is only a part URI, which must be preceded with the context path of the application. For instance, if the application context path is /Portal and the value of form-error-page is /jsp/error.jsp, then the actual value for this configuration becomes /Portal/jsp/error.jsp.
- Failure to set this property correctly can lead to the malfunctioning of the agent resulting in the application or portions thereof becoming inaccessible.
Hot-Swap Enabled
Yes
Examples
com.sun.am.policy.amFilter.login.errorList[0] = /Portal/jsp/error.jsp
com.sun.am.policy.amFilter.login.errorList[1] = /BankApp/LoginError.html
See Also
Applicable Modes of Operation
J2EE_POLICY, ALL
Agent Operation Mode Map
Property
com.sun.am.policy.amFilter.mode.map
Description
This property allows the agent filter to be configured for different modes of operation for different deployed applications. The value of operation mode specified for a given application in this map takes precedence over the agent operation mode.
Valid Values
An appropriate agent operation mode for a given application protected by this agent.
Note
- This property must conform to the rules and format of MAP construct as described in "Map Constructs in the Configuration File".
- This property is set during agent installation, if needed, and should not be changed unless absolutely necessary.
- The names used in this map are context path names of the application without the leading ’/’ character.
- The values specified in this map can be any valid operation modes of the agent. For details on various operation modes, please refer to the section Agent Filter Modes.
- This property takes precedence over the agent operation mode specified by the property com.sun.am.policy.amFilter.mode.
- For applications that are not explicitly added to this map, the operation mode is determined by the property com.sun.am.policy.amFilter.mode.
- This property is applicable only to the agents for Oracle 9iAS R2, Oracle 10g and Tomcat Server 4.1.27.
Hot-Swap Enabled
No
See Also
Examples
com.sun.am.policy.amFilter.mode.map[Portal]=J2EE_POLICY
com.sun.am.policy.amFilter.mode.map[BankApp]=ALL
Applicable Modes of Operation
J2EE_POLICY, ALL
Enable Filtered Roles
Property
com.sun.am.policy.amRealm.filtered.roles.enable
Description
This property specifies if the agent should enable the use of filtered roles when evaluating role-to-principal mappings. By default, the agent uses static roles as defined in Sun ONE Identity Server. This behavior can be changed by setting the value of this property as true. When set to true, the agent will use both the static as well as the filtered roles to evaluate role-to-principal mappings.
Valid Values
true: indicates that the agent will use filtered roles for evaluating role-to-principal mappings.
false: indicates that the agent will not use filtered roles for evaluating role-to-principal mappings.
Hot-Swap Enabled
Yes
Applicable Modes of Operation
J2EE_POLICY, ALL
Example
com.sun.am.policy.amRealm.filtered.roles.enable = true
SAP User Mapping
Property
com.sun.am.policy.amSAP.user.mapping
Description
This property specifies the way an SAP Enterprise Portal user is mapped to an Identity Server user.
Valid Values
The valid value for this key can be one of the following three strings: USE_DN, LDAP, and HTTP_HEADER. Any other value will be treated as invalid and the agent will default to USE_DN.
Mode USE_DN
In this mode, the user ID from SSO token is used as the mapping attribute. User ID of the Identity Server user should be same as that of the SAP user. Note that in this mode, the property com.sun.am.policy.amSAP.user.attribute.name is not used.
Mode LDAP
In this mode, the SAP user name is set as an LDAP attribute in Identity Server’s user profile. Name of the LDAP attribute should be specified in the property com.sun.am.policy.amSAP.user.attribute.name.
Mode HTTP_HEADER
In this mode, the HTTP header contains the SAP user name. Name of the HTTP header should be specified in the property com.sun.am.policy.amSAP.user.attribute.name.
Note
- When the mapping is set to HTTP_HEADER, the supplied HTTP_HEADER value must be provided with the incoming request. Headers injected by the agent itself may not be used as valid mapping configuration setting.
- This property is set to USE_DN during agent installation and should be changed as necessary.
- This property is used only for the policy agent for SAP Enterprise Portal 6.0 SP2.
Hot-Swap Enabled
Yes
Example
com.sun.am.policy.amSAP.user.mapping = USE_DN
See Also
User Attribute Containing SAP User-ID
User Attribute Containing SAP User-ID
Property
com.sun.am.policy.amSAP.user.attribute.name
Description
This property specifies the name of the attribute that contains the SAP user-id. Depending on the mode in which the agent enforces user mapping, this name could refer to an LDAP Attribute or to a HTTP Header field name.
Valid Values
In the LDAP mode of user mapping, the value should be a valid LDAP attribute name and in the HTTP_HEADER mode of user mapping, it should be the name of the HTTP Header that contains the SAP user-id.
Hot-Swap Enabled
No
Examples
com.sun.am.policy.amSAP.user.attribute.name = employeenumber
com.sun.am.policy.amSAP.user.attribute.name = CUSTOM-HEADER
See Also
Logon Frontend Tracking Cookie Name
Property
com.sun.am.policy.amSAP.lfe.cookie.name
Description
This property specifies the name of the cookie used by the agent logon frontend component to track the user session. This component is used within the iView Runtime Environment of SAP Enterprise Portal for processing login requests.
Valid Values
A string that represents the name of the cookie to be issued by the agent in order to track the user session and synchronize it with the Identity Server session.
Hot-Swap Enabled
Yes
Example
com.sun.am.policy.amSAP.lfe.cookie.name = amLFEParam
Goto URL
Property
com.sun.am.policy.amSAP.goto.url
Description
This property specifies the destination URL for users who have successfully authenticated using the Sun ONE Identity Server authentication service. However, this property is only used when the users that have been allowed access to the SAP Enterprise Portal click the SAP Enterprise Portal’s Logout link or button.
Valid Values
A string representing the complete and fully qualified URL of the destination where the users will be sent after successful logon.
Note
- The value of this property is set during installation and should not be changed unless absolutely necessary.
- The value of this property must be set to a valid entry point into the system. Failing to do so can result in the system becoming inaccessible.
- This property is used when a user clicks the logout link or button in SAP Enterprise Portal environment that is protected by the agent. It is not used to direct incoming users that have not yet established an SAP Enterprise Portal session.
- This property is specific to the agent for SAP Enterprise Portal 6.0 SP2.
Hot-Swap Enabled
Yes
Example
com.sun.am.policy.amSAP.goto.url = http://www.mycompany.com:50000/irj/index.html
Error Content File Name
Property
com.sun.am.policy.amSAP.error.filename
Description
This property specifies the name of the file that has the necessary content needed to handle error situations. When an error is encountered while evaluating the request, the agent displays the contents of this file after substituting the appropriate logout link in it.
Valid Values
Name of a file that exists in the Agent_install_dir/locale directory or the complete path to a file that exists on the system and is readable by the server process on which the agent is installed.
Note
- The file being pointed to by this property must have read permissions for the server process on which the agent is installed.
- If the contents of this file are modified or if this property is set to point to another file instead of the one provided by the agent, it must have the string am.sap.logout.url specified appropriately. This string is replaced by the agent with the actual logout URL before the contents of this file are displayed to the end user.
- This property is set during agent installation and should not be changed unless absolutely necessary.
- This property is specific to the agent for SAP Enterprise Portal 6.0 SP2.
Hot-Swap Enabled
Yes
Example
com.sun.am.policy.amSAP.error.filename = CustomErrorContent.txt
User Mapping
Property
com.sun.am.policy.user.mapping
Description
This property specifies the way a local user is mapped to an Identity Server user. Local user refers to the way the user is identified by the platform on which the agent is running.
Valid Values
The valid value for this key can be one of the following three strings: USE_DN, LDAP, or HTTP_HEADER. Any other value will be treated as invalid and the agent will default to USE_DN.
Mode USE_DN
In this mode, the user ID from the SSO token is used as the mapping attribute. The user ID of the Identity Server user should be the same as that of the local user. Note that in this mode, the following property is not used:
com.sun.am.policy.user.attribute.name
Mode LDAP
In this mode, the local user name is set as an LDAP attribute in Identity Server’s user profile. The name of the LDAP attribute should be specified in the following property:
com.sun.am.policy.user.attribute.name.
Caution
Ensure that the LDAP attribute contains one and only one value. Multiple values or a null value for the LDAP attribute are unrecognizable by the agent, which causes the agent to function improperly
Mode HTTP_HEADER
In this mode, the HTTP header contains the local user name. The name of the HTTP header should be specified in the following property:
com.sun.am.policy.user.attribute.name.
Caution
Ensure that the HTTP_HEADER attribute contains one and only one value. Multiple values or a null value for the HTTP_HEADER attribute are unrecognizable by the agent, which causes the agent to function improperly
Note
- When the mapping is set to HTTP_HEADER, the supplied HTTP header value must be provided with the incoming request. Headers injected by the agent itself can not be used as valid mapping configuration settings.
- This property is set to USE_DN during agent installation and should be changed as necessary.
Hot-Swap Enabled
Yes
Applicable Modes of Operation:
SSO_ONLY, URL_POLICY, J2EE_POLICY, ALL
Example
com.sun.am.policy.user.mapping = USE_DN
See Also
User Attribute Containing Agent User
User Mapping Mode
Property
com.sun.am.policy.user.mapping.mode
Description
This property specifies the mode through which the portal user is mapped to Identity Server user.
Valid Values
The valid value for this key can be one of the three strings: USE_DN, LDAP, or HTTP_HEADER
Note
Valid but inappropriate values for this property could lead to the application being unreachable by users.
Mode USE_DN
In this mode of user mapping, the user ID from the SSO token is used as the mapping attribute. The user ID of the Identity Server user should be the same as that of the WebLogic 8.1 SP2/SP3 Server/Portal user. By default the agent is running in USE_DN mode.
Mode LDAP
In this mode of user mapping, WebLogic 8.1 SP2/SP3 Server/Portal user is set as an LDAP attribute in Identity Server’s user profile. The name of the LDAP attribute should be specified in the following property:
com.sun.am.policy.user.attribute.name
Mode HTTP_HEADER
In this mode, the HTTP header contains the WebLogic 8.1 SP2/SP3 Server/Portal user ID. The name of the LDAP attribute should be specified in the following property:
com.sun.am.policy.user.attribute.name
Hot-Swap Enabled
Yes
Applicable Modes of Operation:
SSO_ONLY, URL_POLICY, J2EE_POLICY, ALL
Example
com.sun.am.policy.user.mapping = USE_DN
See Also
User Attribute Containing Agent User
User Attribute Containing Agent User
Property
com.sun.am.policy.user.attribute.name
Description
This property specifies the name of the attribute which contains the user ID.
Valid Values
In the LDAP mode of user mapping, a valid LDAP attribute name should be used. In the HTTP header mode of user mapping, the name of the HTTP header containing the user ID should be used.
Note
A valid but inappropriate value of this property may lead to the application being unreachable by users.
Hot-Swap Enabled
Yes
Applicable Modes of Operation
SSO_ONLY, URL_POLICY, J2EE_POLICY, ALL
Examples
com.sun.am.policy.user.attribute.name = employeenumber
com.sun.am.policy.user.attribute.name = CUSTOM-HEADER
See Also
Logout Parameter Map
Property
com.sun.am.policy.amFilter.logout.request.param.map
Description
This property specifies the application specific logout parameter value used by the agent to detect the need to invalidate the Application Server and Identity Server user. The logout parameter will be first searched in the HTTP request body depending on the value of the following parameter:
HTTP Request Body Introspect Flag
com.sun.am.policy.amFilter.logout.introspect.request.enableValid Values
If the value of this property is set to false, the Logout parameter will be searched in the HTTP request URI query string only. By default the introspect.request.enable property is set to true.
Note
- This property must conform to the rules and format of MAP construct as described in "Map Constructs in the Configuration File".
- The names used in this map are context path names of the application without the leading '/' character.
- - Either the presence of an entry in Logout Parameter Map or the presence of an entry in Logout URI Map will trigger the need to invalidate the user.
Hot-Swap Enabled
Yes
Applicable Modes of Operation
J2EE_POLICY, ALL
Example
If the agent is trying to protect a portal application with the context URI of /portaApp and the logout event for /portalApp adds a request parameter logout in the HTTP request, the Administrator needs to create the following entry for Logout Parameter Map:
com.sun.am.policy.amFilter.logout.request.param.map[portaApp]=logout
See Also
Logout URI Map
Property
com.sun.am.policy.amFilter.logout.uri.map
Description
This property specifies the application specific logout URI value used by the agent to detect the need to destroy/invalidate the Application Server and Identity Server sessions. If the request URI matches the logout URI specified in the map, the agent will proceed to invalidate the Application Server and Identity Server sessions.
Valid Values
A string that represents a valid URI.
Note
- This property must conform to the rules and format of MAP construct as described in "Map Constructs in the Configuration File".
- The names used in this map are context path names of the application without the leading ‘/’ character.
- Either the presence of an entry in Logout URI Map or the presence of an entry in Logout Parameter Map will trigger the need to invalidate the user.
Hot-Swap Enabled
Yes
Applicable Modes of Operation
J2EE_POLICY, ALL
Example
com.sun.am.policy.amFilter.logout.uri.map[portalApp]=/portalApp/logoutURL. html
See Also
Application Authentication Handler Map
Property
com.sun.am.policy.amFilter.mapped.authentication.handler
Description
This property specifies the application specific local authentication handler used by the agent to validate the user credentials with the application container. All applications protected by the agent can have an authentication handler.
If a specific application has an authentication handler; it will be loaded by the agent. If the agent fails to load the handler for an application that has an authentication handler specified in the map, the agent can malfunction, resulting in the application or portions thereof becoming inaccessible. If the application does not have an authentication handler specified in the map, then user credentials will be validated using the default authentication handler specified in the following property:
J2EE Authentication Handler
com.sun.am.policy.amFilter.j2ee.auth.handlerValid Values
A valid local authentication handler class.
Note
- The value of this property is set during installation and should not be changed unless absolutely necessary.
- This property must conform to the rules and format of MAP construct as described in "Map Constructs in the Configuration File".
- The names used in this map are context path names of the application without the leading ‘/’ character.
Hot-Swap Enabled
Yes
Applicable Modes of Operation
J2EE_POLICY, ALL
Example
com.sun.am.policy.amFilter.mapped.authentication.handler[PortalApp] = AuthenticationHandlerClassForPortal
com.sun.am.policy.amFilter.mapped.authentication.handler[BankApp] = AuthenticationHandlerClassForBank
See Also
Verification Handler Map
Property
com.sun.am.policy.amRealm.verification.handler.map
Description
This property specifies the application specific local verification handler used by the agent to validate the user credentials with the local repository. All applications protected by the agent can have a verification handler. If a specific application has a verification handler, it is loaded by the agent. If the agent fails to load the handler for an application that has a verification handler specified in the map, the agent can malfunction, resulting in the application or portions thereof becoming inaccessible. If the application does not have a verification handler specified in the map, no verification process for the user ID is invoked.
Valid Values
A valid local verification handler class.
Note
- This property must conform to the rules and format of MAP construct as described in "Map Constructs in the Configuration File".
- The names used in this map are context path names of the application without the leading ‘/’ character.
Hot-Swap Enabled
Yes
Applicable Modes of Operation
J2EE_POLICY, ALL
Example
com.sun.am.policy.amRealm.verification.handler.map[PortalApp] = VerificationHandlerClassForPortalApp
Global Verification Handler
Property
com.sun.am.policy.amRealm.verification.handler
Description
This property specifies the global or default verification handler used by the agent to validate the user credentials with the local repository. All applications protected by the agent will use this handler if a match for a local verification handler is not found.
Valid Values
A valid global verification handler class.
Hot-Swap Enabled
Yes
Applicable Modes of Operation
J2EE_POLICY, ALL
See Also:
HTTP Request Body Introspect Flag
Property
com.sun.am.policy.amFilter.logout.introspect.request.enable
Description
This property indicates whether or not the Logout parameter specified for the application in the following property for the application URI can be searched in the HTTP request body:
Logout Parameter Map
com.sun.am.policy.amFilter.logout.request.param.mapValid Values
A value of true indicates that the HTTP request can be searched for the Logout parameter while a value of false indicates that the HTTP request cannot be searched for the Logout parameter.
Hot-Swap Enabled
Yes
Applicable Modes of Operation
J2EE_POLICY, ALL
Example
com.sun.am.policy.amFilter.logout.introspect.request.enable = false
See Also:
Application Local Logout Handler Map
Property
com.sun.am.policy.amFilter.logout.application.handler.map
Description
This property specifies the application specific Local Logout Handler parameter used by the agent to invalidate the HTTP session in the Application server. All applications protected by the agent can have a Local Logout Handler. If a specific application has a Local Logout Handler, it will be loaded by the agent. If the agent fails to load the application specific Local Logout Handler, the agent can malfunction, resulting in the application or portions thereof becoming inaccessible.
Valid Values
Note
- The value of this property is set during installation and should not be changed unless absolutely necessary.
- This property must conform to the rules and format of MAP construct as described in "Map Constructs in the Configuration File".
- The names used in this map are context path names of the application without the leading ‘/’ character
Hot-Swap Enabled
Yes
Applicable Modes of Operation
J2EE_POLICY, ALL
Example
com.sun.am.policy.amFilter.logout.application.handler.map[sampleApp] = LocalLogoutHandlerForSampleApp
See Also: