Sun Java System Access Manager 7 2005Q4 Developer's Guide

Chapter 1 Using the Client SDK

The Sun Java^TM System Access Manager 7 2005Q4 Client SDK package provides Access Management Java libraries for implementing stand-alone applications 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 pre-6.3 versions of Access Manager. The Access Manager 6.3 Client SDK was streamlined to include only the client-side classes and configuration properties you need to connect to Access Manager services. These changes resulted 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 and 7.0 architecture, the Client SDK and client applications communicate with the Access Manager server. Only the Access Manager server communicates directly with the Directory Server.

When you install the Access Manager server, the Client SDK is contained in the following file:

AccessManager-base/SUNWam/lib/amclientsdk.jar

The following table summarizes items included in the Client SDK.

Table 1–1 Contents ofAccessManager-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.

JDK and CLASSPATH Requirements

The Client SDK can be used with JDK version 1.4.2. Both amclientsdk.jar and servlet.jar are required in the CLASSPATH.

Installing the Client SDK

You can obtain the Client SDK from the Access Manager compact disc, and then complete the following steps:

To Install the Client SDK

Before You Begin

The Access Manager server which will be used by the client SDK must be up and running, and you must know the URL for accessing this server.
The machine where the client SDK will be installed must have an Access Manager supported web container installed. Examples of Access Manager supported web containers are Sun Java System Web Server 6.1 sp5, Sun Java System Application Server 8.1, BEA WebLogic Server 8.1 sp4, and IBM Websphere Application Server 5.1.1.5.
The web container instance on which the client SDK will be deployed must be up and running.
The client SDK machine must have access to the Access Manager client SDK package SUNWamclnt through the Java Enterprise System 4 bits or through some other means.

Create a package administration file. .

Using a text editor, add the following contents to this file.
```
mail=
instance=unique
partial=nocheck
runlevel=nocheck
idepend=nocheck
rdepend=nocheck
space=nocheck
setuid=nocheck
conflict=nocheck
action=nocheck
basedir=ClientSDK-base-directory
```
In this example, the package administration file is named /usr/tmp/pkgadmin.

The value for basediris the directory in which you want to install the Access Manager client SDK.

Create a package response file named /usr/tmp/pkgresp.

Using a text editor, place the following three lines (a single y on each line) in this file.
```
y
y
y
```

In the Access Manager package directory, use the pkgadd utility to install the SUNWamclnt package:

cd JES2005Q4-Image-root/OperatingSystem-Architecture/Product/identity_svr/Packages

pkgadd -n -a /usr/tmp/pkgadmin -d . -r /usr/tmp/pkgresp -R / SUNWamclnt

In the directory in which you installed the Access Manager client SDK package, make a copy of the file Makefile.clientsdk.

The directory in which you installed the Access Manager client SDK package should be the same as the value you used for basedir in the package administration file in step 1a.

On Solaris:

cd ClientSDK-base-directory/SUNWam

cp Makefile.clientsdk Makefile.clientsdk.orig

On Linux:

cd ClientSDK-base-directory/identity

cp Makefile.clientsdk Makefile.clientsdk.orig

To Configure the Client SDK

In Makefile.clientsdk, edit the following parameters:

JAVA_HOME

Use the following path: /usr/jdk/entsys-j2se

SERVER_HOSTNAME

The fully-qualified domain name of the Access Manager server.

SERVER_PROTOCOL

If the Access Manager server is SSL-enabled, change this value to HTTPS.

SERVER_PORT

The port number on which the Access Manager server is running.

ENCRYPTION_KEY

This value must be the same value used for the Access Manager server. You can obtain the value by running one of the following commands on the Access Manager server:

On Solaris

grep pwd /etc/opt/SUNWam/config/AMConfig.properties

On Linux

grep pwd /etc/opt/sun/identity/config/AMConfig.properties

DEBUG_DIR

(Optional) If you don't want the debug logs stored in the tmp directory, then change this value to the directory where you want debug logs to be created.

Run the make or gmake command:

make -f Makefile.clientsdk

This step generates a sample properties file in the directory temp, standalone samples in the directory clientsdk-samples and a deployable war file, amclientwebapps.war.The following table summarizes the items included in the WAR file.

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

To Deploy amclientwebapps.war

Create a deployment directory for amclientwebapps.war.

On Solaris

mkdir -p ClientSDK-base-directory/SUNWam/web-src/clientsdk

On Linux

mkdir -p ClientSDK-base-directory/identity/web-src/clientsdK

On the web container instance where you want to use the Access Manager client SDK, deploy the amclientwebapps.war file. See the following examples:

Sun Java Enterprise Web Server on Solaris or Linux

Use the wdeploy command to deploy amclientwebapps.war with a URI of /amcilentwebapps on the Web Server instance https-clientSDKinstance. Example:

WebServer-base-directory/bin/https/httpadmin/bin/wdeploy deploy -u /amclientwebapps -i https-clientSDKinstance -v https-clientsdkinstance -d ClientSDK-base-directory/SUNWam/web-src/clientsdk clientSDK-base-directory/SUNWam/amclientwebapps.war

Sun Java Enterprise Application Server on Solaris

Using the asadmin command to deploy amclientwebapps.war with a URI of /amclientwebapps on the application server instance clientsSDKinstance. Example:

ApplicationServer-base-directory/appserver/bin/asadmin deploy -user Admin-User-ID --host ApplicationServer-instanceHost --port ApplicationServer-Admin-Port --contextroot amclientwebapps -name amcilentwebapps -target clientSDKinstance ClientSDK-base-directory/SUNWam/amclientwebapps.war

Be sure to use the fully qualified host name for ApplicationServer-instanceHost.

Enter the Application Server administration password when prompted.

Sun Java Enterprise Application Server on Linux

Using the asadmin command to deploy amclientwebapps.war with a URI of /amclientwebapps on the application server instance clientsSDKinstance. Example:

ApplicationServer-base-directory/bin/asadmin deploy -user Admin-User-ID --host ApplicationServer-instanceHost --port ApplicationServer-Admin-Port --contextroot amclientwebapps -name amcilentwebapps -target clientSDKinstance ClientSDK-base-directory/SUNWam/amclientwebapps.war

Be sure to use the fully qualified host name for ApplicationServer-instanceHost.

Enter the Application Server administration password when prompted.

If you are deploying the client SDK on a third-party web container such as BEA WebLogic Server or IBM WebSphere Application Server, then see the documentation that comes with that product.

Restart the web container instance on which the Access Manager client SDK was deployed.

If the full server instance being accessed by the client SDK is SSL-enabled, then you must install the root CA certificate of the server's certificate in the web container's JVM-wide cacerts keystore. Alternatively, you can create a keystore on the client SDK machine to contain the server's root CA certificate. Then add the necessary JVM options to the client SDK's web container instance to locate the newly created keystore.

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

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 programmatically using the class: com.iplanet.am.util.SystemProperties. See Using the Java API.

Example 1–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:

-DpropertyName=propertyValue

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.url=http://AcceessManager-HostName.domain_name:
		port/ amserver/namingservice

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

com.iplanet.am.naming.failover.url= http:// 
		AcceessManager-HostName.domain_name:port/		amserver/failover

Debug Properties

com.iplanet.services.debug.level

Specifies the debug level. Possible 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:

com.iplanet.services.debug.directory=/var/opt/SUNWam/debug

Notification URL Properties

com.iplanet.am.notification.url.

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.iplanet.am.notification.url= http://clientSDK_host.domain_name:
		port/amserver/notificationservice

com.sun.identity.agents.notification.enabled

This property enables or disables notifications for remote policy API. Example:

com.sun.identity.agents.notification.enabled=false

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 /AccessManager-base/SUNWam/lib/AMConfig.properties .

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

Set the following property: com.sun.identity.security.AdminToken

This provides an implementation for 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.

See Installing the Client SDK.

Copy servlet.jar to lib directory.

If using JDK 1.3, follow these steps:
1. copy the following jars to the lib directory:
  - jaas.jar
  - jsse.jar jce1_2_1.jar
  - jdk_logging.jar
2. 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/

.../clientsdk-webapps/

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.