WebSphere

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

Implementing WebSphere Security Through LDAP

Implementing WebSphere Security Through LDAP

Lightweight Directory Authentication Protocol (LDAP) is often promoted as a means to leverage an organizational directory as a principal registry for WebSphere authentication and authorization. Advantages include the capability to configure single sign-on across application servers, enabling additional organizational applications, centralized user administration, multimastered replication across authentication sites, and flexible, extensible data formats - not to mention that LDAP is a vendor-neutral protocol and API backed by IETF. This begs the question of how to implement WebSphere security through LDAP.

This two-part series presents a simplified example of how to configure WebSphere Application Server version 5.0 to use IBM Directory Server v5.1 as its user registry for J2EE application user authentication and role-based authorization. This registry enables the ability to configure single sign-on capability across applications residing on multiple WebSphere Application Servers and Lotus Domino servers. By the end of the second part of this article, you will understand how to create an LDAP user registry from scratch, and will have gained an understanding of how to incorporate an existing LDAP user directory as the user registry for securing WebSphere J2EE applications.

Required Software Components
WebSphere Studio Application Developer, version 5.0 (hereafter called WebSphere Studio), will be used to create and host the example using the embedded WebSphere Test Environment v5 as the target application server.

IBM Directory Server v5.1 will host the LDAP directory service. This directory server, available as a free download from IBM (www-3.ibm.com/software/network/directory/server/download), includes a copy of IBM DB2 UCB v8, used to contain the underlying directory information.

The example was written for a Microsoft Windows NT/2000/XP platform, but the principles used apply to any supported platform. The directory server and the application server are often installed on separate machines or even separate platforms, if available.

Create Directory Information
You are starting from scratch, so you first need to design a directory information tree (DIT) and then create an import file that contains entries that conform to it.

DIT Design
The J2EE application users will authenticate themselves through WebSphere Lightweight Third Party Authentication (LTPA). A security token granted by LTPA can propagate to other WebSphere and Domino servers that participate in single sign-on. The user registry can be an LDAP directory or a custom implementation. LDAP has the advantage of being an IETF (Internet Engineering Task Force) standard protocol. Its implementations can be distributed as multimaster replicated directories. These may support additional clients such as organizational white pages applications or service locators.

The example involves LTPA configured to use a scratch-built DIT for its user registry. An LDAP directory stores information in nodes. In this directory, each user has a node that stores information unique to her or him. Each group has a node that maintains a list of unique members. You will be able to set optional attribute values at will to track an organization's personnel information for use by other applications.

WebSphere LPTA uses LDAP to map authorization roles to users and groups. Therefore the DIT needs to contain a set of user entries. In addition it needs a set of groups such that each group entry refers to a subset of users that belong to that group.

The literature generally agrees that a shallow directory hierarchy is less sensitive to organizational changes than a deep hierarchy. The sample organization name is Rogers60, located in the United States. The J2EE application will be constrained by user and admin roles, but it is easy to add more application roles later as the need arises. The example subtree of the LDAP hierarchy is defined by a suffix so that the users and groups fall under that suffix (see Figure 1).

Each person node under the ou=people node contains the object classes person and ePerson. These object classes include optional attributes that can fulfill most anticipated personnel directory requirements. The ePerson object class defines the uid and userPassword attributes that WebSphere will use for authenticating a request having a supplied user ID and password.

Each ou=groups node contains the groupOfUniqueNames object class, which specifies a multivalued attribute named uniqueMember. A group entry will use the value list of this attribute to reference the distinguished name (DN) of each user in a given group. WebSphere will use this information to check group membership for a role mapped to a DIT group.

LDAP Interchange Format File
LDAP uses an import and export file format, called LDAP Interchange Format (LDIF), that is composed of name-value pairs that define and populate nodes in the DIT. The first line for a node entry must define its DN. The definitions of the node's object classes and attributes follow the DN. Each line starts with a nonblank, unless it continues the previous line. The definition of an entry ends with a blank line. A "#" begins a comment line. The LDIF format is easy to understand, as the example will illustrate.

Create an LDIF file to initially populate the directory for the example. A DIT resembles a file directory tree, so begin by creating higher-level nodes that contain lower-level nodes, and then create the contained nodes. The DIT root will be the directory suffix o=rogers60,c=us, which will be defined later using the IBM Directory Server Configuration Tool. Thus the LDIF file begins at the o=rogers60 node. Next, it defines the people and groups nodes. Finally, it populates the people and groups nodes with data nodes.

Use an editor such as VI or Notepad to create the text file named rogers60.ldif, shown in Listing 1. Double-check your work and then save the file in a work directory. We will import the LDIF file into the directory server later.

Notice that the final user node has a uid attribute set to "was". This defines the user account to be used by WebSphere when security is enabled. A sampling of optional attributes, such as telephoneNumber from objectClass ePerson, illustrates how this directory could be extended as a personnel directory. Option attribute values can be added at any time.

Notice that the userPassword attribute is not encrypted. The default access control defined for the userPassword attribute makes it invisible to queries by anonymous LDAP clients. The directory server stores it using imask encryption, meaning that the value is encrypted on the disk but sent in clear text on the network. WebSphere will search the directory as an authenticated privileged client, so the password will be received in clear text. An SSL connection will prevent snooping or undetected alteration of the data on the network.

IBM Directory Server v5.1
Insert the IBM Directory Server v5.1 CD-ROM into the CD drive in the target machine. Choose all options, including the GSKit, DB2, and WebSphere - Express. If you already have DB2 7.2 or DB2 8, the directory server will offer to use it. GSKit is needed for securing the directory with SSL. The WebSphere - Express Server hosts a Web-based directory administration Web application.

Define the Administrator Distinguished Name
After installation there is a forced reboot, followed by automatic invocation of the IBM Directory Server Configuration Tool. The administrative distinguished name is used to bind to the directory with administrative privileges. Set this DN by carrying out the following steps:
1. Click the Administrator DN tree node.
2. Ensure that the administrator DN is cn=root. This is a DN that has administrative privileges. Its user can see and update anything in the directory.
3. Set the password to secret.
4. Set the confirmation password to secret.
5. Click OK.

Configure a Database
Use the following steps to define the DB2 database container for the LDAP information:
1. Click the Configure Database tree node.
2. Name the database ldapdb2.
3. Supply user ID db2admin or your existing DB2 administrative user ID.
4. Enter the DB2 user password.
5. Create the database.

Create the LDAP Directory
The directory server has not yet been started. Use the IBM Directory Server Configuration Tool to set directory suffixes and import the LDIF file.

Set Directory Suffixes
The directory root DN o=rogers60,c=us refers to the relative tree root node in the DIT. Carry out the following steps to set the suffixes for the DIT:
1. Click the Manage Suffixes tree node.
2. Set the Suffix DN field to o=rogers60,c=us.
3. Press the Add button to add the suffix.
4. Press OK.

Import the LDIF File
The IBM Directory Server Configuration Tool can be used to import the LDIF file. An alternative would be to use the ldapadd command found in the bin directory of the server, but the sever would need to be running. Instead, carry out the following steps to use the configuration tool to import the LDIF file to populate your directory:
1. Click the Import LDIF data tree node.
2. Use the Browse button to set the Path and LDIF file name field to point to rogers60.ldif.
3. Ensure that Standard import is selected.
4. Press the Import button to carry out the operation.
5. The task messages should show each DN imported with no error.

Start the IBM Directory Server
The IBM Directory Server installs itself as a Windows service. On AIX or Linux it would install as a daemon. You can start the WebSphere - Express application server that accompanies the directory server and then use the served administration Web page to create a console page for the server. Then you would start the server from the console page. For brevity, use the following steps to start the server on Windows:
1. Open the Windows Control Panel from the Start menu.
2. Open Administrative Tools.
3. Open Services.
4. Find the row labeled IBM Directory Server v5.1.
5. Right-click it and choose Start.

Starting will take a minute or two.

Create a Sample Web Application
You need a sample application to lock down through roles. In the following sections you will configure a workspace for WebSphere Studio, create a simple JSP Model 1 application as a vehicle to demonstrate role-based authorization, and finally, configure an application server.

WebSphere Studio Workspace
You will need a new workspace to contain the application and the server configuration. Carry out the following steps on your development machine: 1. Create a directory named c:\workspace-LDAP-auth.
2. Drag and drop a shortcut to WebSphere Studio to the desktop using the right mouse button.
3. Choose Create Shortcuts Here from the pop-up menu.
4. Right-click the new shortcut and choose Rename to rename it to WSAD LDAP Auth.
5. Right-click the new shortcut and choose Properties from the pop-up menu.
6. Append a blank followed by -data C:\workspace-LDAP-auth to the Target field (see Figure 2). Don't forget the leading dash (-).
7. Press OK to create the shortcut.
8. Use the shortcut to start WebSphere Studio. Some time elapses as the new workspace is created.
9. WebSphere Studio opens in the J2EE perspective. Close the Welcome tab (read it first, if you wish).

Create an Enterprise Application Project
Next, create an enterprise application project that contains a Web application by following these steps:
1. Invoke main menu File -> New -> Enterprise Application Project. The Enterprise Application Project Creation wizard appears.
2. Keep the default Create J2EE 1.3 Enterprise Application Project option. Press Next->.
3. In the Enterprise application name field enter SecurityDemo.
4. Clear the options labeled Application Client Module and EJB Module.
5. The dialog should resemble that shown in Figure 3.
6. Press Finish to create the two projects. They appear in the J2EE Hierarchy view.

Implement the Web Project
The Web project will define a boilerplate JSP Model 1 implementation that acts as a secured "Hello World" demonstration. It will have a start page that invites the user to navigate to either an application page or an administration page. WebSphere will authenticate the user through basic authentication, although you could easily configure forms-based authentication later.

Roles determine if the user is an administrator who is allowed to navigate to the administration page. Once you see how it is done, you can carry the technique forward to actual applications.

Next, you will create the three JSP files that form the entire application.

User Page
Carry out these steps to create a page that represents the application user interface to tasks:
1. Open the Web Perspective to project SecurityDemoWeb in the J2EE Navigator view.
2. Right-click the Web Content folder. Choose New JSP File. The New JSP File wizard opens.
3. Name the file index.jsp and press Finish to create the page.
4. Use main menu Insert -> Paragraph -> Heading 1 to insert User Tasks.
5. Choose main menu Insert -> List -> Bulleted List.
6. Enter the follow bullet items: Task 1, Task2, Task3.
7. Click beneath the bullet list. Enter the following text: -> Home ->.
8. Double-click that text to select it. Choose Insert -> Link from the main menu. The Insert Link dialog will open.
9. Enter index.jsp in the URL field of the dialog. Press OK. The user.jsp file should resemble Figure 4.
10. Save the file and close it.

Administration Page
Carry out the following steps to clone user.jsp to create a representation of an administration page:
1. Select user.jsp in the J2EE navigator.
2. Right-click user.jsp and choose Copy.
3. Select the Web Content node, right-click, and choose Paste. A Name Conflict dialog will appear.
4. Name the new page admin.jsp, as shown in Figure 5.
5. Press OK to create the new JSP file.
6. Open admin.jsp from the J2EE Navigator view.
7. Edit the heading to read Administrative Tasks.
8. Save the file and close it.

Start Page
The start page will link to user.jsp and admin.jsp. Use the following steps to create the first page of the Web application:
1. Create a JSP file named index.jsp under the Web Content folder, as you did for user.jsp.
2. Use main menu Insert -> Paragraph -> Heading 1 to insert Security Demo Start Page.
3. Click beneath the text and insert the text "Enter the application".
4. Select the text. Choose main menu Insert -> Link.
5. Click the Browse button. Choose File from the pop-up menu. A File Selection dialog will appear.
6. Select user.jsp, as shown in Figure 6.
7. Press OK. Press OK again to create the link.
8. Use the same procedure to create a link to admin.jsp for the Administer text.

Keep the JSP open for the following section.

Start Page Scriptlets
The start page should identify the logged-in user and his or her role. Moreover, the admin link on the page should only be visible to callers in the admin role. You need to add two scriptlets to implement this behavior. Follow these steps:
1. Click the Source tab.
2. Display the user name and rights by entering the following HTML element beneath the H1 element.

<H3>User ID:
<%= request.getUserPrincipal().getName()%><br />
Access rights:
<%= (request.isUserInRole("admin") ? "administrator": "user")%>
</H3>

3. Locate the Administer hyperlink. Surround it with scriptlet tags so it appears as follows:

<% if (request.isUserInRole("admin")) { %>
<A href="admin.jsp">Administer</A>
<% } %>

4. Press the Preview tag. The page should resemble Figure 7.
5. Save the JSP file.
6. Click the Preview tab and check that all links operate correctly.

The start page name, index.jsp, is one of the standard names on the welcome file list of the Web deployment descriptor. When you run the application on a server, that page will appear automatically.

Summary
This article has shown you how to obtain the infrastructure needed to implement an example of LDAP authentication through WebSphere. IBM Directory Server v5.1 contains the DIT to be used for authenticating users through WebSphere. We created a small application that will use admin and user roles to enable access to its pages. The start page is customized by Java scriptlets that display user information and conditionally enable an administrative link.

In the second article in this series, I will discuss how to define roles and associated constraints in the application deployment descriptor. The WebSphere v5.0 Test Environment will host the application after roles are associated with resource constraints and are mapped to groups in the LDAP directory. I will demonstrate how WebSphere can authenticate users using basic authentication against a mapped LDAP group. Application resources will be accessible on a per-role basis. Finally, I will discuss how to secure the transport channels between WebSphere, the LDAP directory, and the browser through SSL to prevent password snooping.

More Stories By Louis Mauget

Lou Mauget is a senior consultant with CrossLogic Corporation where his assignments include J2EE mentoring and designing instructional material. He has coauthored three computer-related books. His prior career at IBM included work as a consultant, programmer, and developer.

Comments (2) View Comments

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.


Most Recent Comments
Vivek Pinto 09/03/07 09:56:14 PM EDT

Hi,
I felt that one area where a lot of articles on this subject do not elaborate is configuring for authorization failure. I believe your article does nto address this either.

Some of the questions that could be better detailed are:
1 - How to configure the application server to redirect to a specific page on authorization failure
2 - A clear bloack diagram as to what is going on when authorization fails.

Umesh Subbarayalu 03/15/07 11:48:13 AM EDT

The best article that I have come across. Takes you step by step. Need to make it upto date for newer Websphere Versions though.