API Packaging Guide

Overview
Developing and Running Simple Command Line Applications
ITIM API JAR Files
WebSphere Global Security
Special Considerations for Common Criteria
Upgrade to ITIM 5.0
Supported Client Types
Client Examples

Overview

This document describes the details involved in setting up an environment for the IBM's Tivoli Identity Manager (ITIM) Application Programming Interfaces (APIs) for use by custom-built ITIM applications. The ITIM API is a library that exposes the common programming functions to remote applications, custom user interfaces and portals. The ITIM API details can be found in the Application API document.

Developing and Running Simple Command Line Applications

Install the WebSphere Application Client on the system where the command line applications will be developed and run. Make sure the versions of the WebSphere Application Client and the WebSphere Application Server where the ITIM Server is installed are at the same level.

The Application API document has the neccessary details for programming with the ITIM APIs. For quick reference, see the API Example at the end of the document.

To build and run the simple command line applications that use the ITIM APIs, follow the instructions given in the WebSphere Information Center for developing thin application client code on a client machine (WebSphere Application Server, Version 6.1 -> Developing and deploying applications -> Developing WebSphere applications -> Client applications -> Running Thin application client code -> Running Thin application client code on a client machine). The link to the WebSphere Information Center can be located from where the WebSphere Application Client has been installed.

The following ITIM related jar files are required on a client's classpath:

api_ejb.jar
itim_api.jar
itim_common.jar
itim_server_api.jar

In addition, the ITIM login module has to be specified in the wsjaas_client.conf file:

ITIM { com.ibm.ws.security.common.auth.module.proxy.WSLoginModuleProxy required delegate=com.ibm.itim.apps.jaas.spi.PlatformLoginModule; };

Note: The login module config file is specified as the -Djava.security.auth.login.config argument to the client JVM.

ITIM API JAR Files

The two required JAR files listed above contain the following classes:

File	Location	Description
api_ejb.jar	$ITIM_HOME/lib	Contains stubs and other deployment classes for the session bean interfaces (Home and Remote) used by the ITIM API.
itim_api.jar	$ITIM_HOME/lib	Contains ITIM API classes (MO's and Managers). These are all the classes in apps.impl, apps.identity, apps.provisioning, apps.policy, apps.recon, apps.search, apps.workflow and apps.jaas.
itim_common.jar	$ITIM_HOME/lib	Contains ITIM data and value object classes common to API and server. These classes are used by ITIM API to encapsulate the data in its communication with the server. They also include all descendants of DirectoryObject.
itim_server_api.jar	$ITIM_HOME/lib	Contains class definitions for Home and Remote interface implementations for session beans used by the API as well as Exceptions thrown by same.

WebSphere Global Security

For enabling ITIM Server side security, see the Optionally configuring security for Tivoli Identity Manager section of Chapter 4. (Installing and configuring WebSphere Application Server) of the ManagerServer Installation and Configuration Guide for WebSphere Environments

When the Global Security is enabled on WebSphere Application Server running ITIM, make sure you set the EJB user and the EJB password when you create the InitialPlatformContext on the ITIM Client.

env.put(PlatformContext.PLATFORM_PRINCIPAL, "ejbuser"); env.put(PlatformContext.PLATFORM_CREDENTIALS, "ejbpassword"); PlatformContext platform = new InitialPlatformContext(env);

Special Considerations for Common Criteria

Tivoli Identity Manager shields its core functionality with a layer of manager enterprise Java beans (EJBs). When a client communicates with the Tivoli Identity Manager Server, every manager EJB method takes a signed token from the caller to verify the caller’s identity, except when the method itself does the authentication. The caller obtains this signed token after authenticating with the Tivoli Identity Manager Server. For more details please refer to the Customization planning -> Ensuring secure communication with custom applications section of Chapter 3. (Planning your Tivoli Identity Manager installation) of the Planning for Deployment Guide document.

ITIM Server Side Configuration

This section gives the details on how to create an EJB user and map it to the ITIM_CLIENT EJB role that is authorized to call only manager EJB methods in the unprivileged layer.

Make sure you have enabled WebSphere Application Server security and Java 2 security by following the steps in the Optionally configuring security for Tivoli Identity Manager section of Chapter 4. (Installing and configuring WebSphere Application Server) of the ManagerServer Installation and Configuration Guide for WebSphere Environments.

In addition to that, the following are required for a Common Criteria compliant environment:

For single-node deployments, create or select an administrative user in the user registry of your operating system. In subsequent examples, the user is called the unprivileged EJB user or itimnonadmin.
For multi-node deployments, depending on the directory server, create the itimnonadmin organizational Person object. In subsequent examples, the user is called the unprivileged EJB user or itimnonadmin.

IBM Tivoli Directory Server

Create an ePerson. For example, create (cn=itimnonadmin,ou=WasSecurity,dc=com). Set the following fields and values:
- sn=itimnonadmin
- cn=itimnonadmin
- uid=itimnonadmin
- userPassword=itimnonadminpwd
You can also import the following LDIF file, updating the baseDN with a value such as dc=com and userPassword variables for your environment. An example file contains these statements:

dn:cn=itimnonadmin,ou=WasSecurity,baseDN
userPassword:userPassword
uid:itimnonadmin
objectclass:top
objectclass:person
objectclass:ePerson
sn:itimnonadmin
cn:itimnonadmin

Sun ONE Directory Server

Create an inetOrgPerson. For example, create (uid=itimnonadmin,ou=WasSecurity,dc=com). Set the following fields and values:
- sn=itimnonadmin
- cn=itimnonadmin
- uid=itimnonadmin
- userPassword=itimnonadminpwd
- givenName=itimnonadminpwd
You can also import the following LDIF file, updating the baseDN with a value such as dc=com and userPassword variables for your environment. An example file contains these statements:

dn:uid=itimnonadmin,ou=WasSecurity,baseDN
userPassword:userPassword
uid:itimnonadmin
givenName:itimnonadmin
objectClass:inetorgperson
objectClass:organizationalPerson
objectClass:person
objectClass:top
sn:itimnonadmin
cn:itimnonadmin
Map an itimnonadmin user to a Tivoli Identity Manager role with these steps:
1. On the WebSphere administrative console, click Applications -> Enterprise Applications.
2. Click enRole.
3. In Additional Properties, scroll down and click Map security roles to users/groups.
4. Select the check box for ITIM_CLIENT.
5. Click Lookup users.
6. Click Search.
7. Select the EJB User (itimnonadmin) from the list.
8. Click OK.
9. To prevent unauthorized access, clear the Everyone? or All Authenticated? check boxes.
10. Save the configuration changes.

ITIM Client Side Configuration

It is recommended for security reasons that the custom applications using the ITIM APIs, running from a remote system, use the user(s) configured for the ITIM_CLIENT EJB role to authenticate against the ITIM platform. This user is called the unprivileged EJB user or itimnonadmin in the ITIM Server Side Configuration section above.

Upgrade to ITIM 5.0

When you upgrade ITIM make sure that the jar files api_ejb.jar and itim_api.jar used by the client applications are replaced by the current versions of these files on the ITIM server ($ITIM_HOME/lib). The version information is contained in the Manifest.mf file packaged with these jar files. The contents of the Manifest.mf file will be similar to the sample shown below:

Manifest-Version: 1.0 Ant-Version: Apache Ant 1.6.1 Created-By: 1.4.2_04-b05 (Sun Microsystems Inc.) Name: IdentityManagerServiceability Build-Jar: itim_api.jar Build-Number: 5669 Build-Date: May 16 2005 Build-Time: 0042 Build-Timezone: US/Pacific Build-User: build Build-Server: buildsvr

Also make sure that the WebSphere Application Server/Client is upgraded to the same level as the WebSphere Application Server where ITIM is installed.

Supported Client Types

The list of supported client types are given in the table below:

Client Type	Description
Stand-alone Java client	Deployed as a WebSphere Application Server thin client.
Web application	Deployed as a separate WAR inside ITIM.ear.
Enterprise Application, same JVM	Deployed in the same server instance (ITIM.ear) as the ITIM Server.
Enterprise Application, separate JVM	Deployed on the same machine as the ITIM Server, but on a separate server instance.
Servlets/JSPs	Servlets/JSPs not deployed in the context of a Web Application, on a separate machine running WebSphere Application Server.

Note: This is not an exhaustive list of the client types supported by ITIM.

Client Examples

The following are references to the client examples which call the ITIM APIs.