Contents: About IBM Tivoli Access Manager Authorization Java Classes Performance Tuning Tips Summary Resources About the author Rate this article Subscriptions: dW newsletters dW Subscription (CDs and downloads)

Neil Readshaw (readshaw@au1.ibm.com)
Security Products Integration, IBM
17 December 2003

Tivoli Access Manager provides a set of Java classes that expose its authorization services to developers. Optimizing use of these classes in a performance-sensitive environment can make a significant improvement to the scalability of the solution environment. This document discusses techniques for tuning performance of an application that uses the Authorization Java Classes and the infrastructure upon which it depends.

About IBM Tivoli Access Manager
IBM Tivoli Access Manager is a robust and secure policy management tool for e-business and distributed applications. It addresses the challenges of escalating costs for e-business security, growing complexity of enterprise security solutions, and the inability to implement security policies across platforms. Through its highly available centralized authorization service, IBM Tivoli Access Manager enables better management of business-critical distributed information. It provides simple, secure access to critical information, and enhances communications with customers, business partners, and others.

Figure 1. IBM Tivoli Access Manager

IBM Tivoli Access Manager provides authentication and access control services for Web resources. The WebSEAL server, a component of IBM Tivoli Access Manager for e-business, manages access to all Web servers—regardless of their platforms. This allows an organization to centrally control their Web resources as a single, logical Web space.

IBM Tivoli Access Manager for Business Integration provides protection for MQSeries messages. It allows MQSeries applications to send data with confidentiality and integrity using keys associated with the sending and receiving users. The IBM Tivoli Access Manager authorization service provides access control to MQSeries based services, restricting which users or processes can and cannot put messages on queues or get messages from queues.

IBM Tivoli Access Manager also provides application APIs to allow in-house developed applications to access IBM Tivoli Access Manager services. IBM Tivoli Access Manager supports the J2EE standard JAAS (Java Authentication and Authorization Service) to allow native Java applications to access IBM Tivoli Access Manager for authorization decisions. IBM Tivoli Access Manager also provides an implementation of the Open Group’s standard authorization C-language API (AznAPI) to allow applications that want to call out to a C API to use the IBM Tivoli Access Manager authorization and entitlements services.

IBM Tivoli Access Manager provides a robust web-based delegated security administration utility that allows delegate security administration to members of their eCommunity.

Authorization Java Classes
Tivoli Access Manager provides a rich set of authorization services to a wide variety of application architectures. The Authorization Java Classes in Tivoli Access Manager provide a way to invoke these authorization services from when using the Java programming environment. These classes are used within Tivoli Access Manager (for example, in Tivoli Access Manager for WebSphere), as well as by application programmers who choose to use the classes directly to evaluate authorization decisions specific to solving their own business problems.

Architecture
The Tivoli Access Manager architecture provides two architectures when using the Java Authorization API.

Remote Mode
When using Remote Mode, credential acquisition and authorization decision operations are proxied to a separate Authorization Server. This results in an out-of-process, TCP/IP connection. This mode allows for the smallest impact to the deployment of the Java environment in which the Authorization Java Classes are being used.

Figure 2. Tivoli Access Manager – Remote Mode Authorization

Local Mode
The Local Mode architecture provides a higher-performance alternative to Remote Mode, by increasing the amount of processing performed in-process. A side effect of this is that the impact to the deployment of the Java environment is increased, as a cache of the policy database is kept locally. This cache is memory resident when the process runs, and persisted to disk for availability reasons.

Figure 3. Access Manager – Local Mode Authorization

Upcoming Support
Local Mode is currently only available for the Tivoli Access Manager implementation of the AznAPI (C bindings). The Java bindings currently only support Remote Mode. In the upcoming Tivoli Access manager 5.1 release, Local Mode support is being added for some aspects of the Authorization Java Classes:

• Local replication of policy database
• Evaluation of ACL
• Evaluation of POP

The following capabilities of the Authorization Java Classes will not be evaluated locally in the upcoming 5.1 release, but will continue to be evaluated in a fashion equivalent to Remote Mode described above.

• Authentication
• Credential acquisition and modification
• Evaluation of Boolean rules
• Pluggable extended authorization services

Comparison
The following table summarizes the differences between Remote Mode and Local Mode.

Table 1. Comparison between Remote and Local mode

Criteria	Remote Mode	Local Mode
Authentication – PDPrincipal(username,password)	Proxied via authorization server	Proxied via authorization server
Credential Acquisition - PDPrincipal(username)	Proxied via authorization server	Proxied via authorization server
Authorization – PDPermission.implies()	Proxied via authorization server	Evaluated locally
Java environment requires in-memory policy database?	No	Yes
Java environment requires local storage of policy database?	No	Yes
Java environment receives connections from policy server?	No	Yes
Connectivity required from policy server to Java environment?	No	Yes
Connectivity required from Java environment to authorization server	Yes	Yes
Appropriate for multi-threaded environments?	Yes	Yes
Configuration Tool	com.tivoli.pd.jcfg.SvrSslCfg	com.tivoli.pd.jcfg.SvrSslCfg
Deployment Complexity	Low	Medium
Performance	Lower	Higher
Product Availability	Version 3.8 and above	Version 5.1 and above

Example
Tivoli Access Manager’s Authorization Java Classes are simple to use. The example below walks through the steps required to configure a JRE for use, register the application with Tivoli Access Manager, and then run a sample program.

Configure the JRE
This program copies over JAR files from the Tivoli Access Manager distribution, and initializes some configuration files in the JRE environment.

$ c:\progra~1\tivoli\policy~1\sbin\pdjrtecfg -action config -java_home
 C:\Progra~1\IBM\WebSph~1\runtimes\base_v5\java\jre

Register the Application
This step creates a new server entry in the Tivoli Access Manager policy server, and a new principal representing that server.

$ java com.tivoli.pd.jcfg.SvrSslCfg -action config -mode remote 
-port 12345 -admin_id sec_master -admin_pwd 
serenity -cfg_file c:/temp/PdPerm.properties -key_file c:/temp/pdperm.ks
-appsvr_id mts-test -policysvr
localhost:7135:1 -authzsvr localhost:7136:1

Note that the Java executable used to execute the program should be the one configured in the preceding steps. It is recommended to always specify the full path to the Java executable to avoid making a mistake at this step.

Sample Code
The following program authenticates a user and performs a single authorization request, as specified by the command line parameters.

import com.tivoli.pd.jutil.*;
import com.tivoli.mts.*;
import java.net.*;

/**
 * @author readshaw
 */
public class SimpleAuthorization {

public static void main(String[] args) {
	try {
		if (args.length < 3) {
			throw new Exception(
				"Usage error: "
					+ "\n\tjava SimpleAuthorization 
					<config-url> <username> <password> 
					<object> <action>");
			}

			URL configURL = new URL(args[0]);

			PDPrincipal who =
				new PDPrincipal(args[1], args[2].toCharArray(), 
				configURL);
			PDPermission what = new PDPermission(args[3], args[4]);
			boolean result = who.implies(what);

			System.out.println(
				"Permission check ("
					+ args[1]
					+ ","
					+ args[3]
					+ ","
					+ args[4]
					+ "): "
					+ result);
		} catch (PDException pex) {
			System.err.println(pex.getMessages());
			pex.printStackTrace(System.err);
		} catch (Exception e) {
			System.err.println(e.toString());
		}
	}
}

Sample Output

$ java file:///c:/temp/PdPerm.properties testuser passw0rd / T
Permission check (testuser,/,T): true

Note that the Java executable used to execute the program should be the one configured in the preceding steps. It is recommended to always specify the full path to the Java executable to avoid making a mistake at this step.

Performance Tuning Tips
In the cases where business and/or technical requirements dictate that performance is a high priority when using the Authorization Java Classes, there are a number of steps that can be taken to optimize the configuration and use of these capabilities.

Network Topology
When using either remote or local mode, authentication requests will be proxied via the authorization server. However, in local mode environments, where this is not necessarily required for authorization performance, adequate authentication rates may be achieved with an authorization server on a different machine.

• Co-locating the authorization server with the Java environment will improve the performance characteristic for authentication operations.

When using remote mode, authorization decisions are proxied to the authorization server.

• Co-locate an authorization server on the same machine as the Java environment to minimize the communications overhead of evaluating authorization decisions.

Directory Server
The directory server is accessed by the authorization server in response to the Authorization Java Classes constructing a PDPrincipal object from a username, or username and password. The prescribed operations for the directory server should be followed to ensure that it is tuned for efficient operation.

• For the IBM Directory Server, the “IBM Tivoli Access Manager - Performance Tuning Guide” contains performance tuning information.

Authorization Server
When using an LDAP directory, the authorization server has parameters to control its LDAP cache. See the comments in the [ldap] stanza of the authorization server’s configuration file for more information on how the cache’s behavior can be controlled. Remember, increasing cache sizes will reduce connectivity with LDAP, but also makes the authorization clients less likely to receive fresh directory data. This tradeoff needs to be evaluated in the context of the impact of stale cache data being used, and the dynamics of the directory data.

• Configure the expiry time of the user, group and policy objects in the cache to maximize cache lifetime while preserving an acceptable degree of data freshness in the cache.

• Configure the size of the user, group and policy cache to hold a suitable number of objects, without causing the authorization server’s machine to page.

Coding Techniques
The PDPrincipal constructor communicates with LDAP via the authorization server to acquire credentials. These operations are considerably more expensive than evaluating authorization decisions – remote or local mode.

• Where session semantics exist between the application and its clients, consider implementing a session cache for PDPrincipal objects.

• Construct PDPrincipal objects using more efficient constructors. Building a PDPrincipal object from an existing credential (e.g. an iv-creds header from WebSEAL) will avoid communication with the authorization server and LDAP.

Auditing
Auditing of security events is an important aspect of deploying a security infrastructure, however auditing superfluous events in the authorization server or directory server will impact overall performance.

• Ensure audit configuration is set to produce the minimum number of audit events that continue to meet the business and technical requirements.

Summary
A range of performance tuning options is available to the application developer and solution architect for applications that use the Tivoli Access Manager Authorization Java Classes. With the introduction of the local mode support in the upcoming Tivoli Access Manager 5.1, even more options will be available, and even greater performance will be achieved.

Resources

• IBM Tivoli Access Manager - Authorization Java Classes Developer's Reference
  
  
• IBM Tivoli Access Manager - Performance Tuning Guide
  
  
• Download the source code used in this article.
  
  

What do you think of this document? Killer! (5) Good stuff (4) So-so; not bad (3) Needs work (2) Lame! (1) Comments?

developerWorks > Tivoli