This document covers some of the alternatives for configuring LDAP Realms in Apache Geronimo v2.1. In previous version of Apache Geronimo, ApacheDS was shipped along with Geronimo. To reduce the server footprint and exploit the Geronimo plugin architecture the LDAP server is currently available as an optional plugin install rather then being bundled with the Geronimo server for 2.1. Having said this, ApacheDS is not a requirement for configuring an LDAP Realm. However it will be practical for the purposes of this document to use a local LDAP server.

This document is organized in the following sections:

Installing ApacheDS plugin (optional)

If you choose to have your LDAP service provided by ApacheDS and running from within Geronimo you can install it very quickly by installing the plugin. ApacheDS 1.0 plugin for Geronimo is based on Apache Directory v1.5.1 and can be installed from either the command line or the Administration Console.

Install the plugin from the Geronimo Administration Console

• Login into the Geronimo Administration Console.
• Click on Plugins.
• Click on Update Repository List (optional if you are already pointing to http://geronimo.apache.org/plugins/geronimo-2.1).
• Click on Show Plugins in selected repository.
• Click on Apache Geronimo-Apache Directory Server Plugin 1.0 LDAP link , it should show up as installable.
• Scroll all the way to the bottom of the page and click Install.

The plugin will start automatically after the installation.

Install the plugin from the command line

From a command line window change directory to <geronimo_home>/bin and run the following comamnds:

• deploy search-plugins.
• Select the appropriate repository from the list, for this example select 1. http://geronimo.apache.org/plugins/geronimo-2.1/.
• From the following list identify Apache Geronimo-Apache Directory Server Plugin (1.0), this option will be presented under the LDAP category with an ID number.
• Enter that ID number for the LDAP plugin (e.g.78) and hit Enter.

The plugin will start automatically after the installation.

Deploying LDAP Realms

As always, you can choose to deploy assets like the security realm in this case from the Administration Console or the command line.

Using the Geronimo Administration Console

• Login into the Geronimo Administration Console.
• Click on Security Realms portlet.
• Click on Add new security realm.
• Enter a value for the Name of Security Realm:.
• Select LDAP Realm from the Realm Type: pull-down menu and click Next.
• Enter settings corresponding to your LDAP configuration and click Next.
• Select Advanced Settings as desired.
• To verify the settings are correct click Test a Login.
• Enter a known username and password then click Next.
• You should receive a confirmation message the connection succeded Login succeeded with 1 principals
• Click on Deploy Realm.

The LDAP Realm will deploy and you should be able to see it from the Security Realms portlet. From there you will be able to further edit the realm.

Note that in order to successfully connect and test this realm your LDAP server must be already configured/pre-loaded with the appropriate data. In other words, what you enter here matches with the one in the server. The LDAP server does not come with any preloaded sample data.

Using the command line deployer

As we mentioned, another way to deploy this configuration is via the Deployer tool from a command line. By deploying this way you will have to provide a deployment plan with all the configuraton information already there, there will not be an interactive menu this time.

The deployment itself is fairly simple, once you have the deployment plan sorted out run the following command from the <geronimo_home>/bin directory:

deploy --user system --password manager deploy <deployment_plan_home>/ldap_realm_plan.xml

LDAP Realm deployment plan

We mentioned that when using the command line deployer you will need to provide a deployment plan. The purpose of this section is to show you a sample deployment plan, for additional details refer to the ldap-sample-app - LDAP Sample Application section.

<module xmlns="http://geronimo.apache.org/xml/ns/deployment-1.2">
    <environment>
        <moduleId>
            <groupId>console.realm</groupId>
            <artifactId>LDAP_Test_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_Test_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_Test_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_Test_Realm</log:login-domain-name>
                    <log:login-module-class>org.apache.geronimo.security.realm.providers.LDAPLoginModule</log:login-module-class>
                    <log:option name="connectionUsername">uid=admin,ou=system</log:option>
                    <log:option name="userSearchSubtree">false</log:option>
                    <log:option name="roleSearchMatching">uniqueMember={0}</log:option>
                    <log:option name="roleBase">ou=users,ou=system</log:option>
                    <log:option name="connectionPassword">secret</log:option>
                    <log:option name="roleName">cn</log:option>
                    <log:option name="initialContextFactory">com.sun.jndi.ldap.LdapCtxFactory</log:option>
                    <log:option name="roleSearchSubtree">false</log:option>
                    <log:option name="connectionURL">ldap://localhost:10389</log:option>
                    <log:option name="userBase">ou=users,ou=system</log:option>
                    <log:option name="userSearchMatching">uid={0}</log:option>
                    <log:option name="authentication">simple</log:option>
                </log:login-module>
            </log:login-config>
        </xml-reference>
    </gbean>
</module>