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)
A typical user interaction with a secure application running under WebSphere might look something like this:
- The user requests a protected resource in an enterprise application.
- 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.
WebSphere presents the user with the custom login form page (in this case,
- The user supplies credentials, typically in the form of user ID and password.
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.
- 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:
Let's get started! First we'll import the test application from the Download section:
- Extract the zip file into the C:\ directory. This creates a sub-directory called C:\security.
- Open Application Developer and enter C:\security\workspace.
- Open the J2EE perspective in the workspace, if it's not already open. From the main menu bar, select File => Import.
- To import the Enterprise Application file (EAR), select EAR File and then select Next.
- On the next screen, specify the name of the EAR File by selecting TestEAR.ear from the file system (C:\Security\TestEAR.ear).
- Specify TestEAR in the Project name field.
- Click Finish.
The imported application contains:
A protected servlet,
A custom form-based log-in screen,
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
Descriptor in the TestEAR Enterprise Application folder.
We'll edit these two files to
set up the users, roles, groups and resources.
- Double-click Web Deployment Descriptor in the TestWeb folder.
- Click on the Security tab.
The Security dialog displays. Click on the Security Roles tab to define the J2EE
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.xmlfile 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>
- 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.
- Select SecurityConstraint.
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
- Click Cancel.
When you add security constraints and resources, the
web.xmlfile 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>
From the Page tab, set the authentication method to Form. Set the login page to
- 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.
Application Deployment Descriptor maintained at the enterprise
application level adds configuration data to the J2EE-compliant
file while the WebSphere-specific data is added to the
From the J2EE Navigator View, select TestEAR => EAR Deployment Descriptor.
EAR Deployment Descriptorto open it in the Application Developer editor.
- Select the Security tab in the righthand window in the Application Developer editor.
Select the Gather button. This brings up a list of roles configured in
Web Deployment Descriptor. In our sample application, the
Application Deployment Descriptor,
application.xml, is already configured with the
- 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).
- Under Websphere Bindings, check the Users/Groups checkbox.
- 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.
Now we're finished with doing the configuration work from within Application Developer. The
ibm-application-bnd.xmifiles have been updated with the configuration.
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.
- First, open the Server Perspective by clicking on the Perspective button in the upper left corner of Application Developer.
- The Server Configuration view appears in the bottom left corner. Click on Servers => New => Server and Server Configuration.
The Create a New Server and Server Configuration window displays.
Enter the Server Name as
TestServerand leave the default values for all other fields.
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
TestServeris created in Stopped mode.
Now we need to add our enterprise application
TestEARto the new server instance. To do this, right-click on TestServer in the Server Configuration window and select Add => TestEAR.
- Double-click on TestServer from the Server Configuration pane. The Websphere Server Configuration window displays.
- Click on the Configuration tab. Then check Enable administration console to start the Admin Console.
- Press (Ctrl-S) to save the configuration.
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.
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=peopletree. These two users are of type
inetOrgPerson, which is an objectclass that comes with the default installation of the Directory Server.
HRorganizational 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.
The LDAP configurations are not provided as a part of the download.
This is because your LDAP settings might not have
o=ibm,c=usas 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
administratorsgroup in LDAP.
- 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.
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
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:
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.
- From the Navigation menu, select Security => User Registries => LDAP.
- 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
localhostas 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=usconforming to the Directory Schema used in the sample application.
inetOrgPerson. Therefore, we need to change the default value of User Filter from
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.
- 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.
- Start the server.
- Select the J2EE Navigator tab.
- Open up the TestWeb folder and navigate to the TestServlet.
- Right-click on TestServlet and select Run on Server.
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.jspis displayed, prompting the user for authentication.
Now let's try to authenticate a user whose password is incorrectly entered. We'll use
uid=jdoebut 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.
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
ValidUsercan 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
Now let's try a valid user with a valid password. We'll use
uid=jdoeagain, 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.
- If you followed the steps above, and got the expected results, you did it!!!
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
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.
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.
IBM WebSphere V5.0 Security WebSphere Handbook Series
LDAP Implementation Cookbook
Websphere Application Server V5.0 InfoCenter
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 firstname.lastname@example.org