Writing Java Extensions in ITIM

Writing Java Extensions in ITIM

By Siva Praturi

The Identity Manager provisioning platform is designed with extensibility as a primary goal. Below are few typical scenarios in which we generally extend ITIM capability to meet business requirements.

-          Generate UniqueIds during provisioning accounts

-          Adding custom debug messages to ITIM log

-          Custom approval process that is determined by looking up an approver in a database

You can extend ITIM workflows in two ways: create a workflow extension in Java that can be called as a regular operation, or extending the JavaScript Engine with Java

To Extend JSEngine, One method to write an extension in java that is called from Tivoli Identity Manager (TIM), is to add a new custom class into the application and then call it from Javascript.

There is an alternative method, which uses classes that implement the com.ibm.itim.script.ScriptExtension interface. This method allows extensions to be limited to specific TIM components and access context information such as variables. This method is more complicated.

Developing Java Extensions in ITIM

Below figure shows typical deployment of custom Java Extensions in ITIM.

 Steps involved in writing Java Extensions in ITIM are

1. Develop & build custom java code as per business requirement.
2. Deploying the new extension.

-          Updating the Application Server's Classpath

-          Registering the JavaScript Extensions

3. Test Java Extensions by calling them from ITIM workflows.      

Updating the Application Server's Classpath

TIM is a J2EE application, running on top of IBM WebSphere Application Server (WAS). To add a Java class to the application, follow these steps:

1. Compile the Java code into a class file. To use the TIM API, put $ITIM_HOME/lib/itim_server.jar the class path

2. Include the Java class and properties file into a Java archive (JAR) file.

3. Log on to the WAS integrated services console. Perform step 4 or step 5 to add jar file to classpath

4. Create a new shared library that includes the JAR file you created. Modify the ITIM application: Change the Shared library references to add the new shared library.

5. Another option is to Expand ‘Environment’ menu and click on ‘Shared Libraries’. Click on ‘ITIM_LIB’ shared library. Under ‘General Properties’, append in (JAR) file in list of Classpath property.

6. Save the modified WAS configuration.

Registering the JavaScript Extensions

There are the steps to call the new class from JavaScript:

1. Edit this file: $ITIM_HOME/data/scriptframework.properties

In the file, add a property that starts with ITIM.java.access whose value is equal to the name of the new class. For example:  ITIM.java.access.test=com.ibm.tivoli.javaext.TestClass

2. Restart WebSphere Application Server

3. Use the class in JavaScript within ITIM to test it. For example: define a variable test in identity policy and request an account.

 var test = new com.ibm.tivoli.javaext.TestClass()

Note: To learn more on ITIM Extensions, look at the demonstration code at $ITIM_HOME/extensions/5.1/examples/directory.

Tivoli Access Manager Tracing

Tivoli Access Manager Tracing

By Siva Praturi

IBM Tivoli Access Manager provides configurable tracing capabilities that can aid in problem determination. Tracing can be activated either through a routing file, or through pdadmin server task trace command.  Trace files are required to assist support personnel in diagnosing problems occurring with the functioning of the Tivoli Access Manager software.

Using routing files

A routing file can be used for enabling and disabling trace. The routing file is a file that can be used to define the name, location, and logging behaviour of certain message log and trace log files. The Tivoli Access Manager Base and WebSEAL components each have their own routing (or routing.template) files defined within their respective etc directories.

The contents of a routing file are fairly self-descriptive. When using a routing file to affect trace logging or message logging, you must stop and restart Tivoli Access Manager Component for the routing file change to take effect.

Using pdadmin trace utility

The pdadmin server task trace command can be used to dynamically control trace operations for the Tivoli Access Manager authorization server, WebSEAL, and the Tivoli Access Manager Plug-in for Web Servers. Trace utility allows you to capture information about error conditions and program control flow in Tivoli Access Manager Components. This information is stored in a file and used for debugging purposes.

Tracing for the Tivoli Access Manager policy server cannot be controlled dynamically with the pdadmin server task trace command. You must use the routing file to enable tracing for the policy server. The policy server must be restarted for any routing file modifications to take effect.

Let’s take a look at the tracing system in Tivoli Access Manager and some of the less complex WebSEAL and WebPI trace points in detail.

Trace elements

There are two elements within the trace system used to control the activation of trace statements. These are the trace component and the trace level.

Trace component: The trace within Tivoli Access Manager is organized into trace components. It is important to select the appropriate trace component to troubleshoot the problem area. The trace components themselves are organized in a hierarchical fashion. If trace is activated for a parent trace component, it will automatically be activated for all children trace components.

Trace level: The amount of detail that is produced for a particular trace component is governed by the trace level that is selected. The trace level is a single integer within the range of 1-9, with 9 reporting the most amount of detail and 1 reporting the least amount of detail.

Trace output generally consists of A time stamp for the trace entry, ID of the thread, Name of the trace component, Name of the product source file and

Trace text

Below figure illustrates the process flow for pdadmin server task trace command

Listing trace components

To list all of the trace components offered by a server, issue the trace list command:

server task <server-name> trace list

Adjusting the trace level of a component

To change the level and destination for a specific trace point, use the following command:

server task <server-name> trace set <component> <level> [file path=file|other-log-agent-config]

Where component is the name of trace component as shown by the list command. The level will control the amount of detail to be gathered, in the range of 1 to 9. The optional file path parameter specifies the location for trace output. If this parameter is not supplied the trace output will be sent to the stdout stream of the server.

Retrieving the current trace level of a component

To show the names and levels for all enabled trace components use the following command:

server task <server-name> trace show [component]

If the component parameter is omitted the output will list the name and level of all of the enabled trace components.

Generally used Trace Components with WebSEAL & WebPI

pd.ivc.ira	The pd.ivc.ira component is used to trace the Tivoli Access Manager interaction with the LDAP server. As such, it is a trace component that can be used with WebSEAL or PDWebPI. The trace is useful in determining problems that occur during authentication.
pdweb.debug	The pdweb.debug component is used to trace the HTTP headers sent between the client and WebSEAL. This includes the headers contained within the request, as well as the response.
pdweb.snoop.client	The pdweb.snoop.client component is used trace the HTTP packets which are transmitted between WebSEAL and the client.
pdweb.snoop.jct	The pdweb.snoop.jct component is used trace the HTTP packets that are transmitted between WebSEAL and the junctioned back-end Web server.
pdweb.wan.azn	The pdweb.wan.azn component is used to trace the authorization decision for all transactions. This includes details related to the credential upon which the authorization decision is made, the resource that is being accessed, as well as the result of the authorization decision.
pdweb.wns.authn	The pdweb.wns.authn component is used to trace details concerning the authentication process applied by WebSEAL. This includes information such as the authentication mechanism, the details used during the authentication process, and the result of the authentication.
pdwebpi.azn	The pdwebpi.azn component is used to trace the authorization decision for all transactions.
pdwebpi.proxy-cmd	The pdwebpi.proxy-cmd trace component can be used to examine these commands, and from this an administrator can derive what the proxy component is instructing the Web server to do with each request.
pdwebpi.request	The pdwebpi.request component is used to trace the HTTP requests that are received by the system.
pdwebpi.session	The pdwebpi.session component is used to trace details pertaining to a user's session. In particular, it will trace the contents of the user's session along with session expiration details and any changes that might be made to a user's session.

Note: Use trace with caution. It is intended as a tool to use under the direction of technical support personnel. Messages from trace are sometimes cryptic, are not translated, and can severely degrade system performance.