Introduction

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.

Back to top

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.

• Authentication flow
  1. The authentication flow starts with an ObjectGrid client getting the credential which represents itself. This is done by the plug-in com.ibm.websphere.objectgrid.security.plugins.CredentialGenerator.
  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 com.ibm.websphere.objectgrid.security.MapPermission 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 com.ibm.websphere.objectgrid.security.plugins.ObjectGridAuthorization.

  7. The server runtime sends the Subject object and the required permission to the ObjectGrid authorization plug-in.
  8. 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.
  9. 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.

Back to top

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:

  • com.ibm.websphere.objectgrid.security.plugins.builtins.UserPasswordCredentialGenerator
  • com.ibm.websphere.objectgrid.security.plugins.builtins.UserPasswordCredential

  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 javax.security.auth.callback.NameCallback
  • password, through a javax.security.auth.callback.PasswordCallback.

  When the Access Manager credential is successfully retrieved, the login module creates a Subject object and a PDPrincipal object. A simple callback handler class, com.ibm.websphere.samples.objectgrid.security.tam.UserPasswordCallbackImpl, 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 com.ibm.websphere.samples.objectgrid.security.tam.TAMAuthenticator 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())); lc.login(); 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 "http://www.ibm.com/com/ibm/ws/objectgrid/security/PrivilegedAction" principal com.tivoli.pd.jazn.PDPrincipal "manager1" { permission com.ibm.websphere.objectgrid.security.MapPermission "Accounting.Balance", "read,write,insert"; };

  
  

  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: com.ibm.websphere.samples.objectgrid.security.tam.TAMOGAuthorization. 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) iter.next(); 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.

Back to top

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

   
   

   where:

   • <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

   
   

   where:

   • <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 /OGTamSample/Accounting.Balance 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 tamsample.zip 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:
      

      setupCmdLine.bat

      
      
      
      For UNIX:
      

      ./setupCmdLine.s

      
      

   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/startcatalog.sh script:
      
      For Windows:
      

      startOgServer.bat catalogServer -script startcatalog.bat -clusterSecurityFile ../tamsample/objectGridSecurity.xml -serverProps ../tamsample/server.props -jvmArgs -classpath ../tamsample/tamsample.jar -Djava.security.auth.login.config= ../tamsample/config.pd

      
      
      
      For UNIX:
      

      ./startOgServer.sh catalogServer -script startcatalog.sh -clusterSecurityFile ../tamsample/objectGridSecurity.xml -serverProps ../tamsample/server.props -jvmArgs -classpath ../tamsample/tamsample.jar -Djava.security.auth.login.config= ../tamsample/config.pd

      
      

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

   6. Start the catalog server:
      
      For Windows:
      

      startcatalog.bat

      
      
      
      For UNIX:
      

      . startcatalog.sh &

      
      
   7. Start the container server in the [OBJECTGRID_HOME]/bin directory. Use the following command to create a startcontainer.bat/startcontainer.sh 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 -Djava.security.auth.login.config=../tamsample/config.pd

      
      
      
      For UNIX:
      

      ./startOgServer.sh c0 -script startcontainer.sh -objectGridFile ../xml/CSSelectorTestOG.xml -deploymentPolicyFile ../ ../tamsample/objectGridDeployment.xml -catalogServiceEndpoints localhost:2809 -serverProps ../tamsample/server.props -jvmArgs -Djava.security.auth.login.config=../tamsample/config.pd

      
      
   8. Run this command to start the container server:
      
      For Windows:
      

      startcontainer.bat

      
      
      
      For UNIX:
      

      . startcontainer.sh &

      
      
   9. Launch the client in the [OBJECTGRID_HOME] directory
      
      For Windows:
      

      java -cp lib/objectgrid.jar;tamsample/tamsample.jar;lib/mx4j.jar com.ibm.websphere.samples.objectgrid.security.tam.TAMOGClient localhost:2809 <user_name> <password>

      
      
      
      For UNIX:
      

      java -cp lib/objectgrid.jar:tamsample/tamsample.jar:lib/mx4j.jar com.ibm.websphere.samples.objectgrid.security.tam.TAMOGClient 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 com.ibm.websphere.samples.objectgrid.security.tam.TAMOGClient 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 com.ibm.websphere.samples.objectgrid.security.tam.TAMOGClient 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" com.ibm.websphere.objectgrid.TransactionException: rolling back transaction, see caused by exception .java:65) ... ... Caused by: java.security.AccessControlException: The following access to the map Accounting.Balance is not granted: com. ibm.websphere.objectgrid.security.MapPermission Accounting.Balance remove at c om.ibm.ws.objectgrid.security.MapAuthorizer.getAccessControlException (MapAuthorizer.java:139) ... ...

       
       

       The root exception message is:

       java.security.AccessControlException: The following access to the map Accounting.Balance is not granted: com.ibm.websphere.objectgrid .security.MapPermission Accounting.Balance remove.

       
       

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

Back to top

Conclusion

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.

Resources

• ObjectGrid documentation wiki
  
  
• IBM Tivoli Access Manager for e-business product information
  
  
• IBM Tivoli Access Manager for e-business Information Center
  
  
• Java Authentication and Authorization Service (JAAS) Reference Guide
  
  
• IBM Tivoli Access Manager Authorization Java Classes Developer Reference V6.0
  
  
• ObjectGrid security overview
  
  
• ObjectGrid security JavaDoc
  
  
• Setting up IBM Tivoli Directory Server
  
  
• Setting up a policy server
  
  
• Setting up an authorization server
  
  
• Highly scalable grid-style computing and data processing with the ObjectGrid component of WebSphere Extended Deployment
  
  
• IBM developerWorks WebSphere Extended Deployment resources
  
  
• IBM developerWorks WebSphere
  
  

About the author

Rate this article

Comments

Back to top

Table of contents

• Introduction
• Overview of ObjectGrid security
• Integrating Tivoli Access Manager
• Run the sample application
• Conclusion
• Resources
• About the author
• Comments

Next steps from IBM

• Try: Tivoli Access Manager Enterprise Single Sign-on
• Demo: Demo: Tivoli Access Manager for Enterprise Single Sign-On solution overview
• Briefing: Introduction to Tivoli service management environment
• Buy: Tivoli Access Manager Enterprise Single Sign-on

Dig deeper into WebSphere on developerWorks

IBM SmartCloud trial. No charge.

Unleash the power of hybrid cloud computing today!

---

Public and private solutions in one trial.

Special offers