Appendix A AMAgent Properties

Web Policy Agents Guide

Appendix A
AMAgent Properties

The 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.

Note

All property names in this file are case-sensitive.

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.

Note

In most cases, in a destination application where a “http_header_name” shows up as a request header, it will be prefixed by HTTP_, and all lower case letters will become upper case, and any - will become _;

For example, “common-name” would become “HTTP_COMMON_NAME”

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:

LOG_NONE - Do not log user access to URL

LOG_DENY - Log URL access that was denied.

LOG_ALLOW - Log URL access that was allowed.

LOG_BOTH - Log URL access that was allowed or denied.

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.

Note

The property com.sun.am.policy.agents.fqdnMap provides another way by which the agent can resolve malformed access URLs used by the users and take corrective action. This property can also be used to override the behavior of the agent in cases where necessary. For example, if it is required that no corrective action such as a redirect be used for users who access the web server resources using raw IP address, you can implement this by specifying a map entry such as:

com.sun.am.policy.agents.fqdnMap = <IP>|<IP>

The agent gives precedence to the entries defined in the com.sun.am.policy.agents.fqdnMap property over the value defined in this property.

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.

Note

This property can be used for creating a mapping for more than one hostname. This may be the case when the web server protected by this agent is accessible by more than one hostname. However, the use of this feature must be done with caution as it can lead to the web server resources becoming inaccessible.

The agent gives precedence to the entries defined in this property over the value defined in com.sun.am.policy.agents.fqdnDefault property.

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_
enabled

Description

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.
postcacheentrylifetime

Description

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_
enable

Description

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_
list

Description

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
Age

Description

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

Previous      Contents      Index      Next

Copyright 2004 Sun Microsystems, Inc. All rights reserved.


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.


Note	In most cases, in a destination application where a “http_header_name” shows up as a request header, it will be prefixed by HTTP_, and all lower case letters will become upper case, and any - will become _; For example, “common-name” would become “HTTP_COMMON_NAME”


Note	The property com.sun.am.policy.agents.fqdnMap provides another way by which the agent can resolve malformed access URLs used by the users and take corrective action. This property can also be used to override the behavior of the agent in cases where necessary. For example, if it is required that no corrective action such as a redirect be used for users who access the web server resources using raw IP address, you can implement this by specifying a map entry such as: com.sun.am.policy.agents.fqdnMap = <IP>\|<IP> The agent gives precedence to the entries defined in the com.sun.am.policy.agents.fqdnMap property over the value defined in this property.


Note	This property can be used for creating a mapping for more than one hostname. This may be the case when the web server protected by this agent is accessible by more than one hostname. However, the use of this feature must be done with caution as it can lead to the web server resources becoming inaccessible. The agent gives precedence to the entries defined in this property over the value defined in com.sun.am.policy.agents.fqdnDefault property.


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.