Wiki Markup | ||
---|---|---|
{scrollbar} | ||
Note | ||
|
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.
Deploying ApacheDS to Geronimo
To deploy set up ApacheDS to Geronimo follow these stepsin Geronimo install the plugin as follows:
- Log into the Geronimo Console
- Click on
Creat/Install
under thePlugins
folder. - If there are no repositories in the list click the
Update Repository List
link. - Select a Repository to search.
- Click the
Search for Plugins
button. - In the list select
Apache Directory 0.92 for Geronimo (1.1)
- Click the
Continue
button on the next page. - Click the
Install Plugin
button on the next page.
All the needed components will be download and, if successful, you will see a message indicating that the plugin was installed. - 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. The following procedure skips discussion of the Advanced Configuration step.
From the Security Realms portlet:
- Click
Add new security realm
- Name the realm and select
LDAP Realm
in theRealm Type
box and then clickNext
At this point you are presented with a list of the LDAP Login Module's settings (see Ldap Login Module Configuration) - Enter settings corresponding to your LDAP configuration and click
Next
- To verify the settings are correct click
Test a Login
- 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. - 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:
No Format bgColor #000000 borderStyle solid
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
Anchor | ||||
---|---|---|---|---|
|
The following XML example uses parameters that are valid for the default ApacheDS server setup.
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
<?xml version="1.0" encoding="UTF-8"?> <module xmlns="http://geronimo.apache.org/xml/ns/deployment-1.1"> <environment> <moduleId> <groupId>groupName<<groupId>groupId</groupId> <artifactId>artifactName<<artifactId>artifactId</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:
No Format bgColor #000000 borderStyle solid
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
LDAPLoginModule Configuration
Anchor | ||||
---|---|---|---|---|
|
class = org.apache.geronimo.security.realm.providers.LDAPLoginModule
Info |
---|
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:
...
. |
...
LDAPLoginModule
...
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.
...
Options
Option | Description |
---|---|
initialContextFactory | The class name of the initial context factory. Usually |
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 | 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 |
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 |
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.