Chapter 2 Using the Client SDK

The Sun Java™ System Access Manager 6 2005Q1 Client SDK package provides Access Management Java libraries for implementing stand-alone and web applications. You can use the Client SDK interfaces in your applications to take advantage of Access Manger services such as authentication, Single Sign-On (SSO), authorization, auditing and logging, user management, and Security Assertion Markup Language (SAML). The client SDK libraries communicate with Access Manager using XML (SOAP) over HTTP or HTTPS.

How the Client SDK Works

The Client SDK is different from the SDK packages provided in previous versions of Access Manager. The Access Manager 6.3 Client SDK has been streamlined to include only the client-side classes and configuration properties you need to access Access Manager services. These changes result in a smaller jar file, and eliminate the dependency on connections to Directory Server when developing and deploying client applications. In the Access Manager 6.3 architecture, the Client SDK and client applications communicate with the Access Manager server. Only the Access Manager server communicates directly with the Directory Server.

JDK and CLASSPATH Requirements

Java Authentication and Authorization Service (JAAS). Available at the following URL: JAAS hhtp://java.sun.com/products/jaas/

Java Web Services Developer Pack 1.3 (Java WSDP). Available at the following URL: Java WSDP http://java.sun.com/products/jwsdp/

Java Secure Socket Extension (JSSE). Available at the following URL: http://java.sun.com/products/jsse/

JDK Logging. The jar jdk_logging.jar can be obtained from SUNWamsdk package for Solaris and sun-identity-sdk RPM for Linux

amclientsdk.jar. This jar is located in the directory AccessManager-base/SUNWam/lib.

servlet.jar. This jar can be obtained as part of the SUNWamsdk package, or from the AccessManager-base/SUNWam/lib directory if Access Manger is installed.


Note	To use the Client SDK with JDK 1.4.2 and higher versions, only amclientsdk.jar and servlet.jar are required in the CLASSPATH.

Configuring the Client SDK

Before installing the Client SDK, an instance of Access Manager must be running, and you must know the URL for accessing it. The client SDK libraries use this URL to communicate with Access Manager using XML (SOAP) over HTTP or HTTPS. The Client SDK is contained in the following file:

Table 2-1 Contents of *AccessManager-base*/SUNWam/amclientsdk.jar
File	Description
README.clientsdk	ASCII version of this chapter. Contains information on installing and using Access Manager client SDK.
lib/amclientsdk.jar	Client SDK for stand-alone applications.
amclient.war	Archive of Access Manager samples, web applications, and Javadoc.
Makefile.clientsdk	Defines objects and parameters for building sample properties, stand-alone samples and web applications.

To Configure the Client SDK

In Makefile.clientsdk, edit the following parameters to suit your environment:

JAVA_HOME

SERVER_HOSTNAME

SERVER_PORT

If implementing User Management, SAML, or Policy, then edit the following parameters to suit your environment:

APPLICATION_USERNAME

APPLICATION_PASSWORD

If an encrypted password or secret exists, then provide the following instead of ADMIN_PASSWORD:

ENCRYPTED_PASSWORD

ENCRYPTION_KEY

Run the make command:

make -f Makefile.clientsdk

This generates a sample properties file in the directory temp, standalone samples in the directory clientsdk-samples and a deployable war file, amclientwebapps.war, that can be deployed in any Servlet 2.3 compliant container. Table 2-2 summarizes the items included in the war file.

Table 2-2 Contents of AccessManager-base/SUNWam/amclientsdk.war
File	Description
index.html	Instructions for installing and using the Client SDK packages
WEB-INF/web.xml	Client SDK for stand-alone applications
WEB-INF/classes/AMClient.properties	Archive of Access Manager samples, web applications, and Javadoc
WEB-INF/classes/*.classes	File for building stand-alone samples and web applications
WEB-INF/docs	Javadoc (Public Client SDK APIs)
WEB-INF/samples	Sample stand-alone programs
WEB-INF/webapps	Sample web applications

Initializing the Client SDK

Before Access Manager Client SDK can communicate with Access Manager Server, you must initialize some properties in the client SDK. You can set these properties in one of three ways:

Using a Properties File

Using the Java API

Setting Individual Properties

Using a Properties File

You can set properties in a properties file and then provide a path to it at runtime. The properties files must be in the CLASSPATH. The default properties file name is AMConfig.properties and is always read at start-up.

To Set ClientSDK Properties in a Properties File

Generate a sample AMConfig.properties by running the following command:

make -f Makefile.clientsdk properties

The AMConfig.properties will be present in the temp directory.

Edit properties to suit your environment.

At runtime if the file name is different from AMConfig, provide the edited properties filename (without the .properties extension, and also with the path. The path should be in the CLASSPATH) by declaring the JVM option:

-Damconfig=filname

Using the Java API

The ClientSDK properties can also be set programatically using the class: com.iplanet.am.util.SystemProperties. See Code Example 2-1:

Code Example 2-1 Setting ClientSDK Properties

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/amserver/namingservice’);

props.setProperty(‘com.sun.identity.agents.app.username’, ‘amAdmin’);

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/amserver/namingservice’);

// Application specific code ...

}

Setting Individual Properties

You can set properties one at a time. For example, you can declare the following JVM option at run time to assign a value to a particular property:

The following sections describe the properties expected by Access Manager Client SDK. A client application deployed within a servlet container can register for changes to session, user attributes and policy decisions.These properties must be set to receive such notifications.

Naming URL Properties

com.iplanet.am.naming.url. This is a required property. The value of this property represents the URL where the Client SDK would retrieve the URLs of Access Manager internal services. This is the URI for the Naming Service. Example:

com.iplanet.am.naming.failover.url. This is a required property. This property can be used by any remote SDK application that wants failover in, for example, session validation or getting the service URLs. Example:

Debug Properties

com.iplanet.services.debug.level. Specifies the debug level.Possibe values are levels are: off, error, warning, or message.

com.iplanet.services.debug.directory. The value of this property is the output directory for the debug information. This directory should be writable by the server process. Example:

Notification URL Properties

The value of this property is the URI of the Notification Service running on the host machine where you installed the Client SDK. Example:

com.sun.identity.agents.notification.enabled. This property enable or disables notifications for remote policy API. Example:

com.sun.identity.agents.notification.url. This property defines the notification URL for remote policy API.

Setting Up a Client Identity

Some of the Access Manager components such as SAML, User Management, Policy, require an identity for the client. The client application reads configuration data to identify the client. You can set up the identity for the client in one of two ways:

Set username and password properties can be authenticated

Set an SSO Token Provider



Note	Some of the configuration attributes (such as password) are encrypted and stored in the data store as an Encryption/Decryption Key. If such attributes have to be decrypted by the client, the property must be set, and must be the same as that of the Access Manager Server. This value is generated at installation time and stored in /IdentityServer_base/SUNWam/lib/AMConfig.properties. More information on this property can be found in the Encryption section of the Appendix A, "AMConfig.properties File."

To Set Username and Password Properties

The following properties can be used to set the username and password that can be used by client SDK to obtain the configuration parameters. The authenticated username should have permissions to read the configuration data for SAML and User Management.

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

For scenarios where plain text password would be security concern, an encrypted password can be provided using the property: com.iplanet.am.service.secret

If an encrypted password is provided, the encryption key must also be provided using the property: am.encryption.pwd

To Set an SSO Token Provider

This provides an implementation for the the interface, which returns the following single-sign-on (SSO) token: com.sun.identity.security.AppSSOTokenProvider.

Building Custom Web Applications

The Client SDK package contains Makefile.clientsdk that you can use to generate and build samples and web applications. The makefile defines targets to build configuration properties, samples and web applications.

Building Stand-Alone Applications

Use these steps a template for building their identity-enabled web applications.

To Build a Stand-Alone Application

Install the Client SDK.

Follow the steps in the sectionTo Configure the Client SDK.

Copy servlet.jar to ../lib directory.

If using JDK 1.3, follow these steps:

copy the following jars to the ../lib directory:

jaas.jar

jsse.jar jce1_2_1.jar

jdk_logging.jar

Add the jar files the CLASSPATH definition in the file clientsdk-samples/defines.mk.

Run the stand-alone application.

Change directory to respective components within clientsdk-samples. Each has a Readme.html file explaining the changes to done and a Makefile to rebuild and run the program.

Targets Defined in clientsdk

For web deployment, amclientwebapps.war is ready to be deployed. However, you can make changes in clientsdk-webapps directory and the war file can be recreated.

Custom web applications can use the following as a template to build their identity enabled web application.

properties: Generates AMConfig.properties in the temp directory that can used as a template for setting AM SDK's properties

samples: Copies standalone samples and corresponding Makefiles to samples directory.

webapp: Generates amclientwebapps.war that can be deployed on any Servlet 2.3 compliant web container.

About the Client SDK Samples

Sample files are included in the Client SDK. These demonstrate how to write stand-alone programs and how to write web applications.The samples are located under the directory where you generated the Makefile.clientsdk, and in the following subdirectories:

Clientsdk-samples includes samples for authentication, logging, policy and SAML stand-alone programs.Clientsdk-webapps includes samples for user management, service management, and policy programs. Each sample has a Readme.html file with instructions on compiling and running the sample program..

Previous Contents Index Next
Sun Java System Access Manager 6 2005Q1 Developer's Guide