Introduction

An increasing number of systems now use LDAP-based directory services in order to provide an integrated authentication and authorization-based security mechanism for enterprise applications. It would be a great convenience to the application developer to be able to create a testing environment from within IBM®WebSphere® Studio Application Developer (Application Developer) to test authentication and authorization using an LDAP registry.

The good news is that Application Developer V5 now provides a way to configure the WebSphere Test Environment to do just that! This article will show you how to use Application Developer to create, configure, and test a simple enterprise application to use LDAP for security.

This article assumes a basic understanding of:

• J2EE security
• WebSphere Application Server
• WebSphere Studio Application Developer V5
• LDAP and the use of filters to configure search parameters

You must have the following products to complete the steps in this article:

• WebSphere Studio Application Developer V5
• IBM Directory Server V4.1 (as the LDAP product)

Back to top

Typical WebSphere security scenario

A typical user interaction with a secure application running under WebSphere might look something like this:

1. The user requests a protected resource in an enterprise application.
2. If security is enabled and properly configured, WebSphere intercepts the request to the protected resource. In this case, we are using Form-based Custom Login as the mode of authentication.
3. WebSphere presents the user with the custom login form page (in this case, login.jsp).
4. The user supplies credentials, typically in the form of user ID and password.
5. WebSphere authenticates using j_security_check, the default login servlet provided by WebSphere. Authentication can be based on either local operating system, LDAP or a custom registry. In our case, we are going to use LDAP as the user registry.
6. If authentication is successful, the user gains access to the protected resource, provided that the user has the correct access rights, or roles, for the resource. If the authentication and authorization process is not successful, the user is unable to log in.

This sequence is illustrated below:

Back to top

Importing the test application

Let's get started! First we'll import the test application from the Download section:

1. Extract the zip file into the C:\ directory. This creates a sub-directory called C:\security.
2. Open Application Developer and enter C:\security\workspace.
3. Open the J2EE perspective in the workspace, if it's not already open. From the main menu bar, select File => Import.
4. To import the Enterprise Application file (EAR), select EAR File and then select Next.
5. On the next screen, specify the name of the EAR File by selecting TestEAR.ear from the file system (C:\Security\TestEAR.ear).
6. Specify TestEAR in the Project name field.
7. Click Finish.

The imported application contains:

• A protected servlet, TestServlet.
• A custom form-based log-in screen, login.jsp.
• An HTML file, error403.html, for error reporting on resources that are not found.

The most important files for our purpose are Web Deployment Descriptor in the TestWeb Web Application folder and Application Deployment Descriptor in the TestEAR Enterprise Application folder. We'll edit these two files to set up the users, roles, groups and resources.

Back to top

Configuring the Web Deployment Descriptor

1. Double-click Web Deployment Descriptor in the TestWeb folder.
2. Click on the Security tab.
3. The Security dialog displays. Click on the Security Roles tab to define the J2EE roles.

   You can see that a role, called ValidUser, has already been created for our application. If you needed to define more roles for the application, you would do that from this dialog, using the Add button.

   The concept and definition of roles comes from the Business Domain of the enterprise application. In the J2EE security model, a role is mapped to a corresponding profile of, for example, a group in an underlying security implementation. To the servlet, a role represents a group whose members are allowed to access the servlet, mapped together by a Security Constraint. To the underlying J2EE security model, a role can map directly to a group or a group can map to multiple roles. The way roles are to be mapped to groups should be planned out in the design phase of an application.

   If you look at the XML source (web.xml) for the Web Deployment Descriptor, you can see that creating roles updates the XML file based on the grammar of the web.xml file as specified by the J2EE specification. To view the contents of web.xml, click the Source tab. Following is an excerpt from the file:

   <security-role> <description></description> <role-name>ValidUser</role-name> </security-role>

   
   
4. Now select the Security Constraints tab. Security constraints match users and or groups to particular resources. Each security constraint has a corresponding Resource List, which defines the URLs (for JSPs, HTMLs, servlets, and so on) that are collectively defined for that constraint.
5. Select SecurityConstraint.
6. Click Edit. This opens a window from which you can map access methods and permissions to resources.

   If you wanted to add more resources for your specific application, you would select ValidUser and click Edit. For our application, the only resource configured is TestServlet.)

7. Click Cancel.
8. When you add security constraints and resources, the web.xml file is updated. For example:

   <security-constraint> <web-resource-collection> <web-resource-name>Resources</web-resource-name> <description></description> <url-pattern>/TestServlet</url-pattern> <http-method> GET</http-method> <http-method> POST</http-method> </web-resource-collection> <auth-constraint> <description></description> <role-name>ValidUser</role-name> </auth-constraint> </security-constraint>

   
   
9. From the Page tab, set the authentication method to Form. Set the login page to login.jsp.
10. Close the Web Deployment Descriptor editor.

A little background: J2EE security is a specification. The runtime bindings of the security roles to the actual underlying implementation are not laid down as a part of the specification. Each application server vendor has its own implementation technique. WebSphere uses XMI binding files tied to the enterprise application. The Application Deployment Descriptor maintained at the enterprise application level adds configuration data to the J2EE-compliant application.xml file while the WebSphere-specific data is added to the ibm-application-bnd.xmi file.

Back to top

Configuring the EAR Deployment Descriptor

1. From the J2EE Navigator View, select TestEAR => EAR Deployment Descriptor. Double-click the EAR Deployment Descriptor to open it in the Application Developer editor.
2. Select the Security tab in the righthand window in the Application Developer editor.
3. Select the Gather button. This brings up a list of roles configured in the Web Deployment Descriptor. In our sample application, the Application Deployment Descriptor, application.xml, is already configured with the ValidUser role.
4. Select ValidUser. At this point, we're beginning to get into LDAP-specific configuration and bindings. This is where application-defined roles are mapped to users and groups that reside in a user registry, which in our case is an instance of IBM Directory Server V4.1 (LDAP).
5. Under Websphere Bindings, check the Users/Groups checkbox.
6. Because Application Developer has no way of accessing an instance of LDAP to obtain the users and groups for mapping purposes, we need to enter the names of the users and or groups. Since we're using role-group mapping, type in the name of the LDAP group that contains the users to whom you want to provide access to your resources.

   To do this, select Add to the right of the Group text area. In the dialog that displays, type in the name of the group, in our case administrators (the group that is defined in LDAP), and click Finish.

7. Now we're finished with doing the configuration work from within Application Developer. The application.xml and ibm-application-bnd.xmi files have been updated with the configuration.

Back to top

Creating and configuring the server

WebSphere Application Developer provides an embedded WebSphere Application Server Test Environment (WTE). Both 4.0 and 5.0 versions of the WTE are supported. Although Application Developer provides most of the configurations through its editor features, the security configurations for WTE are not provided from the editor. For this, we need to fire up the Administration Console of WTE and configure application server security.

Lets walk through the step-by-step process of creating and configuring a Server/Server Configuration and using the Admin Console of the started server to complete the LDAP settings.

1. First, open the Server Perspective by clicking on the Perspective button in the upper left corner of Application Developer.
2. The Server Configuration view appears in the bottom left corner. Click on Servers => New => Server and Server Configuration.
3. The Create a New Server and Server Configuration window displays. Enter the Server Name as TestServer and leave the default values for all other fields.
4. Click on WebSphere version 5.0 => Test Environment, then click Finish to create the new server instance TestServer.

   Once the server instance is created, you can see it in the Server Configuration pane. You can also see that TestServer is created in Stopped mode.

5. Now we need to add our enterprise application TestEAR to the new server instance. To do this, right-click on TestServer in the Server Configuration window and select Add => TestEAR.
6. Double-click on TestServer from the Server Configuration pane. The Websphere Server Configuration window displays.
7. Click on the Configuration tab. Then check Enable administration console to start the Admin Console.
8. Press (Ctrl-S) to save the configuration.

Back to top

Configuring LDAP settings

This section describes how to configure the LDAP settings for our application. It contains important information about the LDAP schema on which our application security is based.

LDAP User Registry Schema

The diagram below shows the simple LDAP schema on which our enterprise application is configured for authentication and authorization based on users, roles and groups.

This schema depicts the following:

• The organization (o=ibm,c=us) has two organizational units: ou=people and ou=hr.
• There are two users (with uid=jdoe and uid=sachin) in the organization who are placed in the ou=people tree. These two users are of type inetOrgPerson, which is an objectclass that comes with the default installation of the Directory Server.
• The HR organizational unit has a group (cn=administrators). The group type is groupOfNames, which is an objectclass that comes with the default installation of the Directory Server. This is the group name that was added in Configuring the EAR Deployment Descriptor.
• Using the Directory Server administrative console, the two users are added to the group (cn=administrators) as members.

Notes:

• The LDAP configurations are not provided as a part of the download. This is because your LDAP settings might not have o=ibm,c=us as the root node. Therefore, the configurations would not be successfully imported into your LDAP instance. You will need to configure LDAP manually. To do this, create a suffix called o=ibm,c=us, and then follow the above diagram to create the structure as depicted.

  This step is a pre-requisite before you do configuration steps that follow.

• The application has a role (derived from the problem/business domain) called ValidUser. This role is mapped to the administrators group in LDAP.

Configuring LDAP

1. Now it's time to do the final step in the configuration process. First, we need to start the server. To do this, right-click on TestServer in the Servers view and click Start.
2. Wait for the message "Server open for e-business" to appear in the Console window, as shown below:

   [4/27/03 22:16:42:436 EDT] 6e09af3c HttpTransport A SRVE0171I: Transport http is listening on port 9,080. [4/27/03 22:16:44:780 EDT] 6e09af3c HttpTransport A SRVE0171I: Transport https is listening on port 9,443. [4/27/03 22:16:44:790 EDT] 6e09af3c HttpTransport A SRVE0171I: Transport http is listening on port 9,090. [4/27/03 22:16:45:030 EDT] 6e09af3c HttpTransport A SRVE0171I: Transport https is listening on port 9,043. [4/27/03 22:16:45:140 EDT] 6e09af3c RMIConnectorC A ADMC0026I: RMI Connector available at port 2809 [4/27/03 22:16:45:180 EDT] 6e09af3c WsServer A WSVR0001I: Server server1 open for e-business

   
   
3. Now start the admin console by selecting TestServer from the Servers window, then selecting Run administrative console. The admin console is a WebSphere application that normally opens in a Web browser within the Application Developer editor window. If this doesn't happen, open up any browser and enter the following URL: http://localhost:9090/admin.

   This step is a pre-requisite before you do configuration steps that follow.

   XML error: The image is not displayed because the width is greater than the maximum of 580 pixels. Please decrease the image width.

   Once the admin console appears, enter any user ID and the press OK.

4. From the Navigation menu, select Security => User Registries => LDAP.
5. The LDAP User Registry window displays. In this window, you need to provide the following entries:
• Server User ID - I used sachin, who is a user in the directory. You can use the ID of any valid user in the directory.
• Server User Password - I used the password defined for sachin. You must use the valid password for the user you entered in the Server User ID field.
• Type - Select IBM_Directory_Server from the menu.
• Host - Use localhost as long as a local instance of IBM Directory Server is running. If not, you can use the URL of any machine where an instance of the IBM Directory Server is running and which is network-reachable from your machine.
• Port - Use 389, which is the default port for LDAP, unless of course it is set to a non-default value, in which case use the correct value.
• Base Distinguished Name (DN) - I used o=ibm,c=us conforming to the Directory Schema used in the sample application.
6. Check Ignore Case.
7. Leave all other fields with the default values provided, and click Apply to save the settings.
8. Next we need to set the advanced LDAP settings of LDAP. To do this, scroll down and click Advanced LDAP Settings.
9. In our simple LDAP schema, we haven't used any custom structural or auxiliary object classes. The user entries have the attribute uid as unique. However, the user entries are of objectclass type inetOrgPerson. Therefore, we need to change the default value of User Filter from (&(uid=%v)(objectclass=ePerson)) to (&(uid=%v)(objectclass=inetOrgPerson))

   Our group (administrators) is defined as a groupOfNames objectclass, so the Group Filter doesn't need to be changed. Keep the defaults for all other values.

   Click Apply to save the settings.

10. In the sample application, we're using LTPA (Lightweight Third Party Authentication), which we also need to configure. To do this, select Security => Authentication Mechanisms => LTPA. This opens a window that prompts you for a user ID and password. WebSphere uses these values to encrypt and decrypt the LTPA keys. You can use any valid user ID and password pair. Click Apply.
11. The final step is to configure global security. Select Security => Global Security. In the dialog that comes up do the following:
    
    • Check Enabled.
    • Make sure that Enforce Java 2 Security is not checked.
    • Right-click on Active Authentication Mechanism and select LTPA (Lightweight Third Party Authentication) from the menu.
    • Right-click on Active User Registry and select LDAP from the menu.
    Click Apply to save the global security settings.
12. Enough of configurations! Now it's time to save the settings, log off the admin console and get ready to do some testing. Follow the steps as depicted in the following two figures and then click Logout to log off the admin console.
13. Return to the Servers window and stop the server.

Back to top

Testing the application

1. Start the server.
2. Select the J2EE Navigator tab.
3. Open up the TestWeb folder and navigate to the TestServlet.
4. Right-click on TestServlet and select Run on Server.
5. A Web browser opens up in Application Developer editor pane. Since TestServlet is a protected resource, it should not be displayed prior to a successful authentication and that's exactly what happens here. Instead, the login.jsp is displayed, prompting the user for authentication.
6. Now let's try to authenticate a user whose password is incorrectly entered. We'll use uid=jdoe but an invalid password. This will fail the authentication test and the console output will look something like this:

   Authentication failed for jdoe. The user id or password may have been entered incorrectly or misspelled. The user id may not exist, the account could have expired or disabled. The password may have expired.

   
   
7. The User Registry can contain some users who are not playing the role of ValidUser. In other words, they are not authorized to access resources that ValidUser can access. Let's pick a user like that, uid=tilak, and try to log him in. The console output should look something like this:

   Authorization failed for tilak while invoking GET on default_host:/TestWeb/TestServlet. Authorization failed. Not granted any of the required roles: ValidUser

   
   
8. Now let's try a valid user with a valid password. We'll use uid=jdoe again, but this time with the correct password. The browser should display the contents of the TestServlet, which at this point has been accessed with the authentication and authorization credentials of a user conforming to the Declarative Security Mapping.
9. If you followed the steps above, and got the expected results, you did it!!!

Back to top

An important LDAP design tip

If you decide to use LDAP as the user registry for authentication and authorization of J2EE enterprise applications running under WebSphere Application Server V5, you should be aware of a WebSphere constraint that will affect the design of the LDAP schema.

In a LDAP design, it's very common to have a group that appears in multiple nodes of a directory tree. For example, the group called administrators in our example may be present not only in the ou=HR node, but also in another node, such as ou=Accounts. It's also not uncommon to have a different set of members of these two groups in the two different nodes in the directory.

While this is completely acceptable from a LDAP design standpoint, WebSphere has some restrictions on the existence of the same group in multiple nodes under the same Base Distinguished Name, or root node. Basically, WebSphere's LDAP search halts after finding the first match of a particular group.

What this means is that users in the group that appears in another node would never be viewed as having valid roles in the system. You need to take this into consideration while designing the LDAP schema.

Back to top

Conclusion

In this article, we learned how to use LDAP to meet the authentication and authorization requirements of a J2EE-based enterprise application built with Application Developer. We went over how to configure enterprise application security using the web and application deployment descriptors and learned how to map them to the underlying security implementation. Finally, we deployed the sample application and tested our security.

With LDAP being used more frequently as the data store for user and other information in real-world enterprise applications, having a way to test LDAP-based security directly from a development environment is definitely a welcome feature for the enterprise security developer.

Top of page

Back to top

Download

Name	Size	Download method
TestEAR.zip	7.9 KB	FTP|HTTP

Information about download methods

Resources

• IBM WebSphere V5.0 Security WebSphere Handbook Series
  
  
• LDAP Implementation Cookbook
  
  
• Websphere Application Server V5.0 InfoCenter
  
  

About the author

Tilak Mitra is an IT Architect in AIS, EAD Southeast sector, in the Fort Lauderdale/Miami area. He specializes in mid- to large range enterprise and application architectures based on J2EE, MQ and other EAI technologies. You can contact Tilak at tmitra@us.ibm.com

Rate this article

Comments

Back to top

Table of contents

• Introduction
• Typical WebSphere security scenario
• Importing the test application
• Configuring the Web Deployment Descriptor
• Configuring the EAR Deployment Descriptor
• Creating and configuring the server
• Configuring LDAP settings
• Testing the application
• An important LDAP design tip
• Conclusion
• Download
• Resources
• About the author
• Comments

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