Sun OpenSSO Enterprise 8.0 Developer's Guide

Using AMConfig.properties With the Client SDK

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.

If the Client SDK was installed by deploying the samples:

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

See Installing the Client SDK by Deploying the Sample WAR.

If the Client SDK was installed by compiling the samples:

opensso-client-zip-root/sdk/resources

See Installing the Client SDK By Compiling the Samples.

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.

Properties in AMConfig.properties

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.


Note –

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.


Debug Properties

Client SDK Related Properties

Logging Property

The value of com.iplanet.am.logstatus should be ACTIVE. INACTIVE disables logging.

Additional log properties are in Policy Logging and Caching Properties.

Java™ Platform, Enterprise Edition (Java EE) Agent Property

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.


Note –

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.


OpenSSO Enterprise Configuration Data User Credential Properties

See Setting Up a Client SDK Identity for additional information.

Cache Enable Properties

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.

Additional cache configuration properties include:

Additional cache properties are in Policy Logging and Caching Properties.

Cache Update 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.


Caution – Caution –

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.

Notification Properties

See Sending Notifications to the Client SDK Cache for more information on the Notification Service.

Polling Properties

Notification must be disabled.

TTL Properties

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.

These are the Identity Repository TTL properties.

For backwards compatibility, these are the properties to configure the TTL feature for the com.iplanet.am.sdk classes.

Naming Property

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

Encryption Properties

OpenSSO Enterprise Server and Console Location Properties

These properties point to the OpenSSO Enterprise server and console. They are set during Client SDK configuration.

Cookie Property

com.iplanet.am.cookie.name contains the name of the OpenSSO Enterprise cookie; by default, iPlanetDirectoryPro.

Client Side Session Polling Properties

JSS Certificate Database Properties

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.

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.

Policy Logging and Caching Properties

Federation Properties

These federation properties are not included in AMConfig.properties by default but can be added as needed.

com.sun.identity.liberty.ws.soap.supportedActor

Defines the SOAP supported actors. Each actor must be separated by a pipe (|).


Note –

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.


com.sun.identity.liberty.interaction.wspRedirectHandler

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.

com.sun.identity.liberty.interaction.wscSpecifiedInteractionChoice

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.

com.sun.identity.liberty.interaction.wscWillInlcudeUserInteractionHeader

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.

com.sun.identity.liberty.interaction.wscWillRedirect

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.

com.sun.identity.liberty.interaction.wscSpecifiedMaxInteractionTime

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.

com.sun.identity.liberty.interaction.wscWillEnforceHttpsCheck

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.

com.sun.identity.liberty.interaction.wspWillRedirect

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.

com.sun.identity.liberty.interaction.wspWillRedirectForData

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.

com.sun.identity.liberty.interaction.wspRedirectTime

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.

com.sun.identity.liberty.interaction.wspWillEnforceHttpsCheck

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.

com.sun.identity.liberty.interaction.wspWillEnforceReturnToHostEqualsRequestHost

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.

com.sun.identity.liberty.interaction.htmlStyleSheetLocation

Indicates the path to the style sheet used to render the interaction page in HTML.

com.sun.identity.liberty.interaction.wmlStyleSheetLocation

Indicates the path to the style sheet used to render the interaction page in WML.

com.sun.identity.liberty.ws.interaction.enable

Default value is false.

com.sun.identity.wss.provider.config.plugin= com.sun.identity.wss.provider.plugins.AgentProvider

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

com.sun.identity.loginurl

Used by the web services clients in Client SDK mode. For example:

com.sun.identity.loginurl=https://host:port/opensso-uri/UI/Login

com.sun.identity.liberty.authnsvc.url

Indicates the Liberty authentication service URL.

com.sun.identity.liberty.wsf.version

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.

com.sun.identity.liberty.ws.soap.certalias

Value is set during installation. Client certificate alias that will be used in SSL connection for Liberty SOAP Binding.

com.sun.identity.liberty.ws.soap.messageIDCacheCleanupInterval

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.

com.sun.identity.liberty.ws.soap.staleTimeLimit

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.

com.sun.identity.liberty.ws.wsc.certalias

Value is set during installation. Specifies default certificate alias for issuing web service security token for this web service client.

com.sun.identity.liberty.ws.trustedca.certaliases

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.

Setting Properties in AMConfig.properties

There are three ways to set properties in AMConfig.properties. The following sections contain more information.

Setting Properties Using a Text Editor

You can set properties in AMConfig.properties by editing the file with a text editor. Each property is defined as:

property-name=property-value

Setting Properties Using the Java API

You can set properties programmatically using the com.iplanet.am.util.SystemProperties class. For example:


Example 14–1 Setting Client SDK Properties Programmatically


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

Setting Properties at Run Time

To set a value to a particular property at run time, declare the JVM option using the following format:

-Dproperty-name=property-value