Subscribe to WebSphere: eMailAlertsEmail Alerts newslettersWeekly Newsletters
Get WebSphere: homepageHomepage mobileMobile rssRSS facebookFacebook twitterTwitter linkedinLinkedIn

IBM WebSphere software products Authors: Yeshim Deniz, hyper filter, Timothée Bensimon, XebiaLabs Blog, Javier Paniza

Related Topics: Java EE Journal, WebSphere

J2EE Journal: Article

Understanding Tivoli Access Manager for WebSphere Application Server

Understanding Tivoli Access Manager for WebSphere Application Server

J2EE Security provides a mechanism called EJBRoles that can be used to provide security for applications running in J2EE-compliant application servers, including WebSphere Application Server. Use of EJBRoles requires that users, or groups of users, be mapped to EJBRoles so that WebSphere can perform security checks when applications are running. It is common to find several WebSphere environments in a large organization. Management of EJBRoles across these environments can become complex and expensive.

IBM's Tivoli Access Manager provides a software component that can be integrated with WebSphere Application Server to provide centralized management of EJBRoles. When WebSphere is configured with this component it relies on Tivoli to determine if access to an EJBRole is allowed. This article describes how Tivoli Access Manager (TAM) for WebSphere Application Server works with WebSphere on distributed platforms. For the purposes of this article, I used WebSphere Application Server v4 with Fix Pack 3, and Tivoli Access Manager v4.1 with no fix packs.

IBM provides a range of solutions within the Tivoli Access Manager family that build to form a comprehensive security management and enforcement environment that extends from Web applications to messaging applications and the operating system platforms on which they run. IBM's WebSphere Application Server (WAS) is a high-performance and scalable transaction engine for dynamic e-business applications. Using WAS coupled with Tivoli Access Manager, customers can finally build tightly integrated, centralized identity management solutions that can protect their J2EE, Web, and legacy resources.

More on EJBRoles and J2EE Security
Before describing how TAM for WAS works, it is worth spending a few moments to explain EJBRoles in a little more detail.

An EJBRole typically identifies a logical resource of some sort. Using a bank as an example, different types of employees, such as tellers and managers, have different roles. For instance, a manager may be authorized to withdraw larger amounts of money than a teller. In years past, an application would perhaps hard-code some test to determine if the user running the application was a teller or a manager, or instead look up the user in a table.

EJBRoles allow a Java programmer to use a programmatic or declarative approach to security. For example, a programmer could define two EJBRoles, Teller and Manager, and create two different methods in an EJB, called handleLargeAmounts and handleSmallAmounts.

Declarative Security
The developer would specify in the deployment descriptor that users have to be authorized to use the "Manager" EJBRole in order to invoke the "handleLargeAmounts" method, and users have to be authorized to use the "Teller" EJBRole to invoke the "handleSmallAmounts" method. This approach is called declarative security. A servlet can also be protected with an EJBRole, meaning that before an authenticated user can invoke a servlet, the user must be authorized to the EJBRole that protects the servlet.

When a method that has been marked with an EJBRole is invoked, it is up to WebSphere to determine if the user running the application is authorized to that EJBRole.

Programmatic Security
In the programmatic approach, some sort of logic test in the code is used to determine if the user running the application is authorized to run a section of the code. This can be done by using the statements isUserInRole (for use in a servlet) and isCallerInRole (for use in an EJB).

When these statements are executed, it is up to WebSphere to check if the authenticated user is authorized to a particular EJBRole. WebSphere returns a value of true or false to the application to indicate the result of the authorization check. To enable this programmatic approach, role names need to be mapped to EJBRoles in the deployment descriptor.

Without Tivoli Access Manager
When you are running WebSphere alone, it is up to WebSphere to handle the process of checking if an authenticated user is authorized to an EJBRole. WebSphere does this based on which users and groups have been assigned to the EJBRole. Typically, during deployment of an application WebSphere will detect that there are EJBRoles in the deployment descriptor. It will then give you an opportunity to find the users and groups that are defined, and map them to EJBRoles. It is also possible to specify users in the deployment descriptor at application assembly time.

If you are mapping users and/or groups to EJBRoles during deployment of the application, then you are faced with having to do this each time you deploy a new version of the application. To deploy a new version of the application, you have to remove the current version, which also removes the existing mappings.

With Tivoli Access Manager
With Tivoli Access Manager configured into WebSphere, the process of checking if a user is authorized to an EJBRole is delegated to TAM. In TAM, objects are defined that represent the EJBRoles. Users and/or groups are then assigned to access control lists (ACLs), which are then attached to EJBRoles objects.

When WebSphere needs to check authorization, it calls TAM, which checks the ACLs and objects to determine if the user has access to the EJBRole.

The Deployment Descriptor Always Wins!
The key point with regard to the use of EJBRoles in WebSphere is that they have an effect only if your servlet/ EJB is running as authenticated in WebSphere. The only way a servlet can run as authenticated in WebSphere is if it has been marked as such in the application's deployment descriptor.

In an EAR file containing servlets and EJBs, a web.xml file acts as the deployment descriptor for the servlets, and an ejb-jar.xml file acts as the deployment descriptor for the EJBs. These XML files indicate which EJBRoles are used and whether a servlet runs as authenticated. Listing 1 is a snippet from a web.xml file showing a security constraint for a servlet. The listing shows that for any URL containing "secure/", "BASIC" authentication will be required, and the authenticated user will have to be granted access to the "Employee" EJBRole. Listing 2 is an example of XML from an ejb-jar.xml file showing how a method of an EJB is being protected with an EJBRole. The example shows that the "runAsRoleCEO" method of the "EJBSample" EJB requires the user to be authorized to the "CEO" EJBRole in order to invoke it.

Performing some sort of authentication operation outside of WebSphere, such as in WebSEAL or the TAM plug-in for WebSphere Edge Server, has no effect on WebSphere's determination as to whether a servlet is to run as authenticated.

When WebSphere receives a request to run a servlet, it will check the deployment descriptor to determine if a security constraint is configured. If so, then WebSphere will try to determine if authentication information is present in the HTTP object it has received, and if not, it will send back a response to obtain it.

z/OS WebSphere and J2EE Security Handbook, an IBM Redbook, offers detailed information about how to set security constraints in the deployment descriptors. Although this redbook focuses on WebSphere Application Server on z/OS, the concepts it describes for setting security constraints and J2EE security are the same regardless of what platform WebSphere is running on.

Installation of Tivoli Access Manager
Installation of TAM is described in IBM Tivoli Access Manager for WebSphere Application Server User's Guide (SC32-1136). Follow the instructions carefully! Be sure to use the manual corresponding to the version of the product you are using. Tivoli manuals can be viewed online at: http://publib.boulder.ibm.com/tividd/td/tdmktlist.html.

Defining EJBRoles in TAM
TAM supplies a tool called migrateEAR, which takes an application EAR file as input; for each EJBRole defined in the EAR file it defines an object in TAM, and creates an ACL. However, this should be seen as very much a one-off process. When a new version of the application EAR file is delivered, you probably do not want to use the migrateEAR tool. For example, if the application EAR file now no longer uses a particular EJBRole, that EJBRole is no longer defined in the deployment descriptor and migrateEAR will not detect this. The tool will not remove from TAM an EJBRole that is no longer used.

In a situation in which an organization is planning to use EJBRoles in its applications, a process must be developed through which the application area creating EJBRoles passes on this information to an area responsible for managing TAM resources. The organization would also need to identify which users/groups are to have access to the EJBRoles.

Tivoli Access Manager Objects
In Tivoli Access Manager, objects that represent an EJBRole are all anchored off what is called the root object "/", and must start with:


The next part of the object name for an EJBRole object is the EJBRole name itself, for example the object for an EJBRole called "Employee" would be:


When TAM is invoked by WebSphere, the object it constructs to be checked follows this format:


When TAM receives this as the object to check authorization against, it searches from the start of the object tree at "/", looking for the most exact match.

You could simply define an object of this form:


This would be sufficient for a match. Tivoli Access Manager searches down the object tree until it finds the object that most closely matches the received object. When TAM finds this object, it then checks the ACL being "enforced" for this object. The ACL will specify the users or groups that have permission to access this object.

Whether or not to use an in the TAM object depends on whether the EJBRole is to be treated as a common EJBRole across the applications it is defined in. For example, a bank may have two applications, AppA and AppB, deployed into WebSphere, with the "Teller" EJBRole defined in both. In such a situation it would make sense to define an object called /WebAppServer/deployed Resources/Teller rather than define two objects, such as /WebAppServer/deployedResources/ Teller/AppA and /WebAppServer/deployedResources/Teller/ AppB. Using the former approach, the ACLs would each be attached to only one object, as opposed to two.

However, consider another company that is running two applications that have different users in the company, but both define the same EJBRole, "Employee". In order to ensure that only the correct sets of users have access to their respective EJBRoles, you would define two objects:


ACLs can be called anything. The migrateEAR tool creates ACLs with names like _WebAppServer_deployed Resources___ACL. However, there is no need for the ACLs to be of this format. For example, an ACL could be called WAS_EJBRole_Employee.

The WebServer Action Group
When configuring Tivoli Access Manager, part of the process is to issue these two TAM commands:

action group create WebAppServer


action create i invoke invoke WebAppServer

When giving a group or user access to an ACL, use this type of command:

acl modify _WebAppServer_deployedResources_AdminRole_admin
_ACL set group
pdwas-admin T [WebAppServer ]i

The T[WebAppServer]i command breaks down into:

T Traverse bit
WebAppServer Action group name
i A permission

The Traverse Bit
When WebSphere invokes Tivoli Access Manager to check if a user has access to an EJBRole, TAM constructs an object and then checks for authorization. For example, to determine if a user has access to the object/WebAppServer/deployed Resources/EJB Role, the authorization engine must traverse from the root object "/" down to the "/WebAppServer/deployedResources/EJBRole" object. If at any point the user isn't allowed to traverse beyond a particular object, then regardless of any other permission on subsequent objects, the user is not allowed access to the object.

The traverse bit part of the permission in the ACL command permits this traversing of the object tree.

The WebAppServer Action Group
The "[WebAppServer]" part of the permission is the action group. It is a value used to denote that the permissions granted by the ACL are for use only by Tivoli Access Manager. When TAM checks authorization it makes its calls using the WebAppServer action group.

It is possible to define any number of action groups to TAM. For example, you could define an action group called "MyApplication". You then could set up two ACLs and control access to WebSphere and MyApplication resources like this:

acl modify _WebAppServer_deployedResources_Employee_ACL
set user z12345 T[WebAppServer]i
acl modify _MyApplication_Resources_Widgets_ACL
set user z123456 T[MyApplication]i

Both ACLs give the same user access to the "i" permission, but map it to two different action groups. The permissions after the action group (the characters that come after the last "]") are relevant only for those applications using that action.

Other applications could call TAM to check authorization, and use the "MyApplication" identifier. This approach allows TAM to support the setting up of ACLs to control access for many different applications.

The "i" Permission
The "i" permission is a setting defined in the ACL. Typically, permissions in the ACL correspond to an action. For example, ACLs used in conjunction with the TAM WebSEAL or TAM Edge plug-ins have permissions that correspond to HTTP GET or POST requests.

When TAM does its authorization check, it is asked by WebSphere to check if a user has access to an EJBRole. TAM checks if the user has permission for the "i" action for the WebAppServer action group.

acl modify
set user citizen T[WebAppServer]i

This Tivoli command grants access to the "Employee" EJBRole to the userid "citizen", because the ACL has the WebAppServer action group defined, and has also been assigned the "i" permission.

Application Name and the TAM Object
Previously I discussed how the objects in Tivoli that represent EJBRoles can contain the application name. There is another important consideration here to do with the name that an application is called when it is deployed into WebSphere.

Figure 1 is a view of the WebSphere administration console showing an application, "ITSO", which has been deployed. When this application requires an access check on an EJBRole to be performed by WebSphere, TAM will construct object names that contain the value "ITSO" for checking authorization.

Now suppose we have a new version of the application, and when we deploy it we decide to call it ITSOV2, as shown in Figure 2.

When the ITSO application requires WebSphere to perform an EJBRole authorization check via Tivoli Access Manager, the object name will contain the appName "ITSOV2".

If you have defined TAM objects with an application name of ITSO, then those objects will no longer match the new objects being checked for by TAM. Therefore, if you are going to use the application name as part of the TAM objects, the application - regardless of version - must always be deployed into WebSphere with the same name. If you are not going to use the application name as part of the TAM objects, then you can call the application anything when you deploy it into WebSphere.

Note: During testing to confirm the above, I noticed that after deploying the application again with a new name TAM was still testing for objects using the old application name. After restarting the application server, TAM started using objects with the new application name.

Tivoli Access Manager Properties
Chapter 5 of the IBM Tivoli Access Manager for WebSphere Application Server User's Guide describes how TAM runtime properties can be adjusted by modifying the PDWAS.properties file. Figure 3 shows where this file is located on a Windows system.

On an AIX system it is located in the directory where the Tivoli Access Manager software is installed. Properties that can be adjusted are:
1.  Limit simultaneous connections
2.  Enable static role caching
3.  Define static roles
4.  Configure dynamic role caching
5.  Specify logging mechanism type
6.  Specify logging level
7.  Specify root object space name
8.  Specify document type definition directory

Incorrect Authorization
If, after setting up Tivoli Access Manager, you find that authorization decisions are not what you had expected, you will need to find out what object and userid TAM is using to check authorization.

Tracing of TAM can be enabled by setting values in the PDWAS.properties file, as mentioned previously. However, that approach requires restarting WebSphere to pick up the change in the PDWAS.properties. An alternative is to use the WebSphere admin facility to set and capture a trace.

In the WebSphere admin facility, select the application server you want to trace activity in, and then select the Trace service. Click on "trace specification" and you will get a display similar to that shown in Figure 4.

TAM now shows up under the Components->com headings. Right-click on "PDWASAuthzManager" and select "All". Click OK, then OK on the Trace service panel, and finally the Apply button.

Run the servlet/EJBs, then go back into the Trace service and dump the trace to a file. You can then view the captured trace to determine which object and userid TAM used for the authorization check. The sample trace shown in Listing 3 shows that the object for which TAM is requesting authorization is:


The userid is "wasadmin" and the EJBRole is "Employee". You can then use this information to check what has been defined in TAM, for example:

  • Is the userid "wasadmin" defined?
  • What object maps to the resource being checked by TAM?
  • Does the userid have access to that object via an ACL?

    The Tivoli Access Manager component provides centralized management of EJBRole security in WebSphere. Understanding how EJBRoles are mapped by objects in Tivoli Access Manager is the key to how you will set up Tivoli to manage EJBRoles.


  • Security Management: www.ibm.com/software/tivoli/solutions/security
  • WebSphere software platform: www.ibm.com/software/websphere
  • More Stories By Edward McCarthy

    Edward McCarthy is an e-business specialist for IBM Global Services Australia. For the past three years he has provided technical support and solution design for WebSphere and MQSeries across all platforms. Prior to that, he was a CICS systems programmer for nine years. He has contributed to a number of IBM Redbooks, including z/OS WebSphere and J2EE Security Handbook (SG24-6846) and IBM WebSphere Everyplace Server Service Provider and Enable Offerings: Enterprise Wireless Applications (SG246519).

    Comments (0)

    Share your thoughts on this story.

    Add your comment
    You must be signed in to add a comment. Sign-in | Register

    In accordance with our Comment Policy, we encourage comments that are on topic, relevant and to-the-point. We will remove comments that include profanity, personal attacks, racial slurs, threats of violence, or other inappropriate material that violates our Terms and Conditions, and will block users who make repeated violations. We ask all readers to expect diversity of opinion and to treat one another with dignity and respect.