Web Policy Agents Guide |
Appendix A
AMAgent PropertiesThe configuration of Web Policy Agents is largely determined by a set of properties present in the file AMAgent.properties. This appendix describes the properties in this file.
com.sun.am.cookieName
Description
The name of the cookie passed between Sun ONE Identity Server and the SDK.
Valid Values
The default value is iPlanetDirectoryPro. Changing the value of this property without making the corresponding change to the Identity Server will disable the SDK.
Example
com.sun.am.cookieName = iPlanetDirectoryPro
com.sun.am.namingURL
Description
The URL for the Sun ONE Identity Server Naming service.
Valid Values
The URL for the naming service
Example
com.sun.am.namingURL =http://nila.eng.example.com/amserver/namingservice
com.sun.am.policy.am.loginURL
Description
This property stores the URL of the login page on the Identity Server. If you have a failover server, you can enter its URL after a space after the primary server URL. See example.
Valid Values
URL of the login page on the Identity Server.
Example
com.sun.am.policy.am.loginURL=http://nila.eng.example.com:58080/amserver/UI/Login http://nila1.eng.example.com:58080/amserver/UI/Login
com.sun.am.policy.am.library.loginURL
Description
When the agent starts up, it authenticates itself as a valid agent with Sun ONE Identity Server. If a previously specified login URL must be exclusively used for redirecting users, then this property must be used to specify the Identity Server with which the agent library must authenticate.
Note
If the value of this property is not set, the value of com.sun.am.policy.am.loginURL will be used as the loginURL to authenticate the agent.
Valid Values
URL of the Sun ONE Identity Server login page where the agent library must authenticate.
Example
com.sun.am.policy.am.library.loginURL = http://nila.eng.example.com:58080/amserver/UI/Login
com.sun.am.logFile
Description
This property stores the name of the file to be used for logging messages. By default, the agent creates a directory called webserver_instance_dir under the /SUNWam/agents/debug directory (or the directory that you specify) and stores the log file in that directory.
Valid Values
The absolute path to the log file as shown in the following example.
Example
com.sun.am.logFile =/var/opt/SUNWam/agents/debug/webserver_instance_dir/amAgent
com.sun.am.serverLogFile
Description
This property stores the name of the Identity Server log file to be use for logging messages to Identity Server.
Valid Values
Only the file name is needed. The directory of the file is determined by settings configured on the Identity Server.
Example
com.sun.am.serverLogFile= amAuthLog
com.sun.am.logLevels
Description
This property allows to set the logging level for the specified logging categories.
Valid Values
The value of the property should be in this format:
<ModuleName>[:<Level>][,<ModuleName>[:<Level>]]*
The currently used module names are: AuthService, NamingService, PolicyService, SessionService, PolicyEngine, ServiceEngine, Notification, PolicyAgent, RemoteLog and all.
The “all” module can be used to set the logging level for all the logging modules. This will also establish the default level for all subsequently created modules.
The meaning of each level is described below:
0 Disable logging from specified module*
1 Log error messages
2 Log warning and error messages
3 Log info, warning, and error messages
4 Log debug, info, warning, and error messages
5 Like level 4, but with even more debugging messages
128 Log URL access to log file on IS server.
256 Log URL access to log file on local machine.
If level is omitted, then the logging module will be created with the default logging level, which is the logging level associated with the “all” module.
For levels 128 and 256, you must also specify a logAccessType.
Even if the level is set to zero, some messages may be produced for a module if they are logged with the special level value of “always”.
Example
com.sun.am.logLevels = all:5
com.sun.am.policy.am.username
Description
This property stores the user name to use for the Application authentication module.
Valid Values
UrlAccessAgent. This is a hardcoded value and must not be changed.
Examples
com.sun.am.policy.am.username = UrlAccessAgent
com.sun.am.policy.am.password
Description
This property stores the encrypted password to use for the Application authentication module.
Valid Values
The shared secret between the agent and the Identity Server it protects. By default this is the Identity Server internal LDAP authentication user (amldapuser) password. If you want to change this password, you must use the Shared Secret Encryption utility to do so and copy the encrypted password here. For information on the Shared Secret Encryption utility, see the section "Shared Secret Encryption Utility."
Examples
com.sun.am.policy.am.password = SHARED_SECRET
com.sun.am.sslCertDir
Description
This property stores the name of the directory containing the certificate databases for SSL.
Valid Values
The absolute path to the directory.
Example
com.sun.am.sslCertDir = /opt/SUNWam/servers/alias
com.sun.am.certDbPrefix
Description
Set this property if the certificate databases in the directory specified by the previous property have a prefix.
Valid Values
Any text string that you want to use as the prefix. This text will be prefixed to the name of the certificate databases.
Example
com.sun.am.certDbPrefix = prefix
com.sun.am.trustServerCerts
Description
This property determines if the agent should trust all server certificates when Identity Server is running SSL. For more information, see the section "The Agent’s Default Trust Behavior."
Valid Values
true or false
Example
com.sun.am.trustServerCerts = true
com.sun.am.notificationEnabled
Description
This policy determines if the policy SDK should use the Identity Server notification mechanism to maintain the consistency of its internal cache. If the value is false, then a polling mechanism is used to maintain cache consistency.
Valid Values
true or false.
Example
com.sun.am.notificationEnabled = true
com.sun.am.notificationURL
Description
This property stores the URL to which notification messages should be sent if notification is enabled. See the previous property.
Valid Values
true or false
Example
com.sun.am.notificationURL = http://nila.eng.example.com:58080/amagent/UpdateAgentCacheServlet?shortcircuit=false
com.sun.am.policy.am.urlComparison.caseIgnore
Description
This property determines whether case sensitivity of the URL string is obeyed during policy evaluation.
Valid Values
true or false
Example
com.sun.am.policy.am.urlComparison.caseIgnore = true
com.sun.am.policy.am.cacheEntryLifeTime
Description
This property determines the amount of time (in minutes) an entry remains valid after it has been added to the cache. The default value for this property is 3 minutes.
Valid Values
The amount of time in minutes
Example
com.sun.am.policy.am.cacheEntryLifeTime=3
com.sun.am.policy.am.userIdParam
Description
This property allows the user to configure the User Id parameter passed by the session information from the Identity Server. The value of User ID will be used by the agent to set the value of REMOTE_USER server variable. By default this parameter is set to User ID.
Valid Values
User ID
Example
com.sun.am.policy.am.userIdParam=UserId
com.sun.am.policy.am.fetchHeaders
Description
This property enables/disables the additional policy response attributes to be introduced into the HTTP headers. The value can be true or false.
Valid Values
true or false.
Example
com.sun.am.policy.am.fetchHeaders=false
com.sun.am.policy.am.headerAttributes
Description
This property determines the policy attributes to be added to the HTTP header.
Valid Values
The specification is of the format ldap_attribute_name|http_header_name[,...]. where ldap_attribute_name is the attribute in data store to be fetched and http_header_name is the name of the header to which the value needs to be assigned.
Example
com.sun.am.policy.am.headerAttributes=cn|common-name,ou|organizational-unit,o|organization,mail|email,employeenumber|employee-number,c|country
com.sun.am.policy.am.loadBalancer_enable
Description
This property indicates whether a load balancer is used for Identity Server services.
Valid Values
true or false.
Example
com.sun.am.policy.am.loadBalancer_enable = false
com.sun.am.policy.agents.version
Description
This property is meant for product versioning, please do not modify it.
Example
com.sun.am.policy.agents.version=2.1
com.sun.am.policy.agents.logAccessType
Description
This property allows to set the URL access logging level.
Valid Values
The allowed values are:
Example
com.sun.am.policy.agents.logAccessType = LOG_DENY
com.sun.am.policy.agents.agenturiprefix
Description
The agent uses this property to support some essential functions such as notification and post-data preservation.
Valid Values
Its value should be http://host.domain:port/agent_deployment_uri where host, domain and port are FQDN and port number of the web server where the agent is installed and agent_deployment_uri is the URI where the web server will look for agent's related HTML pages.
Example
com.sun.am.policy.agents.agenturiprefix = http://nila.eng.example.com:58080/amagent
com.sun.am.policy.agents.locale
Description
This property specifies the Locale setting.
Valid Values
It is recommended that you do not change this value.
Example
com.sun.am.policy.agents.locale = en_US
com.sun.am.policy.agents.instanceName
Description
This property stores the unique identifier for this agent instance.
Valid Values
This property is not currently used by the agent.
Example
com.sun.am.policy.agents.instanceName = unused
com.sun.am.policy.agents.do_sso_only
Description
This property indicates whether the agent will just enforce user authentication (SSO) without enforcing policies (authorization).
Valid Values
true or false
Example
com.sun.am.policy.agents.do_sso_only = false
com.sun.am.policy.agents.accessDeniedURL
Description
This property stores the URL of the custom page that you want to display when a user tries to access a protected resource. If no value is specified, then the agent will return an HTTP status of 403 (Forbidden).
Valid Values
The URL of the page that you want to display.
Example
com.sun.am.policy.agents.accessDeniedURL =http://nila.eng.example.com:58080/urlaccessdenied.html
com.sun.am.policy.agents.urlRedirectParam=goto
Description
This property allows the user to configure the URL Redirect parameter for different auth modules.
Valid Values
By default this parameter is set to goto.
Example
com.sun.am.policy.agents.urlRedirectParam=goto
com.sun.am.policy.agents.fqdnDefault
Description
Default FQDN is the fully qualified hostname that the users should use in order to access resources on this web server instance. This is a required configuration value without which the web server may not startup correctly.
The primary purpose of specifying this property is to ensure that if the users try to access protected resources on this web server instance without specifying the FQDN in the browser URL, the agent can take corrective action and redirect the user to the URL that contains the correct FQDN.
This property is set during the agent installation and need not be modified unless absolutely necessary to accommodate deployment requirements.
WARNING: Invalid value for this property can result in the web server becoming unusable or the resources becoming inaccessible.
Valid Values
The fully qualified domain name of the machine where the agent is installed.
Example
com.sun.am.policy.agents.fqdnMap = nila.Eng.example.COM
com.sun.am.policy.agents.fqdnMap
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
The format for this property is:
com.sun.am.policy.agents.fqdnMap = [invalid_hostname|valid_hostname][,...]
Where invalid_hostname is a possible invalid hostname the user may use such as partial hostname or an IP address, and the valid_hostname is the corresponding valid hostname which is fully qualified. For example the following is a possible value specified for xyz.domain1.com:
com.sun.am.policy.agents.fqdnMap = xyz|xyz.domain1.com, xyz.domain1|xyz.domain1.com
This value maps xyz and xyz.domain1 to the FQDN xyz.domain1.com.
At runtime, the agent refers to this map in order to take corrective actions for users who may have typed in a URL with malformed hostname. If none of the entries in this map matches the hostname specified in the user request, the agent uses the com.sun.am.policy.agents.fqdnDefault property.
WARNING: Invalid value for this property can result in the web server becoming unusable or the resources becoming inaccessible.
This property can also be used in a way that the agents use the name specified in this map instead of the web server’s actual name.
Say, you want your server to be addressed as xyz.hostname.com whereas the actual name of the server is abc.hostname.com. The browser only knows xyz.hostname.com and you have specified policies using xyz.hostname.com at the Identity Server console. In this file, set the mapping as com.sun.am.policy.agents.fqdnmap = valid|xyz.hostname.com
com.sun.am.policy.agents.cookie_reset_
enabledDescription
This property must be set to true, if this agent needs to reset cookies in the response before redirecting to Identity Server for Authentication.
Valid Value
true or false. By default this is set to false.
Example
com.sun.am.policy.agents.cookie_reset_enabled=true
com.sun.am.policy.agents.cookie_reset_list
Description
This property gives the comma separated list of cookies, that need to be included in the Redirect Response to Sun ONE Identity Server. This property is used only if the Cookie Reset feature is enabled.
Valid Values
The cookie details need to be specified in the following format
name[=value][;Domain=value]
If Domain is not specified, then the default agent domain is used to set the cookie.
Example
com.sun.am.policy.agents.cookie_reset_list=LtpaToken, token=value;Domain=subdomain.domain.com
com.sun.am.policy.agents.cookieDomainList
Description
This property gives the space separated list of domains in which cookies have to be set in a CDSSO scenario. This property is used only if CDSSO is enabled.
Valid Values
If this property is left blank, then the fully qualified cookie domain for the agent server will be used for setting the cookie domain.
Example
com.sun.am.policy.agents.cookieDomainList=.example.com .madisonparc.com
com.sun.am.policy.agents.unauthenticatedUser
Description
This property stores the User Id to be returned if a user is accessing global allow page and is not authenticated.
Valid Values
Any user id that you want to display for the unauthenticated user.
Example
com.sun.am.policy.agents.unauthenticatedUser=anonymous
com.sun.am.policy.agents.anonRemoteUserEnabled
Description
Use this property to enable/disable REMOTE_USER processing for anonymous users.
Valid Values
true or false
Example
com.sun.am.policy.agents.anonRemoteUserEnabled=false
com.sun.am.policy.agents.notenforcedList
Description
This property stores the list of URLs for which no authentication is required.
Each service has its own not-enforced list. The service name is suffixed after com.sun.am.policy.agents.notenforcedList. to specify a list for a particular service. SPACE is the separator between the URLs.
Valid Values
The list of URLs for which authentication is required. Wildcards can be used to define a pattern of URLs. The URLs specified may not contain any query parameters.
Example
com.sun.am.policy.agents.notenforcedList = SERVER_PROTO://SERVER_HOST:SERVER_PORTSERVER_DEPLOY_URI/UI/* SERVER_PROTO://SERVER_HOST:SERVER_PORTCONSOLE_DEPLOY_URI/*
com.sun.am.policy.agents.reverse_the_meaning_of_notenforcedList
Description
This property uses a boolean attribute to indicate whether the above list is a not-enforced list or an enforced list; When the value is true, the list means enforced list, or in other words, the whole web site is open/accessible without authentication except for those URLs in the list.
Valid Values
true or false
Example
com.sun.am.policy.agents.reverse_the_meaning_of_notenforcedList = false
com.sun.am.policy.agents.notenforced_client_IP_address_list
Description
This property stores a list of client IP addresses. No authentication and authorization are required for the requests coming from these client IP addresses.
Valid Values
Valid IP addresses in the form of 192.168.12.2 1.1.1.1
Example
com.sun.am.policy.agents.notenforced_client_IP_address_list =194.164.10.2
com.sun.am.policy.agents.is_postdatapreserve_enabled
Description
This property enables/disables POST data preservation. By default its value is set to false.
Valid Values
true or false.
Example
com.sun.am.policy.agents.is_postdatapreserve_enabled = false
com.sun.am.policy.agents.
postcacheentrylifetimeDescription
This property determines the number of minutes any POST data will remain valid in the web server cache. After the specified interval, the entry will be cleared.
Valid Values
The time can be set by the Administrator. The default is 10 minutes.
Example
com.sun.am.policy.agents.postcacheentrylifetime = 10
com.sun.am.policy.agents.cdsso-enabled
Description
This property indicates if the Cross-Domain Single Sign On URL is enabled.
Valid Values
true or false
Example
com.sun.am.policy.agents.cdsso-enabled=true
com.sun.am.policy.agents.cdcservletURL
Description
This property indicates the URL the user will be redirected to after a successful login in a CDSSO scenario.
Valid Values
The URL to which the user will be redirected.
Example
com.sun.am.policy.agents.cdcservletURL = http://sina.eng.example.com:58080/amserver/cdcservlet
com.sun.am.policy.agents.client_ip_validation_
enableDescription
This property enables/disables client IP address validation. This validation will check if the subsequent browser requests come from the same IP address that the SSO token is initially issued against.
Valid Values
true or false
Example
com.sun.am.policy.agents.client_ip_validation_enable = false
com.sun.am.policy.agents.logout.url
Description
This property indicates the application’s Logout URL This URL is not enforced by policy. When the agent sees this URL, it checks whether a valid session ID for the user still exists. If one does exist, the agent invalidates it, thus logging the user off Sun ONE Identity Server.
Valid Values
The logout URLs used by the protected applications.
Example
com.sun.am.policy.agents.logout.url=http://dsameqa1:7778/pls/portal30_sso/PORTAL30_SSO.wwsec_app_priv.logout?p_done_url=http%3A%2F%2Fdsameqa1%3A7778%2Fpls%2Fportal30_sso%2FPORTAL30_SSO.home
http://dsameqa1:7778/pls/portal30/PORTAL30.wwsec_app_priv.logout?p_done_url=http%3A%2F%2Fdsameqa1%3A7778%2Fpls%2Fportal30%2FPORTAL30.home
com.sun.am.policy.agents.logout.cookie_reset_
listDescription
This property lists the cookies that need to be reset or removed upon log out.
Valid Values
Cookies in the same format as specified for the property com.sun.am.policy.agents.cookie_reset_list.
Example
com.sun.am.policy.agents.logout.cookie_reset_list = iPlanetDirectoryPro;Domain=, iPlanetDirectoryPro;Domain=iplanet.com
com.sun.am.policy.am.ldapattribute.cookiePrefix
Description
If a value is specified for this field, any cookie set will have its prefix set to this value. For example, if the property is set to MY_COOKIE_PREFIX_, for the LDAP attribute email, the cookie name will be MY_COOKIE_PREFIX_email.This property is used when the user wants to set the LDAP attribute through a COOKIE.
Valid Values
Any string. The default value is HTTP_.
Example
com.sun.am.policy.am.ldapattribute.cookiePrefix = HTTP_
com.sun.am.policy.am.ldapattribute.cookieMax
AgeDescription
This property indicates the time in seconds after which the cookie will expire. This property is used when the user wants to set the LDAP attributes through COOKIE.
Valid Values
Amount of time in seconds.
Example
com.sun.am.policy.am.ldapattribute.cookieMaxAge = 300
com.sun.am.policy.agents.getClientHostname
Description
This property indicates whether to get the client’s hostname through DNS reverse lookup for use in policy evaluation.
Valid Values
true or false. By default, the value is true if the property does not exist or if it is any value other than false.
Example
com.sun.am.policy.agents.getClientHostname = true
com.sun.am.policy.am.ldapattribute.mode
Description
This property is used to specify if additional policy response attributes should be introduced into the request.
Valid Values
This property takes the following values:
- NONE: indicates that no additional policy attributes will be introduced.
- HEADER: means that additional policy attributes will be introduced into HTTP header.
- COOKIE: indicates that additional policy attributes will be introduced through cookies.
If a value other than these is supplied, it will default to NONE.
Example
com.sun.am.policy.am.ldapattribute.mode=COOKIE
com.sun.am.policy.am.fetchFromRootResource
Description
By default, when a policy decision for a resource is needed, the agent gets and caches the policy decision of the resource and all the resources from the root of the resource down, from the Identity Server.
For example, if the resource is http://host/a/b/c, the root of the resource is http://host/. This is because more resources on the same path are likely to be accessed subsequently. However, this may take a long time initially if there are many policies defined under the root resource. To have the agent get and cache the policy decision for the resource only, set this property to false.
Note
This property is not currently used with Sun ONE Identity Server 6.1. It will be used with Sun ONE Identity Server 6.2 or later.
Valid Values
true or false
Example
com.sun.am.policy.am.fetchFromRootResource = true