LDAP Realm

Geronimo Console Deployment

LDAP Deployment from the Geronimo console currently fails with an Error: Unable to initialize LoginModule: null. Until this is resolved use the Deployer Tool to deploy LDAP realms.

LDAP Deployment XML Example

<?xml version="1.0" encoding="UTF-8"?>
<module xmlns="http://geronimo.apache.org/xml/ns/deployment-1.1">
	<environment>
		<moduleId>
			<groupId>groupName</groupId>
			<artifactId>artifactName</artifactId>
			<version>1.0</version>
		</moduleId>
		<dependencies>
			<dependency>
				<groupId>geronimo</groupId>
				<artifactId>j2ee-security</artifactId>
				<version>1.1</version>
				<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</attribute>
	</gbean>
	
	<gbean name="ldap-realm" class="org.apache.geronimo.security.realm.GenericSecurityRealm">
		<attribute name="realmName">ldap-realm</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>

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 <groupName>/<artifactName>/<version>/car

LDAPLoginModule Configuration

class = org.apache.geronimo.security.realm.providers.LDAPLoginModule

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

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.

LDAPLoginModule Options

Option	Description
initialContextFactory	The class name of the initial context factory. Usually `com.sun.jndi.ldap.LdapCtxFactory`.
connectionURL	The LDAP connection URL, such as ldap://localhost:1389 . Note that the usual LDAP port is 389.
connectionUsername	The DN used by the login module itself for authentication to the directory server.
connectionPassword	The credential (password) that is used by the login module to authenticate itself to the directory server.
connectionProtocol	The security protocol to use. This value is determined by the service provider. This can be left blank. An example would be SSL.
authentication	The security level to use. Its value is one of the following strings: "none", "simple", "strong". If this property is unspecified the behavior is determined by the service provider.
userBase	The base DN for the group membership search.
userSearchMatching	The filter specification for how to search for user entries. RFC 2254 filters are allowed. In addition you can pass a parameter to the search filter instead of the literal value. For example: this is RFC 2254 filter spec: (cn=Babs Jensen). If you want to parameterize the value of the CN attribute type, specify (cn = {0}). This integer refers to the parameter number. Parameter value is the user name. This query must return exactly one object.
userSearchSubtree	Defines the directory search scope for user entries. If set to true, the directory search scope is SUBTREE, if set to false, the directory search scope is ONE-LEVEL.
roleBase	The base DN for the group membership search.
roleName	The LDAP attribute that identifies the group name in the entry returned from the group membership search. Note that group membership query is defined by the `roleSearchMatching` parameter. Often group name parameter is cn.
roleSearchMatching	The filter specification for how to search for roles. RFC 2254 filters are allowed. In addition you can pass parameters to the search filter instead of the literal value. For example: (uniqueMember = {0}). This integer refers to the parameter number. This parameter is the DN of the authenticated user. Note that if role membership for the user is defined in the member-of-like attribute (see `userRoleName` parameter) you may not need to search for group membership with the query.
roleSearchSubtree	Defines the directory search scope for roles. If set to true, the directory search scope is SUBTREE, if set to false, the directory search scope is ONE-LEVEL.
userRoleName	The group membership attribute of a user entry. Different LDAP schemas represent user group membership in different ways. Examples are: memberOf, isMemberOf, member, etc. Values of these attributes are identifiers of groups that a user is a member of. For example, if you have: memberOf: cn=admin,ou=groups,dc=foo, specify memberOf as the value for the `userRoleName` attribute. Be aware of the relationship between this parameter and roleSearchMatching query. Often times they will return the same data.

Child pages