Within Apache Tomcat, a realm is (cite) a "database" of usernames and passwords that identify valid users of a web application (or set of web applications), plus an enumeration of the list of roles associated with each valid user. Learn more about them in the Realm Configuration HOW-TO from the Tomcat website.
In order to use Apache Directory Server (ApacheDS) as a realm, the straight forward approach is to use the JNDIRealm shipped with Tomcat. It can handle arbitrary LDAP servers, among them ApacheDS.
Because ApacheDS is 100% pure Java and embeddable, there is another option: Implement the Realm interface from Apache Tomcat and run within Tomcat. There are (at least) two interesting things about this approach:
While the first point promises some performance advantages, which are irrelevant in most situations (because LDAP servers like ApacheDS are optimized for read operations anyway), the second reason makes this approach a good option for development environments.
I have started a Realm implementation. A first version (proof of concepts) already works quite well. I have committed the sources here as a Maven2 project:
It builds a jar file which contains the Realm class. In order to use it, one has to copy it to the Tomcat server lib directory, along with the required ApacheDS and dependency jars.
Activation in Tomcat server.xml is simply
<Realm className="org.apache.directory.tomcatrealm.EmbeddedApacheDsRealm" />
You can use Studio to edit your users and groups after Tomcat startup; the embedded ApacheDS opens an LDAP port at 10389.
I will continue testing and will provide some documentation on the wiki later on. Some features like configuration (LDAP port, filter expressions for searches, ...) are still missing, but I think it looks quite promising.
Feel free to check it out and provide feedback. Further discussions about whether we provide this as official artifact will be on the dev-list, which you hopefully scan as well.