Using IBM Tivoli Directory to deploy LDAP with Websphere Community Edition

Learn how to implement user authentication and authorization for WebSphere® Application Server Community Edition, using IBM® Tivoli® Directory Server to configure an LDAP realm .

Share:

Krishnakumar Balachandar (krishnakumarb@in.ibm.com), Software Engineer, WebSphere Application Server Community Edition Support Team, EMC

Krishnakumar BalachandarKrishnakumar Balachandar is a Senior Staff Software Engineer at IBM Software Labs in Bangalore, India. He is part of the support team for Geronimo and WebSphere Community Edition.



20 November 2008 (First published 26 April 2006)

Also available in

Introduction

Recently updated for V2.1.x

This article was recently updated to apply to WebSphere Application Server Community Edition V2.1.x. You can also view a PDF of the original V1.1 article.

IBM WebSphere Application Server Community Edition is a Java™ Enterprise Edition (Java EE) application server based on Apache Geronimo. This article tells you how to use IBM Tivoli Directory Server V 6.1 ( hereafter called Directory Server ) with IBM WebSphere Community Edition 2.1 ( hereafter called Community Edition ) for user authentication and authorization. This article is intended for Java EE application developers who want to configure a LDAP realm with Directory Server for their applications to be deployed in Community Edition.

Application servers store credentials in a repository based on files, a database, LDAP or other custom registries. LDAP repositories can store static information related to users and can be used across the enterprise by all applications. This article shows how to use Directory Server to configure an LDAP realm in Community Edition. We will also deploy a sample application that uses LDAP entries in Directory Server.

Before you continue: This article was written for WebSphere Application Server Community Edition V2.1, which was the current version at the time the article was published. Some of the information in this article may not be applicable to later versions. To follow along with this article, be sure to use the product version on which this article is based. If you wish, you can download the current version of WebSphere Application Server Community Edition, or you can download an earlier version by visiting the product archive page.


About LDAP Records

You can use LDAP to store user information like IDs, addresses, telephone numbers, roles and passwords. The data is organized in a tree structure starting from the root of the hierarchy. Listing 1 shows a sample LDAP user record.

Listing 1. Sample LDAP user record
dn: uid=guest1,ou=people,dc=ibm,dc=com
objectclass: ePerson
objectclass: inetOrgPerson
cn: guest1	
sn: guest1
displayName: Guest
uid: guest
userpassword: welcome
ou: people

The record in Listing 1 is for a user called Guest1, whose user ID is guest1 and password is welcome. An LDAP record of type ePerson stores other user information like address, telephone, etc.

You can group users created in a LDAP tree based on role. For example, you can group all users with administration rights under the admin role. Listing 2 shows users (user1, user2) grouped by role.

Listing 2. Users grouped by role
dn: cn=users,ou=groups, dc=ibm,dc=com
objectClass: groupOfUniqueNames
uniqueMember: cn=user2,cn=user1,ou=groups,dc=ibm,dc=com
cn: users

Similar to the two previous LDAP entries, you can create a complex structure to map users and roles. You can store these details in a LDIF file, and upload to any LDAP server. The sample application used in this article contains an LDIF file that has the LDAP structure shown in Figure 1.

Figure 1. LDAP structure
LDAP structure

Configuring Tivoli Directory Server

In this section we'll configure Tivoli Directory Server.

You can install Tivoli Directory Server as a separate product on the same machine as the application server, or on a different machine. It is available on port 389 by default. Tivoli Directory Server provides utilities for performing operations on the server. You can invoke these operations through a Web interface (http://localhost:12100/IDSWebApp/IDSjsp/IDSConsoleFrameWork.jsp), but you need to have installed WebSphere Application Server - Express when you installed IBM Tivoli Directory Server.

To start IBM Tivoli Directory Server and upload the LDIF file to the server, enter the commands shown in Listing 3:

Listing 3. Directory Server commands
1. To add the suffix submit the following command at the command prompt. 
<tivolids_home>/sbin/idscfgsuf -s dc=ibm,dc=com

2. To start IBM Tivoli Directory Server, submit the following command at the command prompt
<tivolids_home>>/sbin/ibmslapd

3. To add ldap entries from ldif, submit the following command at the command prompt
<tivolids_home>/bin/ldapadd -h ldap://<ldaphostname> -D "cn=root" -w
<password> -f <ldif_directory_path><filename>.ldif
	
Note: In all the above commands, the <tivolids_home> 
is the directory where IBM Tivoli Directory server is installed.

Figure 2 shows the LDAP entries created in Directory Server.

Figure 2. LDAP entries in Directory Server
LDAP entries in Directory Server

Web Application Security and LDAP

Web application security consists of authentication and authorization. You define these in the deployment descriptor. Within the deployment descriptor, you can configure specific realms for authentication and authorization. To use LDAP, define the authentication as FORM based, and invoke LDAP to check for the user ID and credentials.

Similarly, you can group users based on roles defined in the deployment descriptor, and create corresponding entries in the LDAP server. Figure 3 shows the security constraints and roles in the Web deployment descriptor, a "Geronimo" plan for WebSphere Application Server Community Edition, and their mapping to entries in LDAP.

Figure 3. Security constraint and role mappings
Security constraint and role mappings

Creating a Community Edition Plan for the LDAP Realm

To use LDAP in WebSphere Application Server Community Edition, you need to create a realm plan. You can then deploy this plan server-wide, or within the scope of an application or module. Listing 4 shows a sample LDAP realm plan for Community Edition.

Listing 4. LDAP realm plan

Click to see code listing

Listing 4. LDAP realm plan

<module xmlns="http://geronimo.apache.org/xml/ns/deployment-1.2">
    <environment>
        <moduleId>
            <groupId>console.realm</groupId>
            <artifactId>ldap-realm</artifactId>
            <version>1.0</version>
            <type>car</type>
        </moduleId>
        <dependencies>
            <dependency>
                <groupId>org.apache.geronimo.framework</groupId>
                <artifactId>j2ee-security</artifactId>
                <type>car</type>
            </dependency>
        </dependencies>
    </environment>
    <gbean name="ldap-realm" 
           class="org.apache.geronimo.security.realm.GenericSecurityRealm" 
           xsi:type="dep:gbeanType" 
           xmlns:dep="http://geronimo.apache.org/xml/ns/deployment-1.2" 
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <attribute name="realmName">ldap-realm</attribute>
        <reference name="ServerInfo">
            <name>ServerInfo</name>
        </reference>
        <xml-reference name="LoginModuleConfiguration">
            <log:login-config xmlns:log="http://geronimo.apache.org/xml/ns/loginconfig-2.0">
                <log:login-module control-flag="REQUIRED" wrap-principals="false">
                    <log:login-domain-name>ldap-realm</log:login-domain-name>
                    <log:login-module-class>
                         org.apache.geronimo.security.realm.providers.LDAPLoginModule
                    </log:login-module-class>
                    <log:option name="roleSearchMatching">(uniqueMember={0})</log:option>
                    <log:option name="userSearchMatching">uid={0}</log:option>
                    <log:option name="userBase">ou=people,dc=ibm,dc=com</log:option>
                    <log:option name="connectionUsername">cn=root</log:option>
                    <log:option name="roleName">cn</log:option>
                    <log:option name="userSearchSubtree">false</log:option>
                    <log:option name="authentication">simple</log:option>
                    <log:option name="initialContextFactory">com.sun.jndi.ldap.LdapCtxFactory</log:option>
                    <log:option name="roleBase">ou=groups,dc=ibm,dc=com</log:option>
                    <log:option name="connectionPassword">kesava12</log:option>
                    <log:option name="connectionURL">ldap://localhost:389</log:option>
                    <log:option name="roleSearchSubtree">false</log:option>
                </log:login-module>
            </log:login-config>
        </xml-reference>
    </gbean>
</module>

This LDAP realm plan consists of three Gbeans. When deployed, it configures JAAS to use LDAPLoginModule to connect to LDAP server and retrieve the user credentials. To get user details, you use this query: userSearchMatching=uid={0} and roleSearchMatching=(uniqueMember={0}). Based on these entries, the LDAPLoginModule retrieves the users and roles.

You can deploy the LDAP realm using the Community Edition console or deploy tool:

java -jar bin\deployer.jar deploy ldap-realm-ibm.xml

Now that we have a LDAP realm in place, we need to configure our LDAP Web application to use the LDAP realm. You add these details to the geronimo-web.xml plan file as shown in Listing 5.

Listing 5. geronimo-web.xml plan

Click to see code listing

Listing 5. geronimo-web.xml plan

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<web:web-app xmlns:dep="http://geronimo.apache.org/xml/ns/deployment-1.2"
     xmlns:conn="http://geronimo.apache.org/xml/ns/j2ee/connector-1.2" 
     xmlns:name="http://geronimo.apache.org/xml/ns/naming-1.2" 
     xmlns:ejb="http://openejb.apache.org/xml/ns/openejb-jar-2.2" 
     xmlns:pkgen="http://openejb.apache.org/xml/ns/pkgen-2.1" 
     xmlns:app="http://geronimo.apache.org/xml/ns/j2ee/application-2.0" 
     xmlns:sec="http://geronimo.apache.org/xml/ns/security-2.0" 
     xmlns:web="http://geronimo.apache.org/xml/ns/j2ee/web-2.0.1" 
     xmlns:pers="http://java.sun.com/xml/ns/persistence" 
     xmlns:client="http://geronimo.apache.org/xml/ns/j2ee/application-client-2.0">
     
    <dep:environment>
        <dep:moduleId>
            <dep:groupId>LDAPExample</dep:groupId>
            <dep:artifactId>wasce</dep:artifactId>
            <dep:version>1.0</dep:version>
            <dep:type>car</dep:type>
        </dep:moduleId>
    
      	<dep:dependencies>
    		<dep:dependency>
        		<dep:groupId>console.realm</dep:groupId>
        		<dep:artifactId>ldap-realm</dep:artifactId>
        		<version>1.0</version>
        		<dep:type>car</dep:type>
      		</dep:dependency>
    	</dep:dependencies>
 
    </dep:environment>
    <web:context-root>/ldap-demo</web:context-root>
    
    <security-realm-name>ldap-realm</security-realm-name>
    
 <sec:security>

  <sec:default-principal realm-name="ldap-realm">
   <sec:principal class="org.apache.geronimo.security.realm.providers.GeronimoUserPrincipal" name="system"/>
  </sec:default-principal>

      <sec:role-mappings>

       <sec:role role-name="admin">
        <sec:realm realm-name="ldap-realm">

	<sec:principal	 
class="org.apache.geronimo.security.realm.providers.GeronimoGroupPrincipal"
                  name="admin" designated-run-as="true" />

	<sec:principal
class="org.apache.geronimo.security.realm.providers.GeronimoUserPrincipal"
	name="system" />

        </sec:realm>
       </sec:role>
			
       <sec:role role-name="users">
        <sec:realm realm-name="ldap-realm">

	<sec:principal
class="org.apache.geronimo.security.realm.providers.GeronimoGroupPrincipal"
       name="users" designated-run-as="true" />
	
         <sec:principal
class="org.apache.geronimo.security.realm.providers.GeronimoUserPrincipal"
	name="user1" />

	<sec:principal
class="org.apache.geronimo.security.realm.providers.GeronimoUserPrincipal"
         name="user2" />
       </sec:realm>
      </sec:role>
			
      <sec:role role-name="guest">
       <sec:realm realm-name="ldap-realm">
        
         <sec:principal
class="org.apache.geronimo.security.realm.providers.GeronimoGroupPrincipal"
          name="guest" designated-run-as="true" />

	<sec:principal
class="org.apache.geronimo.security.realm.providers.GeronimoUserPrincipal"
	name="guest1" />
      </sec:realm>
     </sec:role>

    </sec:role-mappings>
  </sec:security>
   
</web:web-app>

The roles in the geronimo-web plan should match those you created in the Web deployment descriptor and LDAP groups.

The Web application is packaged in a EAR file and available in the sample zip file (LDAPExample.ear). You deploy it using the Community Edition console.


Using the Sample Application

In the previous sections we created an LDAP realm, and configured our Web application to use that realm. We alsp deployed both the application and the realms. To access the Web application, enter the following url: http://localhost:8080/ldap-demo. Now you can login to the Web application, which verifies the user ID and credentials by retrieving the entries from the LDAP directory. At login, the application checks access to protected resources based on roles defined in the Web deployment descriptor.


Conclusion

In this article we created user records in Directory Server, and deployed a LDAP realm in Community Edition. The sample Web application showed how to use the LDAP realm to get user credentials and roles.


Download

DescriptionNameSize
Sample Web applicationwasce-ldap-sample-v2x.zip25 KB

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere, Tivoli
ArticleID=109369
ArticleTitle=Using IBM Tivoli Directory to deploy LDAP with Websphere Community Edition
publish-date=11202008