Using IBM Tivoli Directory to deploy LDAP with Websphere Community Edition

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

Krishnakumar 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.

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

Tag this!

Date: 20 Nov 2008 (Published 26 Apr 2006)
Level: Intermediate
PDF: A4 and Letter (245KB | 12 pages)Get Adobe® Reader®
Activity: 497 views

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

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

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

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

                
<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

                
<?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

Description	Name	Size	Download method
Sample Web application	wasce-ldap-sample-v2x.zip	25 KB	HTTP

Information about download methods

Resources

Learn

Get products and technologies

Discuss

About the author

Krishnakumar 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.

Comments (Undergoing maintenance)

Trademarks | My developerWorks terms and conditions

Close [x]

Help: Update or add to My dW interests

What's this?

This little timesaver lets you update your My developerWorks profile with just one click! The general subject of this content (AIX and UNIX, Information Management, Lotus, Rational, Tivoli, WebSphere, Java, Linux, Open source, SOA and Web services, Web development, or XML) will be added to the interests section of your profile, if it's not there already. You only need to be logged in to My developerWorks.

And what's the point of adding your interests to your profile? That's how you find other users with the same interests as yours, and see what they're reading and contributing to the community. Your interests also help us recommend relevant developerWorks content to you.

View your My developerWorks profile

Return from help

Close [x]

Help: Remove from My dW interests

What's this?

Removing this interest does not alter your profile, but rather removes this piece of content from a list of all content for which you've indicated interest. In a future enhancement to My developerWorks, you'll be able to see a record of that content.

View your My developerWorks profile

Return from help

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

author1-email=krishnakumarb@in.ibm.com

author1-email-cc=