Chapter 14 Using the Client
SDK
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:
About the Client SDK
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.
Caution –
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.
Caution –
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.
OpenSSO Enterprise Client SDK Requirements
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.
Using the Client SDK
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.
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
-
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.
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
-
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.
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.
-
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.
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 –
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
-
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.
Polling Properties
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.
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.
-
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.
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
-
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:
OpenSSO Enterprise Server and Console Location Properties
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.
Cookie Property
com.iplanet.am.cookie.name contains the
name of the OpenSSO Enterprise cookie; by default, iPlanetDirectoryPro.
Client Side Session Polling Properties
-
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.
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.
-
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.
Caution – 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
Policy Logging and Caching Properties
-
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.
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
Installing the Client SDK and Running the
Samples
There are two ways to install the Client SDK. These options
are documented in the following sections:
Installing the Client SDK by Deploying the
Sample WAR
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.
The following sections contain the procedures for deploying
the Client SDK WAR and running the web-based and command line samples.
To Install the Client SDK by Deploying the
Sample WAR
Before You Begin
-
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.
To Run the Client SDK Web-based Samples
Before You Begin
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.
Tip –
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.
Next Steps
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.
To Run the Client SDK Command Line Samples
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.
Caution –
Be sure to run all the scripts discussed one level
up from the directory in which they are found.
Before You Begin
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
|
Note –
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.
-
Login.sh/Login.bat
-
Uses Login.java to log in and log out a user.
-
CommandLineSSO.sh/CommandLineSSO.bat
-
Uses CommandLineSSO.java to retrieve a user profile.
-
CommandLineIdrepo.sh/CommandLineIdrepo.bat
-
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.
-
CommandLineLogging.sh/CommandLineLogging.bat
-
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).
-
SSOTokenSample.sh/SSOTokenSample.bat
-
to verify an SSOToken. Uses SSOTokenSample.java to demonstrate this and other
functions of the session API.
Note –
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.
-
run-policy-evaluation-sample.sh/run-policy-evaluation-sample.bat
-
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.
-
run-xacml-client-sample.sh/run-xacml-client-sample.bat
-
Uses XACMLClientSample.java to construct a XACML request,
to make an authorization query, receive the decision, and print out
the response.
Note –
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.
Installing the Client SDK By Compiling the
Samples
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.
Note –
These samples can be run in a standalone JVM outside of
a web container.
To Install the Client SDK by Compiling the
Samples
Before You Begin
-
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.
Sending Notifications to the Client SDK Cache
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.
To Enable Client SDK Cache Notifications
Before You Begin
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.
Setting Up a Client SDK Identity
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.
To Set Username and Password Properties
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.
Note –
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.
To Set an SSO Token Provider
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.
Using the Virtual Federation Proxy Client
Interfaces
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:
For more information, see the README in zip-root/opensso/libraries/native/dll and Using SAML v2 for Virtual Federation Proxy.
Scarica il manuale in formato PDF (2140 KB)