Sun Java System Access Manager 6 2005Q1 Developer's Guide |
Chapter 2
Using the Client SDKThe 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 WorksThe 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.
Figure 2-1 Client SDK Architecture
JDK and CLASSPATH RequirementsThe Client SDK can be used with JDK versions J2SE 1.3.2, J2SE 1.4.2 and higher.
To use the Client SDK with JDK 1.3.2 add the following to the CLASSPATH:
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 SDKBefore 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:
AccessManager-base/SUNWam/lib/amclientsdk.jar
Table 2-1 summarizes items included in the Client SDK.
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.
Initializing the Client SDKBefore 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 programatically using the class: com.iplanet.am.util.SystemProperties. See Code Example 2-1:
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.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
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.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 IdentitySome 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.
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 the interface, which returns the following single-sign-on (SSO) token: com.sun.identity.security.AppSSOTokenProvider.
Building Custom Web ApplicationsThe 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:
- 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..