ApacheDS and Tomcat

Getting up and running with ApacheDS

The Apache Directory server is pretty easy to set up. It essentially runs out of a single executable JAR file and contains it's own database system and everything it needs in the one file. Now the download link on the ApacheDS website is inaccurate, but you can get the 0.9 distribution from http://svn.apache.org/repository/directory/distributions/. You will see in the README that starting it is easy as:

$ java -jar apacheds-main-0.9.jar

Now, you generally will not want to run it this way, but rather, to specify a configuration file. When the server comes up, it will create a folder called “server-work” that will contain the database files.

A good tool to use while working with ApacheDS is JXplorer. This is a stand-alone LDAP client written in Java. When you first bring up ApacheDS there will be one user: admin with a password of “secret” in the “system” branch:

Log in and play around with it. This is a really good tool for exploring what LDAP is and how it works, in addition to just getting your ApacheDS configured.

Now that you are running, you might be thinking to yourself, “Gee, I want to set this up the way I want it to run!” Well, good for you. Now, you can't create root-level structures in ApacheDS using the tool. In order to do that, you need to create a properties file.

#totsp.properties
# all multivalued properties are space separated like the
list of partitions here

server.db.partitions=totsp

# apache partition configuration

server.db.partition.suffix.totsp=dc=screaming-penguin,dc=com

server.db.partition.indices.totsp=ou uid cn objectClass
server.db.partition.attributes.totsp.dc=screaming-penguin
server.db.partition.attributes.totsp.objectClass=top
domain extensibleObject dNSDomain

Now, the first line, “server.db.partitions” is a space separated list of partitions you are going to want the server to start up with. I have a single partition, “totsp”.

Next, you have a block of configuration for the partitions you specified. “server.db.partition.suffix.[partition name]” is going to be the point in the tree where you want your partition information to begin. I have selected “com.screaming-penguin” here. “server.db.parition.indices.[partition name]” is going to be the node attributes you want the database to index for searching. Here I am specifying “organizational unit”, “user id” “common name” and “objectClass”. Next you specify attributes on the top level. Here I am creating a node called “screaming penguin” with a domain component “screaming-penguin”. And it is a “top”, a “domain” an extensibleObject, and if I want to use ApacheDS as a DNS server, I can specify it as a dNSDomain.

Complete information on this properties file is available at the ApacheDS website.

Now, when I bring up ApacheDS, I will see my new com.screaming-penguin scope:

Now, you want to create a node to hold your users. I will create an organization unit (ou=users) under screaming-penguin:

(CTRL-N to bring up this dialog, or right click on the domain in the tree view)

After filling in the cn and uniqueMemeber fields (bold means “required”), you can hit “submit” to add it to the tree.

Then, let's repeat the process and create a “roles” node. Then I add an administrator role to the tree... (note the uniqueMember field. More on this later.)

...and create a user called “rcooper” setting the “userPassword” field.

Finally, in the uniqueMember field of the role, put the DN to your user (If you right click the user and select “Copy DN” you can get it easily) and put it in the uniqueMember field of the “administrator”. You can right click and select “add value” to add as many users as you want to the administrator role.

So far so good. Feel free to create a couple more roles and users for the purposes of running with tomcat.

Configuring your Web Application

Next, we need to add a realm to our WAR file for Tomcat. In your META-INF/context.xml file, start with..

<?xml version="1.0" encoding="UTF-8"?>
<Context path="/DemoApplication" >
<Realm className="org.apache.catalina.realm.JNDIRealm"
debug="99"
connectionName="uid=admin,ou=system"
connectionPassword="secret"
connectionURL="ldap://localhost:389"
roleBase="ou=roles,dc=screaming-penguin,dc=com"
roleName="cn"
roleSearch="(uniqueMember={0})"
roleSubtree="false"
userSearch="(uid={0})"
userPassword="userPassword"
userPattern="uid={0},ou=users,dc=screaming-penguin,dc=com"
/>
</Context>

Here you can see we are replacing the respective inserts for searches with “{0}”. This is where tomcat will insert the appropriate value. We are also just using the standard JNDI realm with an ldap:// URL. If you aren't familiar with the full flexibility of the JNDI API, I highly recommend you look into it. You can use JNDI as a uniform access point to any tree/directory style information, including the filesystem. This, however, is out of scope for this article. You will also notice that I am having Tomcat connect as the ApacheDS “root” user. You might consider making a user specifically for Tomcat, but lets just get this running, eh?

Next, lets create a secure area in our web application. I just made a folder with an index.html file in it, but as you will see soon, you can apply the security to almost anything in your application.

Now, we need to set up the web.xml file to authenticate administrators:

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/j2ee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
version="2.4">

<session-config>
<session-timeout>30</session-timeout>
</session-config>
<welcome-file-list>
<welcome-file>index.jsp</welcome-file>
</welcome-file-list>

<!-- here I set up a constraint on the administrator folder -->
<security-constraint>
<web-resource-collection>
<web-resource-name>Administration Area</web-resource-name>
<url-pattern>/administrator/*</url-pattern>
</web-resource-collection>
<auth-constraint>
<role-name>administrator</role-name>
</auth-constraint>
</security-constraint>

<!-- here I tell it to use BASIC HTTP authentication -->
<login-config>
<auth-method>BASIC</auth-method>
</login-config>

<!-- and here we are just telling the system that there is an administrator role. You can have 1..n “security-role�s here.-->

<security-role>
<role-name>administrator</role-name>
</security-role>

</web-app>

Note that the role-name are set up to match the “cn” (common name) attribute in our LDAP tree.

That's it! Now when I brows to my administrator secured folder, I am prompted for a password:

And it will log me in and confirm I am in the administrator role.

This should be enough to get you rolling. Hope it was helpful.