...

Starting the LDAP server

If you installed the Apache Geronimo-Apache Directory Plugin it should have been started as part of the installation. You can verify that it is started from command line using the deployer tool or via the Geronimo Administration Console.

...

Alternatively, if you are using an external LDAP server, start that server in the normal manner and follow the remaining instructions here.

Back to Top

Source Code for Sample

You can checkout the source code of this sample from SVN:

...

At this point you can choose to install an LDAP client and import/export an .ldif file to a directory server. However, this is not required. Directions are provided if you choose to not install an LDAP client.

Back to Top

Add LDAP entries

Ensure that Geronimo is up and running and the Directory service is started.

To add entries manually

When you installed the Apache Geronimo-Apache Directory plugin you may have noticed a message on the console similar to the following:

...

This is because the directory server does not yet have any content. You can manually add the content necessary for the sample by including the ldap-sample.ldif from the sample source in the location specified in the message (<geronimo-home>/var/ldif/) and restarting the Geronimo server or optionally just the directory configuration in the server.

To add entries using an LDAP client

Start your LDAP client and create a new connection profile with the following values:

...

Once the file is imported you should get a confirmation that five entries were successfully imported.

Back to Top

Deploy the LDAP realm

One way to install the LDAP realm for the sample is by installing a Geronimo plugin created for this purpose. You can do this by navigating in the Geronimo Administration Console to Applications -> Plugins. Once in the view, updating the repository list (which should add http://geronimo.apache.org/plugins/geronimo-2.1/ if not already included), selecting the referenced repository, and then select Show Plugins in selected repository to display the list of all possible plugins in this directory. Locate the Geronimo Configs :: LDAP Sample Security Realm and then install it. However, this process hides many of the details of creating and installing the realm. For those details refer to the next section.

LDAP realm deployment details

The LDAP sample application provides a security realm that needs to be deployed before the deployment of the application itself. This realm is located in <ldap_home>/ldap-realm.xml and the content is illustrated in the following example.

...

Once deployed you should see a confirmation message similar to the following example:

D:\geronimo-tomcat6-jee5-2.0\bin>deploy deploy \samples\2.0\ldap-sample-app\ldap-realm.xml
Using GERONIMO_BASE:   D:\geronimo-tomcat6-jee5-2.0
Using GERONIMO_HOME:   D:\geronimo-tomcat6-jee5-2.0
Using GERONIMO_TMPDIR: D:\geronimo-tomcat6-jee5-2.0\var\temp
Using JRE_HOME:        C:\Java\jdk1.5.0_06\\jre
    Deployed console.realm/LDAP_Sample_Realm/1.0/car

For further details refer to the LDAP Realm section.

Creating and Installing the LDAP Sample Application

One way to install the LDAP sample application is by installing a Geronimo plugin created for this purpose. You can do this by navigating in the Geronimo Administration Console to Applications -> Plugins. Once in the view, updating the repository list (which should add http://geronimo.apache.org/plugins/geronimo-2.1/ if not already included), selecting the referenced repository, and then select Show Plugins in selected repository to display the list of all possible plugins in this directory. Locate the Geronimo Configs :: LDAP Sample for Tomcat or Geronimo Configs :: LDAP Sample for Jetty (depending upon you Geronimo service choice) and then install it. However, this process hides many of the details of creating and installing the sample. For those details refer to the next section.

Deployment plans

The deployment plans are located in the <ldap_home>/WEB-INF directory. Clearly, geronimo-web.xml is the Geronimo specific deployment plan. It provides the details on what security realm to use and user role mappings as well as the Geronimo specific namespace used to identify the elements in the security configuration. Common to other types of applications, not just security, the deployment plan also provides the main namespace for the deployment plan, a module identification (optional), a parent module configuration ID (also optional) and a context root. The following example illustrates the Geronimo specific deployment plan.

...

Note that these role mappings will be overridden by the actual roles (what users pertaining to what groups) defined in the LDAP server. Ultimately it is the realm defined in the application deployment plan who determines the validation method. Nevertheless, for this particular example, you still need to define principals and role mappings as determined in the XML schemas

Back to Top

The web.xml deployment descriptor shown in the following example (also located in the <ldap_home>/WEB-INF diretory) adds security constraints based on the location of the files.

<?xml version="1.0" encoding="ISO-8859-1"?>
<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">

    <welcome-file-list>
        <welcome-file>index.html</welcome-file>
    </welcome-file-list>

    <security-constraint>
        <web-resource-collection>
            <web-resource-name>Admin Role</web-resource-name>
            <url-pattern>/protect/*</url-pattern>
        </web-resource-collection>
        <auth-constraint>
            <role-name>content-administrator</role-name>
        </auth-constraint>
    </security-constraint>
    
    <security-constraint>
        <web-resource-collection>
            <web-resource-name>No Access</web-resource-name>
            <url-pattern>/forbidden/*</url-pattern>
        </web-resource-collection>
        <auth-constraint/>
    </security-constraint>

    <login-config>
        <auth-method>FORM</auth-method>
            <realm-name>ldap-realm-1</realm-name>
            <form-login-config>
                <form-login-page>/auth/logon.html?param=test</form-login-page>
                <form-error-page>/auth/logonError.html?param=test</form-error-page>
            </form-login-config>
    </login-config>

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

</web-app>

Back to Top

Package the sample application

Now that all the elements have been identified, it is necessary to package the sample application in a Web application Archive (.war). Open a command line window, change directory to <ldap_home> and run the following command:

...

This command will package all the existing files and directories inside <ldap_home>. Although not needed inside the .war file, the ldap-realm.xml and ldap-sample.ldif files will also be included.

Back to Top

Deploy the sample application

To deploy the LDAP sample application make sure the Geronimo server is up and running. Open a command line window, change directory to <geronimo_home>/bin and run the following command:

java -jar deployer.jar --user system --password manager deploy <ldap_home>/ldap-demo.war

Testing the sample application

Once the Web application is successfully deployed you should see a confirmation message similar as the one shown in the following example:

...

To further test this example you could now try the different users provided in the ldap-sample.ldif, use your LDAP client and add/remove users from the different groups. You will notice the changes immediatly (you may need to close your web browser).

Back to Top