The SunTM OpenSSO Enterprise Client Software Development Kit (Client SDK) provides the Java libraries for integrating OpenSSO Enterprise functionality in remote standalone or web applications. This chapter contains the following sections:
The Client SDK includes the Java packages, classes, and configuration properties that you can use to enhance remote, standalone or web applications with the ability to access OpenSSO Enterprise. The Client SDK allows an application to use services such as authentication, SSO, authorization, auditing, logging, and the Security Assertion Markup Language (SAML). It also includes samples that you can run to help understand and develop code.
The Client SDK is not for use by applications that perform policy management or identity management (which includes the creation and deletion of entries).
From a deployment point of view, the Client SDK offers the following:
The Client SDK communicates directly with OpenSSO Enterprise server using XML (SOAP) over HTTP or HTTPS. In turn, OpenSSO Enterprise server communicates directly with the data stores.
The Client SDK does not require administrator credentials.
An application using the Client SDK can be deployed in a demilitarized zone (DMZ), with a firewall between the application and OpenSSO Enterprise server.
The Client SDK includes samples to show how it can be used.
The Client SDK includes these packages:
com.iplanet.am.sdk
com.iplanet.am.util
com.iplanet.sso
com.sun.identity.authentication
com.sun.identity.federation
com.sun.identity.idm
com.sun.identity.liberty.ws
com.sun.identity.log
com.sun.identity.policy
com.sun.identity.policy.client
com.sun.identity.saml
com.sun.identity.saml2
com.sun.identity.smt
com.sun.identity.xacml
com.sun.identity.wss
For a description of these packages, see the Sun OpenSSO Enterprise 8.0 Java API Reference. A complete listing of the classes that comprise the Client SDK can be found in the ClientSDKClasses file available on the OpenSSO web site. Samples and source code are also included to help developers understand how the Client SDK can best be implemented.
It is recommended that you do not use the com.iplanet.am.sdk, com.iplanet.am.util, com.sun.identity.policy, and com.sun.identity.sm packages directly.
The requirements to use the Client SDK include:
Access to OpenSSO Enterprise running on a remote server. You will need the following information about this remote installation:
Protocol (http or https) used by web container instance on which the OpenSSO Enterprise server is deployed.
Fully qualified domain name (FQDN) of the host where the OpenSSO Enterprise server is deployed.
Port on which the OpenSSO Enterprise server is running.
Deployment URI for the OpenSSO Enterprise server (default is opensso)
Default Agent user (UrlAccessAgent) password that you entered when you ran the OpenSSO Enterprise Configurator.
If you are writing a web application, you will need a web container supported by OpenSSO Enterprise. For the list of supported web containers, see the Chapter 2, Deploying the OpenSSO Enterprise Web Container, in Sun OpenSSO Enterprise 8.0 Installation and Configuration Guide.
You can use the Client SDK to:
Build a proprietary application framework in which the Client SDK is a part. The Client SDK features can allow independence from policy agents.
Access profile data, for purposes of authentication and authorization, beyond the default OpenSSO Enterprise capability.
Allow authenticated and non-authenticated users access to a login process with a registration option that, if accepted, would create a user account.
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
There are two ways to install the Client SDK. These options are documented in the following sections:
opensso-client.zip is in the samples directory of the downloaded and inflated opensso.zip. Unzipping opensso-client.zip reveals the war and sdk directories. The war directory contains two versions of the Client SDK WAR depending on the version of Java installed on your machine.
opensso-client-jdk15.war is for web containers running JDK 1.5 or later.
opensso-client-jdk14.war is for web containers running JDK 1.4.2 or later.
The following sections contain the procedures for deploying the Client SDK WAR and running the web-based and command line samples.
Download and unzip opensso_enterprise_80.zip as described in the Sun OpenSSO Enterprise 8.0 Installation and Configuration Guide. The compressed Client SDK ZIP is in the zip-root/opensso/samples/ directory where zip-root is the directory in which you unzipped the OpenSSO Enterprise download.
Deploy opensso.war as described in the Sun OpenSSO Enterprise 8.0 Installation and Configuration Guide.
Install a web container on the host machine on which the Client SDK will be deployed.
AMConfig.properties, openssoclientsdk.jar and servlet.jar are required in the CLASSPATH of the host machine on which the Client SDK is installed.
Copy the compressed opensso-client.zip to a staging directory on the host machine where you plan to deploy the Client SDK.
Unzip opensso-client.zip.
Set the JAVA_HOME environment variable to JDK 1.5 or 1.4, depending on the version of Java installed on your machine.
Deploy the appropriate Client SDK WAR (opensso-client-jdk14.war or opensso-client-jdk15.war) depending on the version of Java installed on your machine.
After successful deployment, launch the Client SDK configuration screen.
Provide the appropriate values pertaining to the instance of OpenSSO Enterprise with which the Client SDK will be communicating.
Server Protocol Protocol (http or https) used by the web container on which OpenSSO Enterprise is deployed.
Server Host Fully qualified domain name (FQDN) of the host machine on which OpenSSO Enterprise is deployed.
Server Port Port used by OpenSSO Enterprise server.
Server Deployment URI URI defined during OpenSSO Enterprise deployment. The default is /opensso. Be sure to include the leading slash (/).
Debug directory: Location of the debug directory; for example, /opensso/debug
Application user name:: The policy agent user that communicates with OpenSSO Enterprise; by default, agentAuth.
Application user password: Password of the policy agent user that communicates with OpenSSO Enterprise.
Click Configure.
A message signifying successful configuration is displayed.
AMConfig.properties for the Client SDK is also created. AMConfig.properties has been deprecated for OpenSSO Enterprise. The server configuration data is now stored in an embedded data store. The Client SDK, however, still uses AMConfig.properties to store its configuration data as it is remote to the installed OpenSSO Enterprise server. For information about the location of the AMConfig.properties file and setting properties in the file, see Using AMConfig.properties With the Client SDK.
This procedure assumes you have completed To Install the Client SDK by Deploying the Sample WAR and the successful configuration screen is still displayed.
Click the word here on the successful configuration screen displayed at the end of To Install the Client SDK by Deploying the Sample WAR.
The web-based samples introduction page is displayed.
Click Access Management Samples.
The Client SDK - Samples page is displayed.
Click Service Configuration Sample Servlet.
The Service Configuration Sample page is displayed.
Enter the password for the amadmin user.
Choose either Schema or Config from the drop-down list.
Schema refers to the data structure of the service. Default values may be defined dependent of the service. Config is the actual data. The output is defined as key/value pairs.
Click Submit.
ServiceConfigServlet.java retrieves the attributes of the Authentication Service (or other input service) and the SSOToken of the questioning user.
If an error message is displayed, confirm that the com.sun.identity.agents.app.username has a value of agentAuth and com.iplanet.am.service.password has a value of changeit in the Client SDK AMConfig.properties. If you need to modify this file, restart the underlying web container.
Click Back to Access Management Samples.
Click User Profile (Attributes) Sample Servlet.
The User Profile Sample page is displayed.
Enter the password for the default amadmin or another defined user name and password and click Submit.
The UserProfileServlet.java retrieves and displays the profile that corresponds to the user ID entered in the Username text box.
Click Back to Access Management Samples.
Click Policy Evaluator Client Sample Servlet.
The Policy Evaluator Client Sample page is displayed.
Open a new browser window, login to OpenSSO Enterprise, and using the console, create a policy for the resource http://www.sun.com:80 with a GET allow and POST deny rule for all authenticated users on Fridays.
Back on the Policy Evaluator Client Sample page, enter the amadmin password and the resource http://www.sun.com:80.
Click Submit.
PolicyClientServlet.java is the call on the client side that initiates the retrieval of a policy decision (from the Policy Service) that would be passed to a web agent for enforcement.
Click Back to Access Management Samples.
Log in to the OpenSSO Enterprise as amadmin if not already.
You must be logged in and have an SSOToken for the Single Sign On Token Verification Servlet.
Back on the Access Management Samples page, click Single Sign On Token Verification Servlet.
The user profile associated with the SSOToken received after successful authentication is displayed. The code included with this sample is SSOTokenSampleServlet.java and SampleTokenListener.java. These files serve as a basis for using the SSO API, demonstrating how you can create an SSOToken, call various methods from the token, set up an event listener and get notified on event changes.
Two other samples using the Client SDK are included on the web-based samples introduction page: the Liberty ID-WSF 1.x Web Service Consumer Sample and the Security Token Service (WS-Trust) Client Sample. See the instructions for these samples when you click the sample name.
This procedure documents compiling the command line samples as well as running them. It uses the scripts for the Solaris and Linux operating systems. opensso-client-zip-root refers to the directory in which you decompressed the appropriate Client SDK WAR.
Be sure to run all the scripts discussed one level up from the directory in which they are found.
This procedure assumes you have completed To Install the Client SDK by Deploying the Sample WAR and the successful configuration screen is still displayed.
On the command line of the machine on which the Client SDK is installed, change to opensso-client-zip-root/sdk/scripts and run chmod to make the scripts executable.
# cd opensso-client-zip-root/sdk/scripts # chmod 755 *.sh |
Execute compile-samples.sh to compile the scripts.
# cd ../ # scripts/compile-samples.sh |
Run the setup script to initialize the command line samples.
# cd ../ # scripts/setup.sh |
Use setup.bat on Windows systems.
The script uses Main.java and creates AMConfig.properties with a pointer to the opensso-client-zip-root/sdk/resources directory.
Run the individual Client SDK samples by executing the rest of the scripts in the /scripts directory.
Uses Login.java to log in and log out a user.
Uses CommandLineSSO.java to retrieve a user profile.
Uses its myriad source files to perform operations on the identity data store. For example, create an identity, delete an identity, and search or select an identity.
Uses its myriad source files (including LogSample.java) to demonstrate the login process and write a log record of a successful authentication. You will need to authenticate two identities: the subject of the LogRecord and the logger (amadmin).
to verify an SSOToken. Uses SSOTokenSample.java to demonstrate this and other functions of the session API.
Before running this sample, you will need an SSO Token ID. You can get this by running the Service Configuration Sample in To Run the Client SDK Web-based Samples and copying the ID that is displayed.
Returns a policy decision based on console created user and configured policy. Uses the code sourced in the policy directory on opensso.dev.jave.net.
Uses XACMLClientSample.java to construct a XACML request, to make an authorization query, receive the decision, and print out the response.
At run time, a sample might require additional property files to be setup in the /resources directory. Check the comments included in each individual script for more information.
You can also install the Client SDK by compiling the samples yourself. The procedure is documented in opensso-client.zip.
opensso-client.zip is in the samples directory of the downloaded and inflated opensso.zip. Unzipping opensso-client.zip reveals the war and sdk directories. The sdk directory contains source code that needs to be compiled before use and includes the following sub directories:
/classes contains the compiled classes from the source files.
/lib contains the JAR files required by the Client SDK.
/resources contains the various properties files required to run the samples, including the AMConfig.properties.template file.
/scripts contains the scripts to compile and run the samples.
/source contains the source files that require compilation.
These samples can be run in a standalone JVM outside of a web container.
Download and unzip opensso_enterprise_80.zip as described in the Sun OpenSSO Enterprise 8.0 Installation and Configuration Guide. The compressed Client SDK ZIP is in the zip-root/opensso/samples/ directory where zip-root is the directory in which you unzipped the OpenSSO Enterprise download.
Deploy opensso.war as described in the Sun OpenSSO Enterprise 8.0 Installation and Configuration Guide.
Install a web container on the host machine on which the Client SDK will be deployed.
Copy the compressed opensso-client.zip to a staging directory on the host machine where you plan to deploy the Client SDK.
Unzip opensso-client.zip.
Change to the sdk directory.
Follow the README to configure the Client SDK and, compile and run the samples.
Notifications enable the synchronization of the Client SDK cache and the OpenSSO Enterprise server. You can use the Notification Service to send session notifications to web containers that are running the OpenSSO Enterprise Client SDK, enabling real-time updates on the client side. No client application changes are required to support session notifications. The notifications can be received only if the Client SDK is installed on a web container. See Properties in AMConfig.properties for information on the notification properties.
Copy the encryption value of am.encryption.pwd from the OpenSSO Enterprise server to the remote Client SDK. The value of am.encryption.pwd is used for encrypting and decrypting passwords.
To access the am.encryption.pwd, in OpenSSO Enterprise administration console, click Configuration > Servers and Sites > serverName > Security.
Install OpenSSO Enterprise on Host 1.
Install Sun Java System Web Server on Host 2.
Install the ClientSDK on the same machine as the Web Server.
Log in to OpenSSO Enterprise as amadmin.
http://OpenSSO-HostName:8080/opensso
Execute the servlet by entering http:// ClientSDK_host:8080/servlet/SSOTokenSampleServlet into the browser location field and validating the SSOToken.
SSOTokenSampleServlet is used for validating a session token and adding a listener. Executing the servlet will print out the following message:
SSOToken host name: 192.18.149.33 SSOToken Principal name: uid=amAdmin,ou=People,dc=red,dc=iplanet,dc=com Authentication type used: LDAP IPAddress of the host: 192.18.149.33 The token id is AQIC5wM2LY4SfcyURnObg7vEgdkb+32T43+RZN30Req/BGE= Property: Company is - Sun Microsystems Property: Country is - USA SSO Token Validation test Succeeded
Set the property com.iplanet.am.notification.url= in the machine where the Client SDK is installed:
com.iplanet.am.notification.url=http://clientSDK_host.domain:port /servlet com.iplanet.services.comm.client.PLLNotificationServlet |
The notification URL is where the OpenSSO server can send change notifications to the clients. This works for web application and standalone applications that can listen on port for HTTP(s) traffic.
Restart the Web Server.
Login into OpenSSO Enterprise as amadmin.
http://OpenSSO-HostName:8080/opensso
Execute the servlet by entering http:// ClientSDK_host:8080/servlet/SSOTokenSampleServlet into the browser location field and validating the SSOToken again.
When the machine on which the Client SDK is running receives the notification, it will call the respective listener when the session state is changed. The notifications can be received only if the Client SDK is installed on a web container.
Some OpenSSO Enterprise components (such as SAML, user management, and policy) require an identity to be authenticated before the client application can read configuration data. The client can provide either a username and password that can be authenticated, or an implementation of the com.sun.identity.security.AppSSOTokenProvider interface. Either option will return a session token which the client can then use to access OpenSSO Enterprise configuration data.
The following properties in AMConfig.properties can be used to set the username and password. The authenticated username should have permission to read the OpenSSO Enterprise configuration data.
The property to provide the user name is com.sun.identity.agents.app.username.
The property to provide the plain text password is com.iplanet.am.service.password.
If a plain text password is a security concern, an encrypted password can be provided as the value of com.iplanet.am.service.secret. If an encrypted password is provided, the encryption key must also be provided as the value of am.encryption.pwd.
Add the com.sun.identity.security.AdminToken property to AMConfig.properties with a value equal to the name of the implementation of the com.sun.identity.security.AppSSOTokenProvider interface.
OpenSSO Enterprise contains both Java and .Net interfaces to enable applications using Virtual Federation Proxy (also referred to as Secure Attribute Exchange). They are provided as follows:
The Java API is provided in fmsae.jar.
The .Net API is provided in fmsae.dll.
For more information, see the README in zip-root/opensso/libraries/native/dll and Using SAML v2 for Virtual Federation Proxy.