Integrate Tivoli Access Manager with ObjectGrid to authenticate and authorize your distributed clients

Learn about ObjectGrid authentication and authorization, then see how IBM® Tivoli® Access Manager can be integrated with ObjectGrid to provide a secure enterprise distributed cache solution. An example is provided to demonstrate how you can accomplish this integration. This content is part of the IBM WebSphere Developer Technical Journal.


Jian Tang (, Software Engineer, IBM

Jian Tang is a software engineer at IBM Rochester Lab in Rochester MN. He works on the ObjectGrid development team and is primarily responsible for ObjectGrid security and stream query technologies.

23 January 2008

Also available in Chinese


The ObjectGrid component of IBM® WebSphere® Extended Deployment V6.1 is a grid-enabled, in-memory data store for for Java™ objects, designed for scalability, resilience, and high-performance. ObjectGrid can be used simply as an in-memory database, or it can be used to distribute data across a network.

ObjectGrid provides out-of-box security support for Java Authentication and Authorization Service (JAAS). However, since JAAS is CodeSource-based and uses the plaintext format policy file implementation, it may not be sufficient to adequately protect an enterprise application. For this reason, ObjectGrid also possesses the ability to integrate with other enterprise security software.

IBM Tivoli® Access Manager for e-business is a widely used, enterprise-wide security solution that provides a complete authentication and authorization solution for enterprise environments, and also fully supports JAAS. ObjectGrid can be integrated with Tivoli Access Manager to achieve a secure distributed cache solution.

This article explains how to use the Tivoli Access Manager Authorization Java API to authenticate and authorize distributed ObjectGrid clients, and includes coding samples to illustrate how this integration can be accomplished. This article assumes a functional understanding of Java programming, basic knowledge of ObjectGrid and Tivoli Access Manager, and familiarity with the concepts of authorization and authentication. See Resources for more information.

Overview of ObjectGrid security

A distributed ObjectGrid hosts data in ObjectGrid servers, and ObjectGrid clients connect to servers to read or update data. ObjectGrid adopts open security architecture to authenticate and authorize clients. The open security architecture enables ObjectGrid to integrate with external security products (see Resources).

As in any secure distributed environment, authentication and authorization are two of the most important security features in a secure distributed ObjectGrid system. An ObjectGrid client must provide a credential to authenticate to the ObjectGrid server, and this client must be authorized to invoke ObjectGrid operations. ObjectGrid does not provide any out-of-the-box security implementation of its own, but it does provide security plug-ins so you can implement the security mechanism of your choice.

Figure 1 shows how an ObjectGrid server authenticates and authorizes clients. Steps 1 through 6 show the authentication process, and steps 7 though 9 show the authorization process. The three green circles represent ObjectGrid plug-ins, and the two yellow cylinders represent external security services.

Figure 1. ObjectGrid authentication and authorization architecture.
Figure 1. ObjectGrid authentication and authorization architecture.
  • Authentication flow
    1. The authentication flow starts with an ObjectGrid client getting the credential which represents itself. This is done by the plug-in
    2. In a nutshell, a CredentialGenerator object knows how to generate a valid client credential, for example, a user ID/password pair, Kerberos ticket, and so on.
    3. After the ObjectGrid client retrieves the Credential object using the CredentialGenerator object, this client Credential object is sent along with the ObjectGrid request to the ObjectGrid server.
    4. The ObjectGrid server authenticates the Credential object before processing the ObjectGrid request. ObjectGrid server uses the Authenticator plug-in to authenticate the Credential object.
    5. The Authenticator plug-in represents an interface to the user registry, for example, an LDAP server or an operating system user registry. The Authenticator consults the user registry and makes authentication decisions.
    6. If the authentication is successful, a Subject object is returned to represent this client.
  • Authorization flow

    ObjectGrid adopts a permission-based authorization mechanism. ObjectGrid has different permission categories represented by different permission classes. For example, a represents permissions to read, write, insert, invalidate, and remove the data entries in an ObjectMap. Since ObjectGrid supports JAAS authorization out-of-box, you can utilize JAAS to handle ObjectGrid authorization by providing authorization policies. Besides that, ObjectGrid also supports custom authorizations. Custom authorizations are plugged in by the plugin-in

    1. The server runtime sends the Subject object and the required permission to the ObjectGrid authorization plug-in.
    2. The ObjectGrid authorization plug-in consults the Authorization service and makes an authorization decision. If the permission is granted for this Subject object, a value of "true" is returned; otherwse a "false" is returned.
    3. This authorization decision, true or false, is returned to the server runtime.

See the ObjectGrid Security JavaDoc for more information on other permission types and security plug-ins.

Integrating Tivoli Access Manager

Of the many components that make up Tivoli Access Manager (hereafter referred to as Access Manager), these components are required to run the sample in this article:

  • Access Manager Directory Server is the IBM implementation of the Lightweight Directory Access Protocol (LDAP) for supported operating systems. The Directory Server provides a server that stores directory information using an IBM DB2® database, a proxy server for routing LDAP operations to other servers, a client, and a graphical user interface (GUI) for managing servers.

  • Access Manager Policy Server maintains the master authorization database for the management domain, as well as the policy databases associated with other secure domains that you might decide to create.

  • Access Manager Authorization Server provides access to the authorization service for third-party applications that use the Tivoli Access Manager authorization API in remote cache mode. It bridges third-party applications, such as ObjectGrid, to the Access Manager Policy server.

  • Access Manager Runtime for Java offers a reliable environment for developing and deploying Java applications in a Tivoli Access Manager secure domain. It can be used to add Tivoli Access Manager authorization and security services to new or existing Java applications.

As you saw in Figure 1, there are three plug-ins that need to be created so that Access Manager can be used to perform authentication and authorization for ObjectGrid:

  • CredentialGenerator and Credential

    A Credential object represents a client credential, such as user ID/password pair, a Kerberos ticket, and so on. A CredentialGenrator object represents a credential factory that creates a credential. For example, if the credential is a Kerberos ticket, the CredentialGenerator will create the Kerberos ticket. When the Kerberos ticket expires, the CredentialGenerator should be able to renew a ticket.

    In this integration sample, a credential is a user ID/password pair that is stored in the directory server. Therefore, you can use the ObjectGrid built-in implementations for these two interfaces that handle the user ID/password pair:


    The UserPasswordCredential class contains two string attributes: one for user ID, and the other for password. The UserPasswordCredentialGenerator class simply creates a pre-set UserPasswordCredential object (see Resources).

  • Authenticator

    Access Manager provides a login module, com.tivoli.mts.PDLoginModule, to support JAAS authentication. This login model class requires that the calling application provides:

    • A principal name, specified as either a short name or an X.500 name (DN).
    • A password.

    The com.tivoli.mts.PDLoginModule module authenticates the principal and returns the Access Manager credential. It expects the calling application to provide this information:

    • user ID, through a
    • password, through a

    When the Access Manager credential is successfully retrieved, the login module creates a Subject object and a PDPrincipal object. A simple callback handler class,, was developed for this example to pass the user password pair, to the PDLoginModule for authentication. The sample code is packaged in the download file included with this article.

    Listing 1 shows the authenticate method in the Authenticator implementation class. You will see that it utilizes the JAAS authentication service to login to Access Manager using the configured login name.

    Listing 1. TAMAuthenticator.authenticate(Credential) method
    subject = (Subject) 
    AccessController.doPrivileged(new PrivilegedExceptionAction() {
        public Object run() throws InvalidCredentialException, 
         ExpiredCredentialException {
            UserPasswordCredential cred = 
              (UserPasswordCredential) credential;
            LoginContext lc = null;
            try {
                lc = new LoginContext(loginName, 
                 new UserPasswordCallbackHandlerImpl(cred
    	.getUserName(), cred.getPassword().toCharArray()));
                Subject s = lc.getSubject();
                System.out.println("The authenticated subject is " + s);
                return s;
            } catch (LoginException le) {
                throw new InvalidCredentialException(le);
            } catch (IllegalArgumentException ile) {
                throw new InvalidCredentialException(ile);
  • ObjectGridAuthorization

    Once the client is authenticated, a Subject object is returned from the server. This Subject can be used to authorize client accesses. Since ObjectGrid supports JAAS authorization out-of-the-box, you can define the JAAS authorization policies in a Java policy file or JAAS authorization policy file. A typical policy looks like this:

    Listing 2. A JAAS authorization policy
    grant codebase 
    principal com.tivoli.pd.jazn.PDPrincipal "manager1" {

    This policy gives the user manager1 read, write, and insert permissions to the Balance map of the Accounting ObjectGrid.

    JAAS authorization policies are configured in a plain text file, which makes them a little cumbersome to manage. For this example, use the Access Manager access control list (ACL) to manage the ObjectGrid authorization policies.

    To use the Access Manager Authorization server to authorize ObjectGrid client access, you need to implement the ObjectGridAuthorization plug-in to do the custom ObjectGrid custom authorization. A plug-in implementation class was created for this purpose: Listing 3 shows the code that illustrates how the map permissions are checked against the Subject object.

    Listing 3. TAMOGAuthorization. checkMapPermission(Subject, Permission) method code sample
    // The permission.getName() is the [OBJECTGRID_NAME].[MAP_NAME].
    // We convert it to the ACL object bt prefixing "/OGTAMSample"
    final PDPermission pdPerm = 
      new PDPermission(resourcePath + permission.getName(), 
    	new String(pdPermissionStr));
    Set principals = subject.getPrincipals();
    Iterator iter = principals.iterator();
    while (iter.hasNext()) {
        try {
            PDPrincipal principal = (PDPrincipal);
            if (principal.implies(pdPerm)) {
                return true;
        } catch (ClassCastException cce) {
    return false;

    Listing 3 shows that you construct a PDPermission object first, which represents the desired permission for the ObjectGrid operation, then iterate the principal set in the Subject object. If it is a PDPrinciplal object, then you call the implies method to check whether it has the desired permission.

Run the sample application

When all the programs are in place, you can run the sample included with this article to see the ObjectGrid and Access Manager integration work. The instructions below will help you set up your environment and run the sample.

  1. Set up Access Manager

    First, you need to install and set up Access Manager. Use Access Manager V6.0 or later. Detailed installation and setup instructions for Access Manager are available in Resources, but here is a high level list of the steps you will need to perform:

    1. Install Access Manager Directory Server.
    2. Configure Access Manager Directory Server.
    3. Install Access Manager Policy Server.
    4. Install Access Manager Authorization Server.
    5. Install Access Manager Runtime for Java system.
    6. Start the Access Manager Directory Server.
    7. Start the Access Manager policy server.
    8. Start the Access Manager authorization server.
  2. Configure Access Manager Runtime for Java to a particular environment

    You need to configure the proper Tivoli Access Manager Runtime for Java component JRE on your system by using the pdjrtecfg command. This automatically makes the Tivoli Access Manager classes and methods available to the JRE. Choose the JRE you want to be configured, and run this command:

    "c:\Program Files\Tivoli\Policy Director\sbin\pdjrtecfg.exe" -action config -host
    <policy_server_host> -port <policy_server_port> -java_home c:\java142\jre


    • <policy_server_host> is the Access Manager policy server host name, for example: localhost.
    • <policy_server_port> is the Access Manager policy server port number, for example: 7135.

    You will use this configured JRE to access the Access Manager runtime.

  3. Configure a Java application in the secure domain

    Java applications that use Access Manager security must be configured into a Tivoli Access Manager secure domain. Access Manager provides a utility class called com.tivoli.pd.jcfg.SvrSslCfg that can be used to accomplish the necessary configuration task. Use this command to configure a Java application:

    java -classpath PD.jar com.tivoli.pd.jcfg.SvrSslCfg -action config -admin_id 
    <administrator_id> -admin_pwd <administrator_password> -appsvr_id OGTAM 
    -appsvr_pwd passw0rd -host <host> -mode local -port 999 -policysvr <policy_server> 
    -authzsvr <authz_server> -cfg_file <configuration_file> -key_file <keystore_file>
    -cfg_action create


    • <administrator_id> is the administrator ID; the default value is: sec_master.
    • <administrator_password> is the administrator password; the default value is: secpw.
    • <policy_server> is the Access Manager policy server address, for example: localhost:7135:1.
    • <authz_server> is the Access Manager authorization server address, for example: localhost:7136:1.
    • <configuration_file> is the name of the configuration file.
    • <keystore_file> is the name of the key store file.
    • <host> is the host of the application server. The default value is localhost.
    After the successful configuration of a Tivoli Access Manager Java application server, the application is permitted to make authenticated use of Tivoli Access Manager services.
  4. Add users and ACL

    Create some test objects in Access Manager, such as users, groups, and protected resources, and then add an Access Control List policy. An ACL policy is the set of rules (permissions) that specifies the conditions required to perform certain operations on that resource. An ACL policy controls what operations can be performed on the resource, and who can perform these operations. For this sample, the operations are the ObjectGrid map permissions, and the resource is the ObjectGrid map name.

    Start the pdadmin command line (called the Administration command prompt on the Windows® Start menu). Run the script in Listing 4 (you can copy and paste) after you have signed in as sec_master (password is passw0rd).

    Listing 4. Add user and ACL PDAdmin script
    // Create two groups employees and managers.
    group create employees "cn=employees,dc=ibm,dc=com" 
    employees employees
    group create managers  "cn=managers,dc=ibm,dc=com"  
    managers  managers
    // Create user empoyee1, belonging to group employees
    // You need to have the dc=ibm,dc=com set up in the LDAP server. 
    user create employee1 uid=employee1,ou=people,dc=ibm,dc=com 
    employee1 employee1 passw0rd employees
    user modify employee1 account-valid yes
    // Create user manager1, belonging to group managers
    user create manager1  uid=manager1,ou=people,dc=ibm,
    dc=com manager1 manager1 passw0rd managers
    user modify manager1  account-valid yes
    // Create an object /OGTAMSample/Accounting.Balance which 
    // represents the Map Balance of ObjectGrid Accounting 
    objectspace create /OGTAMSample "Protected objectspace 
     for ObjectGrid TAM integration
    	sample" 0
    object create /OGTAMSample/Accounting.Balance 
     "ObjectGrid Accounting Map Balance access
    	object" 0
    // create a "w" action to represent the ObjectGrid 
    // map write permission
    action create w write OG_Authzn
    // create an "i" action to represent the ObjectGrid map insert permission
    action create i insert OG_Authzn
    // create a "n" action to represent the ObjectGrid map invalidate permission
    action create n invalidate OG_Authzn
    // We use existing r action for ObjectGrid map read permission
    // We use existing d action for ObjectGrid map remove permission
    // Create an access control list
    acl create Balance_acl
    acl modify Balance_acl set description "ACL for ObjectGrid 
     accounting Map Balance" 
    // Grant r, w, i, d, n actions to user manager1
    acl modify Balance_acl set user manager1 Trwidn
    // Grant only r and i actions to user employee1
    acl modify Balance_acl set user employee1 Tri
    // Attach the access control list to object
    acl attach /OGTamSample/Accounting.Balance Balance_acl

    After running this script, you have successfully created users and defined the permissions a user can access in an ObjectGrid map. The script set user manager1's action to "Trwidn," which means that user manager1 has read, write, insert, remove, and invalidate permissions to the Balance map. User employee1's action is set to "Tri," which means that employee1 only has read and insert permissions to the Balance map.

  5. Install ObjectGrid

    You will need a J2SE ObjectGrid installation to run the sample. If you do not have ObjectGrid installed, see Resources to get a trial version. (Be sure to use WebSphere Extended Deployment Data Grid V6.1 with Interim Fix PK52322, or a later version, and install the software in the [OBJECTGRID_HOME] directory.)

  6. Run the sample

    In this sample, you will launch one secure ObjectGrid catalog server and one secure ObjectGrid container server You will then execute a client program to access the data stored in the ObjectGrid container server. To enable ObjectGrid authentication, you need to enable the ObjectGrid client ad server security:

    1. Unzip the download file, included with this article, into the [OBJECTGRID_HOME] directory. You will see these files in the tamsample directory:

      • tamSampleObjectgrid.xml: ObjectGrid configuration file; one Accounting ObjectGrid and one Balance map are defined in this configuration file.
      • objectGridDeployment.xml: ObjectGrid deployment policy file controls how ObjectGrid is deployed. For this sample, the simplest deployment policy is defined: one partition and no replica.
      • client.props: ObjectGrid client security configuration file.
      • objectGridSecurity.xml: ObjectGrid cluster security configuration file.
      • server.props: ObjectGrid server-specific security configuration file.
      • tamsample.jar: JAR file that contains the integration plug-in implementation classes.
      • config.pd: JAAS configuration file.

      See the ObjectGrid security overview in Resources for more information about these properties files.

    2. Set JAVA_HOME to the JDK you have configured in step 2, using the appropriate command for Windows or UNIX®:
      For Windows:
      set JAVA_HOME=c:\java141\
      For UNIX:
      export JAVA_HOME=/java141/
    3. In the [OBJECTGRID_HOME]/bin directory, run the appropriate command to set up the ObjectGrid environment:
      For Windows:
      For UNIX:
    4. Start the catalog server in the[OBJECTGRID_HOME]/bin directory.

    5. Use one of the following sets of commands to create a startcatalog.bat/ script:
      For Windows:
      startOgServer.bat catalogServer -script startcatalog.bat 
      ../tamsample/objectGridSecurity.xml -serverProps 
      ../tamsample/server.props -jvmArgs 
      -classpath ../tamsample/tamsample.jar
      For UNIX:
      ./ catalogServer -script 
      ../tamsample/objectGridSecurity.xml -serverProps 
      ../tamsample/server.props -jvmArgs 
      -classpath ../tamsample/tamsample.jar

      The JVM option sets the JAAS login configuration file. You can also set it in the file using login.config.url.1=file:${OBJECTGRID_HOME}/tamsample/config.pd.

    6. Start the catalog server:
      For Windows:
      For UNIX:
      . &
    7. Start the container server in the [OBJECTGRID_HOME]/bin directory. Use the following command to create a startcontainer.bat/ script:
      For Windows:
      startOgServer.bat c0 -script startcontainer.bat -objectGridFile 
      ../tamsample/tamSampleObjectgrid.xml -deploymentPolicyFile 
      ../tamsample/objectGridDeployment.xml -catalogServiceEndpoints 
      localhost:2809 -serverProps ../tamsample/server.props -jvmArgs
      For UNIX:
      ./ c0 -script -objectGridFile 
      ../xml/CSSelectorTestOG.xml -deploymentPolicyFile ../ 
      ../tamsample/objectGridDeployment.xml -catalogServiceEndpoints 
      localhost:2809 -serverProps ../tamsample/server.props  -jvmArgs
    8. Run this command to start the container server:
      For Windows:
      For UNIX:
      . &
    9. Launch the client in the [OBJECTGRID_HOME] directory
      For Windows:
      java -cp lib/objectgrid.jar;tamsample/tamsample.jar;lib/mx4j.jar 
      localhost:2809 <user_name> <password>
      For UNIX:
      java -cp lib/objectgrid.jar:tamsample/tamsample.jar:lib/mx4j.jar 
      localhost:2809 <user_name> <password>

      The <user_name> and <password> values are the user ID and password created in the previous step using pdadmin. If you use JDK 5.0 or above, you do not need put mx4j.jar in the classpath.

    10. Use manager1 as the user to connect to the server. Using Windows as an example, the command will be:
      java -cp lib/objectgrid.jar;tamsample/tamsample.jar;lib/mx4j.jar 
      localhost:2809 manager1 passw0rd

      You will see the output similar to the following in the command window:

      Insert user1 ...
      Get user1 ...
      user 1 has balance 10000.0
      Remove user1 ...
    11. Now, use employee1 as the user to connect to the server. Using Windows as an example, the command will be:
      java -cp lib/objectgrid.jar;tamsample/tamsample.jar;lib/mx4j.jar 
      localhost:2809 employee1 passw0rd

      You will see this output:

      Insert user1 ...
      Get user1 ...
      user 1 has balance 10000.0
      Remove user1 ...
      Exception in thread "P=654937:O=0:CT" 
      rolling back transaction, see caused by exception
      ... ...
      Caused by: The following 
      access to the map Accounting.Balance is not granted: com. Accounting.Balance 
      remove at c
      ... ...

      The root exception message is: 
      The following access to the map Accounting.Balance 
      is not granted:
      .security.MapPermission Accounting.Balance 

      This message indicates that user employee1 does not have permission to remove data in the Accounting ObjectGrid and Balance map.


This article described the basic flow of ObjectGrid authentication and authorization, then illustrated how ObjectGrid can utilize Tivoli Access Manager for authentication and authorization with a simple example. Integrating ObjectGrid with Tivoli Access Manager provides a secure enterprise distributed cache solution. Visit the ObjectGrid wiki for more details about ObjectGrid and ObjectGrid security.



developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into WebSphere on developerWorks

ArticleTitle=Integrate Tivoli Access Manager with ObjectGrid to authenticate and authorize your distributed clients