Integrating LDAP With Tomcat

Depending on who you are developing a server for, you may have to follow some authentication rules to prevent unauthorized access to the information that is hosted. Many web servers rely on the common LDAP (Lightweight Directory Access Protocol) protocol to control access. I have set up quite a few tomcat servers and have been asked about how authentication protocols like LDAP can be integrated into the system. This tutorial is designed to help users set up LDAP authentication with their Tomcat server

Required Tools

There are a few tools required to be able to do this job successfully.

• Apache Tomcat - http://tomcat.apache.org/

Step 1: Get LDAP Server Information

The first step in this process is to gather some information about your ldap server. If we don't have this information, then there isn't much further that we can go. To be able to successfully set up these permissions, we need to know the location of the ldap server, an ldap admin user id (on that preferably can only read the ldap contents, and not modify them), as well as the groups that the user should be a member of if they are granted access.

For this tutorial, we will rely on the following arbitrary information:

• LDAP Server: ldap.normalexception.net
• LDAP Port: 389
• LDAP Admin: ldapreader
• LDAP Admin Membership: ou=Admins,o=normalexception.net
• LDAP Admin Pasword: readonly
• LDAP Userbase: ou=Members,o=normalexception.net

Step 2: Open Tomcat Server.xml File

The next step is to open the server configuration file for your tomcat installation. This is usually found in (TOMCAT_INSTALL_DIR)\conf\server.xml. You will want to scroll down to the server realm config section which should start off like:

<Realm className="org.apache.catalina.realm.UserDatabaseRealm" (in my case it was line 120).

This particular section tells tomcat that the authentication for the server is based off of the tomcat user configuration file (the tomcat-users.xml file). At this point in the tutorial, we will be replacing this with the ldap authentication realm. Later in this tutorial I will explain how to retain both an LDAP authentication as well as a user database authentication. What we want to do next, is to replace the

<Realm className="org.apache.catalina.realm.JNDIRealm"
 connectionName="uid=ldapreader,ou=Admins,o=normalexception.net"
 connectionPassword="readonly"
 connectionURL="ldap://ldap.normalexception.net:389"
 referrals="follow"
 userBase="ou=Members,o=normalexception.net"
 userSearch="(uid={0})"
 userSubtree="true"
 userRoleName="memberOf"
/>
						

There are a few things that the above will tell the server. The first is the class name of the realm object, which in the case of LDAP authentication will be "org.apache.catalina.realm.JNDIRealm". The second line 'connectionName' is the information about the ldap admin that will be reading the ldap database for authentication. As we mentioned in the previous step, this admin is 'ldapreader' and he belongs to the 'ou=Admins,o=normalexception.net' organizational unit. The 'connectionPassword' reflects the password of the admin, and the 'connectionURL' is the address to the ldap server.

'Referrals' specifies that you want the authenticator to do a referral search. In many cases you want this value to be 'follow' as many ID's and OU's have referral links. The 'userBase' states what the unit is named where the members are all located, which in our case is 'ou=Members' which is found in 'o=normalexception.net'. The user search is simply '(uid={0})' which just tells the search that the value we are searching for is a 'uid'. You want to enable 'userSubtree' if you have a complex ldap tree structure. This ensures that you search the entire directory tree under the 'OU' to find the user. Note that this may increase search times on larger ldap servers. Lastly, you will want to find the users roles which in our case are found under the tag of 'memberOf'. This is default for LDAP.

Step 3: Enabling LDAP Authentication In Your Webapp

Now that we enabled ldap authentication in our tomcat server, we need to tell our webapp that we want it to do an ldap authentication when a user accesses the page. To do this, we will navigate to our webapp's web.xml file which is generally found in (TOMCAT_INSTALL_DIR)\webapps\{webappname}\WEB-INF\web.xml.

When you open the web.xml file for your webapp, you will see a bunch of configuration parameters for your webapp. Chances are you will not have a section that is called '<security-constraint>', no worries, we are going to be adding that right now. Scroll to the end of your web.xml file and paste the following information:

<security-constraint>
 <web-resource-collection>
	  <web-resource-name>LDAP Authentication</web-resource-name>
	  <description>
	  Authentication for registered users.
	  </description>
	  <url-pattern>/*</url-pattern>
	  <http-method>GET</http-method>
	  <http-method>POST</http-method>
 </web-resource-collection>
 <auth-constraint>
	  <role-name>regular_user</role-name>
 </auth-constraint>
</security-constraint>
<security-role>
 <role-name>regular_user</role-name>
</security-role>
<login-config>
 <auth-method>BASIC</auth-method>
 <realm-name>NormalException.net</realm-name>
</login-config>
						

The above block of text will tell our webapp that we will be using an LDAP security constraint to access the page. The properties are as follows:

• web-resource-name : The name of the resource, this is only used if we want to access the resource from within some java servlet code. Many users will not be doing this, so you can put whatever value you prefer here
• description : A simple description of what this authentication constraint is
• url-pattern : What url's do we want this security to apply to? In this case, we are making sure the user is authenticated for every page of the app
• http-method : What methods do we want authentication for? In my case I want authentication for GET's and POST's
• role-name : What role should the user belong to if they are granted access. In my sample ldap environment, all regular members are under the 'regular_user' role.
• auth-method : In most cases BASIC will be sufficient, but you can also have different authentication methods if you prefer more advanced authentication security. Please check the apache website for more information.
• realm-name : The name of our realm, this will be displayed in the pop-up dialog that requests the username and password from the user

And that should do it! As you can see, it really isn't too difficult to integrate ldap to your webapps as long as your ldap server is properly configured, and you have the information of the ldap server to help you configure tomcat properly.