Database (SQL) Realm

Administering security realms

A guide to deploying LDAP realms in Geronimo. The samples reflect settings that are valid for the default ApacheDS setup.

ApacheDS

Geronimo can be configured to use the Apache Directory Server for its directory service. As of Geronimo 1.1 ApacheDS is not installed by default. If you do not have ApacheDS installed in your environment here are a serie of quick steps to install it as a Geronimo Plugin.

Installing ApacheDS in Geronimo

To set up ApacheDS in Geronimo install the plugin as follows:

1. Log into the Geronimo Console
2. Click on Create/Install under Plugins on the left menu.
3. If there are no repositories in the list click the Update Repository List link.
4. Select a Repository to search.
5. Click the Search for Plugins button.
6. In the list select Apache Directory 0.92 for Geronimo (1.2)
7. Click the Continue button on the next page.
8. Click the Install Plugin button on the next page.
   All the needed components will be downloaded and, if successful, you will see a message indicating that the plugin was installed.
9. Click the Start button to start ApacheDS

Deploying LDAP Realms

Using the Security Realms Portlet

LDAP Security Realms can be deployed easily from within the Geronimo Console using the Security Realms portlet.

From the Security Realms portlet:

1. Click Add new security realm.
2. Name the realm and select LDAP_Realm in the Realm Type box and then click Next.
   At this point you are presented with a list of the LDAP Login Module's settings (see Ldap Login Module Configuration).
3. Enter settings corresponding to your LDAP configuration and click Next.
4. Select Advanced Settings as desired.
5. To verify the settings are correct click Test a Login.
6. Enter a known username and password then click Next.
   If the settings are correct you will see a page displaying the the Principles retrieved for the user.
7. Click Deploy Realm.
   The LDAP realm is ready for use and should be listed in your Security Realms portlet view.

Using the Command Line Deployer

An LDAP Realm can also be deployed from the command line using the Deployer tool. The configuration options are set in the first ldap-login gbean in the sample file. For configuration option details see LDAP Login Module Configuration.

To deploy the ldap-realm.xml run the following command from the <geronimo_home>/bin directory:

java -jar deployer.jar --user system --password manager deploy <ldap_home>/<filename>.xml

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

E:\geronimo\bin>java -jar deployer.jar --user system --password manager deploy e:/ldap-jetty/ldap-realm.xml
Deployed <groupId>/<artifactId>/<version>/car

LDAP Deployment XML Example

The following XML example uses parameters that are valid for the default ApacheDS server setup.

<?xml version="1.0" encoding="UTF-8"?>
<module xmlns="http://geronimo.apache.org/xml/ns/deployment-1.2">
	<environment>
		<moduleId>
			<groupId>samples</groupId>
			<artifactId>ldap-realm-1</artifactId>
			<version>1.2</version>
		</moduleId>

		<dependencies>
			<dependency>
				<groupId>org.apache.geronimo.configs</groupId>
				<artifactId>j2ee-security</artifactId>
				<type>car</type>
			</dependency>
		</dependencies>

	</environment>
	
	<gbean name="ldap-login"
		class="org.apache.geronimo.security.jaas.LoginModuleGBean">
		<attribute name="loginModuleClass">org.apache.geronimo.security.realm.providers.LDAPLoginModule</attribute>
		<attribute name="serverSide">true</attribute>
		<attribute name="options">
			initialContextFactory=com.sun.jndi.ldap.LdapCtxFactory
                        connectionURL=ldap://localhost:1389
                        connectionUsername=uid=admin,ou=system
                        connectionPassword=secret
                        connectionProtocol=
                        authentication=simple
                        userBase=ou=users,ou=system
                        userSearchMatching=uid={0}
                        userSearchSubtree=false
                        roleBase=ou=groups,ou=system
                        roleName=cn
                        roleSearchMatching=(uniqueMember={0})
                        roleSearchSubtree=false
                        userRoleName=
		</attribute>
		<attribute name="loginDomainName">ldap-realm-1</attribute>
	</gbean>
	
	<gbean name="ldap-realm-1" class="org.apache.geronimo.security.realm.GenericSecurityRealm">
		<attribute name="realmName">ldap-realm-1</attribute>
		<reference name="LoginModuleConfiguration">
			<name>ldap-login</name>
		</reference>
		<reference name="ServerInfo">
		<name>ServerInfo</name>
		</reference>
		
		<reference name="LoginService">
			<name>JaasLoginService</name>
		</reference>
	</gbean>
	
	<gbean name="ldap-login" class="org.apache.geronimo.security.jaas.JaasLoginModuleUse">
		<attribute name="controlFlag">REQUIRED</attribute>
		<reference name="LoginModule">
			<name>ldap-login</name>
		</reference>
	</gbean>
</module>

LDAPLoginModule Configuration

The following section is a reference for users needing to deploy custom LDAP realms and outlines the LDAP Login Module configuration parameters as well as different possible configurations for retrieving LDAP user roles.

Tip: The key to working with the LDAP module is: KNOW YOUR LDAP SCHEMA.

LDAPLoginModule Options

Retrieving LDAP User Roles

The LDAPLoginModule can be configured to find user roles (group memberships) using two different methods:

Find the roles using a group entry's attribute that contains user members (e.g. a member attribute).

To use this method the roleName and roleSearchMatching options must be set. The LDAPLoginModule will perform an LDAP search using the roleSearchMatching filter to search for the authenticating user's distinguished name within each group entry's roleName attribute. To skip this method the roleName option MUST be left unset. If the roleName option is set and the roleSearchMatching option is left unset then the LDAPLoginModule will attempt to perform the search and throw an exception.

. Find the roles using a user entry's attribute that contains the groups a user is a member of (e.g. a (memberOf* attribute).

To use this method the userRoleName option must be set with the name of the user entry's attribute that contains the group membership list. To skip this method the userRoleName should be unset.