Although AMConfig.properties has been deprecated as the configuration data store for OpenSSO Enterprise, this file is still used to store configuration data for the Client SDK. An AMConfig.properties file with the information needed to point the Client SDK to the remote OpenSSO Enterprise server must be accessible from the machine on which it is hosted. The location of AMConfig.properties depends on how you initially installed the Client SDK.
user.home/OpenSSO-Deploy-base-client-jdk15_AMConfig.properties
where user.home (JDK system property) is the home directory of the user running the web container, and OpenSSO-Deploy-base is determined by the web container. For example, if you deployed opensso-client-jdk15.war on Sun Java System Application Server 9.1 while running as super user (root), the AMConfig.properties file is:
OpenSSOClient/_opt_SUNWappserver_domains_domain1_applications_j2ee-modules_opensso-client-jdk15_AMConfig.properties
opensso-client-zip-root/sdk/resources
The properties in AMConfig.properties can be modified. Information on the properties in the file and how to modify them is in the following sections.
The Client SDK uses the following properties in AMConfig.properties. You can add additional properties as required by a client application; for example, an application can register for the notification of changes to session attributes, user attributes, and policy decisions. The following sections contain information on the properties.
With the addition of new features, properties often change or might be added. For the most current properties, see AMClient.properties on the OpenSSO web site.
com.iplanet.services.debug.level specifies the debug level as one of the following:
off specifies that no debug information is recorded.
error specifies that only debug messages posted as errors should be written to the debug files. This level is recommended for production environments.
warning is not a recommended value at this time.
message alerts to possible issues using code tracing. Most OpenSSO Enterprise modules use this level to send debug messages.
Using warning or message in production environments is not recommended because they can cause severe performance degradation from excessive of debug messages.
com.iplanet.services.debug.directory is the output directory for the debug information. The directory should be writable by the server process. For example:
com.iplanet.services.debug.directory=/opensso/debug
com.iplanet.am.sdk.package is the name of the Client SDK package; by default, com.iplanet.am.sdk.remote.
com.iplanet.am.serverMode defines whether the configured WAR to which the property applies is running as an OpenSSO Enterprise server or a client to OpenSSO Enterprise. If opensso.war is deployed and configured, the value of this property (in the embedded data store) is set to true as OpenSSO Enterprise is the server. When the clientsdk.war or distauth.war is deployed and configured, the value of this property is set to false as they are clients to OpenSSO Enterprise. In the Client SDK AMConfig.properties the value of this property will always be false.
The value of com.iplanet.am.logstatus should be ACTIVE. INACTIVE disables logging.
Additional log properties are in Policy Logging and Caching Properties.
The value of com.iplanet.am.client.appssotoken.refreshtime is the amount of time (in minutes) that the appSSOToken will be refreshed. It defaults to 3.
A J2EE policy agent authenticates itself to OpenSSO Enterprise as an application using a special user. The OpenSSO sends back an appSSOToken after a successful authentication.
com.sun.identity.agents.app.username defines a user with permission to read the OpenSSO Enterprise configuration data; by default, UrlAccessAgent.
com.iplanet.am.service.password specifies the password of the user with permission to read OpenSSO Enterprise configuration data.
com.iplanet.am.service.secret specifies the encrypted password for the user defined in the com.sun.identity.agents.app.username property; for example, AQIC24u86rq9RRZGr/HN25OcIuO6w+ne+0lG.
See Setting Up a Client SDK Identity for additional information.
Two main components that rely heavily on caching for performance and improved user experience are the Service Management and Identity Repository classes. A combination of true and false values defined for the following three properties will enable and disable the respective cache.
com.iplanet.am.sdk.caching.enabled enables both caches when set to true (default). A value of false disables both caches.
com.sun.identity.idm.cache.enabled controls the Identity Repository cache. When com.iplanet.am.sdk.caching.enabled is set to false, enable this cache (separately from the Service Management cache) with a value of true. A value of false keeps it disabled.
com.sun.identity.sm.cache.enabled controls the Service Management cache. When com.iplanet.am.sdk.caching.enabled is set to false, enable this cache (separately from the Identity Repository cache) with a value of true. A value of false keeps it disabled.
Additional cache configuration properties include:
com.iplanet.am.sdk.cache.maxSize limits the size of the Identity Repository cache to, by default, 10000 entries. There is no corresponding entry to limit the cache size for the Service Management cache.
com.sun.identity.sm.cacheTime is the update time (in minutes) for the Service Management cache when polling is enabled.
com.iplanet.am.sdk.remote.pollingTime is the update time (in minutes) for Identity Repository cache when polling is enabled.
Additional cache properties are in Policy Logging and Caching Properties.
When caching is enabled, OpenSSO Enterprise has three options that can be used to invalidate dirty cache entries. The first is to set up a URL with which the OpenSSO Enterprise server can send session change notifications to clients on remote web containers. This works for web and standalone applications that can listen for HTTP(s) traffic. The second method (which works ONLY if notification is disabled) is polling. In this case, the client periodically checks the OpenSSO Enterprise server for session changes. The third method is referred to as Time-to-Live (TTL) and enforces a limit on the period of time dirty data remains in the cache before it is discarded. See the following sections for more information.
The notification method could cause a constant flood of notification changes that might overwhelm the client so be sure to choose the optimal method for your deployment.
Additional cache properties are in Policy Logging and Caching Properties.
com.sun.identity.client.notification.url defines the URI of the Notification Service running on the host machine on which the Client SDK is installed; by default, http://SDK-host.domain:port/opensso/notificationservice. This value is used for both the Service Management and Identity Repository caches. If no URL is specified, notification is disabled.
com.sun.identity.idm.remote.notification.enabled is used to enable or disable the notifications for the Identity Repository cache. If set to true notifications are enabled; false disabled.
com.sun.identity.sm.notification.enabled is used to enable or disable the notifications for the Service Management cache. If set to true notifications are enabled; false disabled.
See Sending Notifications to the Client SDK Cache for more information on the Notification Service.
Notification must be disabled.
com.iplanet.am.sdk.remote.pollingTime defines the amount of time (in minutes) between each poll (check) by the client for Identity Repository data changes. This property also controls the polling time for the com.iplanet.am.sdk for backwards compatibility.
com.sun.identity.sm.cacheTime defines the amount of time (in minutes) between each poll (check) by the client for Service Management data changes.
The following properties relate to the cache Time To Live (TTL). TTL is a limit on the period of time before data in the cache should be discarded. These TTL properties are not included in AMConfig.properties by default but can be added as needed. These are the Service Management TTL properties.
com.sun.identity.sm.cache.ttl.enable enables the TTL function for the Service Management cache with a default value of true.
com.sun.identity.sm.cache.ttl limits the time (in minutes) to the defined value; by default, 30.
These are the Identity Repository TTL properties.
com.sun.identity.idm.cache.entry.expire.enabled takes a value of true or false which enables or disables, respectively, the Identity Repository TTL feature.
com.sun.identity.idm.cache.entry.user.expire.time specifies the time (in minutes) that user Identity Repository cache entries remain valid after their last modification. In other words, after the specified time has elapsed (following a modification or directory read), the data for the cached entry will expire and new requests for this data must be read from the directory. The default value is one minute.
com.sun.identity.idm.cache.entry.default.expire.time specifies the time (in minutes) that non-user Identity Repository cache entries remain valid after their last modification. In other words, after the specified time has elapsed (following a modification or directory read), the data for the cached entry will expire and new requests for this data must be read from the directory. The default value is one minute.
For backwards compatibility, these are the properties to configure the TTL feature for the com.iplanet.am.sdk classes.
com.iplanet.am.sdk.cache.entry.expire.enabled takes a value of true or false which enables or disables, respectively, the TTL feature for the com.iplanet.am.sdk classes.
com.iplanet.am.sdk.cache.entry.user.expire.time specifies the time (in minutes) that user cache entries remain valid after their last modification. The default value is one minute.
com.iplanet.am.sdk.cache.entry.default.expire.time specifies the time (in minutes) that non-user cache entries remain valid after their last modification. The default value is one minute.
com.iplanet.am.naming.url is a required property. The value of this property is the URI of the Naming Service from which the Client SDK would retrieve the URLs of OpenSSO Enterprise internal services; by default, http://opensso-host.domain_name:port/opensso/namingservice
am.encryption.pwd contains an encryption key used to decrypt passwords stored with the Service Management data.
com.sun.identity.client.encryptionKey contains an encryption key used to encrypt and decrypt data used locally within the client application.
The value of com.iplanet.security.encryptor is either of the following encrypting class implementations:
com.iplanet.services.util.JCEEncryption (default)
com.iplanet.services.util.JSSEncryption
These properties point to the OpenSSO Enterprise server and console. They are set during Client SDK configuration.
com.iplanet.am.server.protocol defines the protocol of the machine on which OpenSSO Enterprise is deployed; for example, http.
com.iplanet.am.server.host defines the name and domain of machine on which OpenSSO Enterprise is deployed; for example, OSSO_Host_Machine.domain_name.
com.iplanet.am.server.port defines the port of the machine on which OpenSSO Enterprise is deployed; for example, 8080.
com.iplanet.am.services.deploymentDescriptor defines the URI of the deployed instance of OpenSSO Enterprise; for example, opensso.
com.iplanet.am.console.protocol defines the protocol of the machine on which the OpenSSO Enterprise console is deployed; for example, http.
com.iplanet.am.console.host defines the name and domain of machine on which the OpenSSO Enterprise console is deployed; for example, OSSO_Host_Machine.domain_name.
com.iplanet.am.console.port defines the port of the machine on which the OpenSSO Enterprise console is deployed; for example, 8080.
com.iplanet.am.console.deploymentDescriptor defines the URI of the deployed OpenSSO Enterprise console; for example, opensso.
com.iplanet.am.cookie.name contains the name of the OpenSSO Enterprise cookie; by default, iPlanetDirectoryPro.
com.iplanet.am.session.client.polling.enable is used to enable (If set to true) or disable (if set to false) client-side session polling.
com.iplanet.am.session.client.polling.period specifies the number of seconds in the polling period; by default, 180.
Network Security Services for Java (JSS) is a Java interface to Network Security Services (NSS), a set of libraries designed to support cross-platform development of security-enabled client and server applications. The following properties are used to initialize the JSS SocketFactory when the web container in which the Client SDK is deployed is configured for SSL.
com.iplanet.am.admin.cli.certdb.dir identifies the directory path to the certificate database.
com.iplanet.am.admin.cli.certdb.passfile identifies the directory path to the password file for the certificate database.
com.iplanet.am.admin.cli.certdb.prefix identifies the prefix for the certificate database.
These properties identify the value for SSL ApprovalCallback. If the checkSubjectAltName or resolveIPAddress feature is enabled, you must create cert7.db and key3.db with a prefix equal to the value defined in com.iplanet.am.admin.cli.certdb.prefix and located in the directory defined in com.iplanet.am.admin.cli.certdb.dir.
com.iplanet.am.jssproxy.trustAllServerCerts, when enabled, allows OpenSSO Enterprise to ignore all certificate-related issues such as a name conflict and continue the SSL handshaking. The default value is false; to enable, true.
To prevent a possible security risk, enable this property only for testing purposes, or when the enterprise network is tightly controlled. Avoid enabling this property if a security risk might occur (for example, if a server connects to a server in a different network).
com.iplanet.am.jssproxy.checkSubjectAltName, when enabled, includes the Subject Alternative Name (SubjectAltName) extension with a certificate, and OpenSSO Enterprise checks all name entries in the extension. If one of the names included in the SubjectAltName extension is the same as the server FQDN, OpenSSO Enterprise continues the SSL handshaking. The default value is false. To enable this property, set a comma separated list of trusted FQDNs; for example, com.iplanet.am.jssproxy.checkSubjectAltName=amserv1.example.com,amserv2.example.com.
com.iplanet.am.jssproxy.resolveIPAddress takes a value of false (by default) or true.
com.iplanet.am.jssproxy.SSLTrustHostList tells OpenSSO Enterprise to check the Platform Server list against the server host that is being accessed. If the server FQDNs of the servers in the Platform Server list match, OpenSSO Enterprise continues the SSL handshaking. Use the following syntax to set the property: com.iplanet.am.jssproxy.SSLTrustHostList=fqdn_osso_server1,fqdn_osso_server2,fqdn_osso_server3
com.sun.identity.agents.server.log.file.name specifies the name of the Client SDK policy log file; by default, amRemotePolicyLog.
com.sun.identity.agents.logging.level specifies the granularity of the information logged to the Client SDK policy log file. Values can be:
NONE is the default value. Nothing is logged.
ALLOW logs allowed access decisions.
DENY logs denied access decisions.
BOTH logs allowed and denied access decisions.
DECISION
com.sun.identity.agents.notification.enabled enables or disables notifications from OpenSSO Enterprise to update the Client SDK cache. Takes a value of true or false respectively.
com.sun.identity.agents.server.log.file.name specifies the URL to which policy, session, and agent notifications from OpenSSO Enterprise are sent.
com.sun.identity.agents.polling.interval specifies the number of minutes after which an entry is dropped from the Client SDK cache.
com.sun.identity.policy.client.cacheMode specifies the cache mode for the client policy evaluator. Values are:
subtree specifies that the policy evaluator obtains policy decisions from the server for all the resources from the root of resource actually requested.
self specifies that the policy evaluator obtains policy decisions from the server only for the resource actually requested.
com.sun.identity.policy.client.usePre22BooleanValues specifies whether to use boolean values; by default, true.
These federation properties are not included in AMConfig.properties by default but can be added as needed.
Defines the SOAP supported actors. Each actor must be separated by a pipe (|).
A SOAP message can travel from a sender to a receiver by passing different endpoints along the way but not all parts of the SOAP message may be intended for the destination; some may be intended for one or more endpoints along the message path. The SOAP actor attribute is used to address the Header element to a specific endpoint URL.
Defines the URL for WSPRedirectHandlerServlet to handle Liberty the WSF web service provider-resource owner. Interactions are based on user agent redirects. The servlet should be running in the same JVM where the Liberty service provider is running.
Indicates whether the web service client should participate in an interaction. Valid values are interactIfNeeded, doNotInteract, and doNotInteractForData. Default value is interactIfNeeded which is used if an invalid value is specified.
Indicates whether the web service client should include userInteractionHeader. Valid values are yes and no (case ignored). Default value is yes. Default value is used if no value is specified.
Indicates whether the web service client will redirect user for an interaction. Valid values are yes and no. Default value is yes. Default value is used if no value is specified.
Indicates the web service client preference for acceptable duration (in seconds) for an interaction. If the value is not specified or if a non-integer value is specified, the default value is 60.
Indicates whether the web service client enforces that redirected to URL is HTTPS. Valid values are yes and no (case ignored). The Liberty specification requires the value to be yes. Default value is yes. Default value is used if no value is specified.
Indicates whether the web service provider redirects the user for an interaction. Valid values are yes and no (case ignored). Default value is yes. Default value is if no value is specified.
Indicates whether the web service provider redirects the user for an interaction for data. Valid values are yes and no. Default value is yes. If no value is specified, the value is yes.
Web service provider expected duration (in seconds) for an interaction. Default value if the value is not specified or is a non-integer value is 30.
Indicates whether the web service client enforces that returnToURL is HTTP. Valid values are yes and no (case ignored). Liberty specification requires the value to be yes. Default value is yes. If no value is specified, then the value used is yes.
Indicates whether the web services client enforces that returnToHost and requestHost are the same. Valid values are yes and no. Liberty specification requires the value to be yes.
Indicates the path to the style sheet used to render the interaction page in HTML.
Indicates the path to the style sheet used to render the interaction page in WML.
Default value is false.
Used by the web services provider to determine the plug-in that will be used to store the configuration.
For example: com.sun.identity.wss.provider.config.plugin= com.sun.identity.wss.provider.plugins.AgentProvider
Used by the web services clients in Client SDK mode. For example:
com.sun.identity.loginurl=https://host:port/opensso-uri/UI/Login
Indicates the Liberty authentication service URL.
Used to determine which version of the Liberty identity web services framework is to be used when the framework can not determine from the inbound message or from the resource offering. This property is used when OpenSSO Enterprise is acting as the web service client. The default version is 1.1. The possible values are 1.0 or 1.1.
Value is set during installation. Client certificate alias that will be used in SSL connection for Liberty SOAP Binding.
Default value is 60000. Specifies the number of milliseconds to elapse before cache cleanup events begin. Each message is stored in a cache with its ownmessageID to avoid duplicate messages. When a message's current time less the received time exceeds thestaleTimeLimit value, the message is removed from the cache.
Default value is 300000. Determines if a message is stale and thus no longer trustworthy. If the message timestamp is earlier than the current timestamp by the specified number of milliseconds, the message the considered to be stale.
Value is set during installation. Specifies default certificate alias for issuing web service security token for this web service client.
Value is set during installation. Specifies certificate aliases for trusted CA. SAML or SAML BEARER token of incoming request. Message must be signed by a trusted CA in this list. The syntax is:
cert alias 1[:issuer 1]|cert alias 2[:issuer 2]|.....
For example: myalias1:myissuer1|myalias2|myalias3:myissuer3. The value issuer is used when the token doesn't have a KeyInfo inside the signature. The issuer of the token must be in this list, and the corresponding certificate alias will be used to verify the signature. If KeyInfo exists, the keystore must contain a certificate alias that matches the KeyInfo and the certificate alias must be in this list.
There are three ways to set properties in AMConfig.properties. The following sections contain more information.
You can set properties in AMConfig.properties by editing the file with a text editor. Each property is defined as:
property-name=property-value
You can set properties programmatically using the com.iplanet.am.util.SystemProperties class. For example:
import com.iplanet.am.util.SystemProperties; import java.util.Properties; public static void main(String[] args) { // To initialize a set of properties Properties props = new Properties(); props.setProperty(”com.iplanet.am.naming.url’, ”http://sample.com/opensso/namingservice’); props.setProperty(”com.sun.identity.agents.app.username’, ”URLAccessAgent’); props.setProperty(”com.iplanet.am.service.password’, ”11111111’); SystemProperties.initializeProperties(props) ; // To initialize a single property SystemProperties.initializeProperties(“com.iplanet.am.naming.url’, ”http://sample.com/opensso/namingservice’); // Application specific code ... } |
To set a value to a particular property at run time, declare the JVM option using the following format:
-Dproperty-name=property-value