LDAP Configuration

This document attempts to document the configuration of the LDAP security module in Jetspeed. Out of the box, Jetspeed searches for user, group & role information in a relational database. However, it can also search this information in an LDAP directory.

Jetspeed stores its LDAP configuration in a Spring XML file called security-spi-ldap.xml

This XML file describes an object (used internally by Jetspeed) that contains LDAP configuration parameters. These configuration parameters are passed onto the object through constructor arguments:

<!-- The LDAP initial context factory. -->
<constructor-arg index="0">
  <value>com.sun.jndi.ldap.LdapCtxFactory</value>
</constructor-arg>

Each constructor argument contains an index to specify the correct order. The file defines the following arguments:

IndexNameExample
0Initial context factorycom.sun.jndi.ldap.LdapCtxFactory
1LDAP server hostlocalhost
2LDAP server port389
3Root contexto=sevenSeas
4The LDAP server root dnuid=admin,o=sevenSeas
5The LDAP server root passwordsecret
6The roles filter(objectclass=groupOfUniqueNames))
7The groups filter(objectClass=groupOfNames)
8The user filter(objectclass=inetorgperson)
9roleMembershipAttributesuniqueMember
10userRoleMembershipAttributes
11groupMembershipAttributesmember
12userGroupMembershipAttributes
13groupMembershipForRoleAttributesuniqueMember
14roleGroupMembershipForRoleAttributes
15defaultSearchBase
16roleFilterBaseou=Roles,ou=OrgUnit1
17groupFilterBaseou=Groups,ou=OrgUnit1
18userFilterBaseou=People,ou=OrgUnit1
19roleObjectClassestop,groupOfUniqueNames
20groupObjectClassestop,groupOfNames
21userObjectClassestop,person,organizationalPerson,inetorgperson
22roleIdAttributecn
23groupIdAttributecn
24userIdAttributeuid
25UidAttributeuid
26MemberShipSearchScope1
27roleUidAttributecn
28groupUidAttributecn
29userUidAttributeuid
30roleObjectRequiredAttributeClassesuniqueMember
31groupObjectRequiredAttributeClassesmember
32userAttributessn={u},cn={u}
33roleAttributessn={u}
34groupAttributessn={u}
35userPasswordAttributepassWord
36knownAttributescn,sn,o,uid,ou,objectClass,userPassword,member,uniqueMember,memberOf

Configuring Jetspeed 2 to Use LDAP

Configuring jetspeed for LDAP usage is simply a matter of having the proper configuration files in place. These configuration files are to be placed in the WEB-INF/assembly folder of the expanded jetspeed WAR.

The following files need to be copied into that directory if you want to connect Jetspeed2 to an LDAP server.

  • security-spi-ldap.xml : Provides the configuration information for LDAP binding, explained in detail below.
  • security-spi-ldap-atn.xml : Provides the SPI configuration for authentication. It replaces the default implementations of the CredentialHandler and UserSecurityHandler with an LDAP specific implementation.
  • security-spi-ldap-atz.xml : Provides the SPI configuration for authorization. It replaces the default implementations of the RoleSecurityHandler, GroupSecurityHandler and SecurityMappingHandler with an LDAP specific implementation.

The default authentication and authorization SPI configurations (the files called security-spi-atn.xml and security-spi-atz.xml) need to be removed from that assembly directory.

In the Jetspeed source tree the examples ldap configuration files can be found in:

${jetspeed-source-home}/components/security/etc/

If your application is deployed in Tomcat, the target assembly directory is located at:

${tomcat-home}/webapps/jetspeed/WEB-INF/assembly/

Furthermore, the source tree of the Jetspeed security component provides several tests using different configurations as well as ldiff sample data for testing the ApacheDS, OpenLDAP, Domino and sunDS LDAP servers. These are located at:

${jetspeed-source-home}/components/security/src/test/JETSPEED-INF/directory/config/

We?ll discuss the security-spi-ldap.xml file in detail below.

LDAP Connection properties

One of the first Jetspeed needs to know is how it to connect to the directory store.

This is done by providing the following properties:



initialContextFactory

The initial context factory

<constructor-arg index="0">
  <value>com.sun.jndi.ldap.LdapCtxFactory</value>
</constructor-arg>



ldapServerName

The name of the LDAP server

<constructor-arg index="1">
  <value>localhost</value>
</constructor-arg>



ldapServerPort

The port of the LDAP server

<constructor-arg index="2">
  <value>389</value>
</constructor-arg>



rootContext

The root context of the LDAP server

<constructor-arg index="3">
  <value>o=sevenSeas</value>
</constructor-arg>



rootDn

The username

<constructor-arg index="4">
  <value>uid=admin,ou=system</value>
</constructor-arg>



rootPassword

The password

<constructor-arg index="5">
  <value>secret</value>
</constructor-arg>

Validate the connection using an LDAP browser:



LDAP Object Filters

A directory service can store any type of object anywhere. As Jetspeed needs to work with roles, groups and users that are defined within the directory, it needs some help in finding them.

The following 3 properties define how Jetspeed will lookup Roles, Groups and Users from the directory store.

  • RoleFilter
  • GroupFilter
  • UserFilter

Property values must be valid objectClassses that are defined in the LDAP schema.

Most LDAP vendors usually expose their schema through an LDIF file that defines every attribute and objectclass available in the directory store.

A configuration based on Lotus Domino might look like this

RoleFilter=(&(objectclass=groupOfUniqueNames)(!(objectClass=dominoGroup)))
GroupFilter=(objectclass=dominoGroup)
UserFilter=(objectclass=dominoPerson)

Domino uses the dominoGroup objectClass to define a group, dominoPerson to define a user, and groupOfUniqueNames to define a role. Since group also has the groupOfUniqueNames as an object class, we need to define a filter for the roles, so that it will only pick up roles. If we had defined the RoleFilter as being (objectclass=groupOfUniqueNames), then the filter would have also picked up the groups.



RoleFilter

This property tells Jetspeed that roles can be recognized by looking for an objectClass attribute with value groupOfUniqueNames.

<constructor-arg index="6">
  <value>=(objectclass=groupOfUniqueNames)</value>
</constructor-arg>



GroupFilter

This property tells Jetspeed that groups can be recognized by looking for an objectClass attribute with value groupOfNames.

<constructor-arg index="7">
  <value>=(objectclass=groupOfUniqueNames)</value>
</constructor-arg>



UserFilter

This property tells Jetspeed that users can be recognized by looking for an objectClass attribute with value organizationalPerson.

<constructor-arg index="8">
  <value>=(objectclass= organizationalPerson)</value>
</constructor-arg>

Alongside these filters, we can also define a filter base for each of those objects (roles, groups and users).

Group/Role membership

In LDAP there are basically 2 ways to define group & role membership (the fact that a user belongs to a group or a role):

  • The user object has an attribute that specifies the groups he is a member of. This is usually done through a memberOf attribute. Microsoft Active Directory and Sun Directory Server use the memberOf and nsrole attribute on the user object.
  • The group/role object contains the group membership information via a multi-valued attribute. No attributes are put on the user to specify membership. Each group/role object has a member list that contains the users belonging to the group

Jetspeed supports both models.

The primary tasks concerning membership of an LDAP are

  • Determining if a user is part of a particular group/role
  • Obtain a list of users belonging to a particular group/role

The 2 models we just covered have an impact on how these tasks are performed

  • Attributes on user object
    • Determining if a user is part of a particular group/role:
      • lookup the membership attribute (ex: memberOf) on the user object for a particular group/role
    • Obtain a list of users belonging to a particular group/role:
      • iterate over the all users, and check their memberOf attribute values for the group
  • Attributes on group/role object
    • To determine if a user is part of a particular group:
      • search the member list on the group for the user
    • To determine the users belonging to a particular group:
      • iterate over the member list on the group

We?ll now discuss in detail how group/role membership can be configured.

Role membership

As already discussed, Jetspeed supports 2 models when it comes to Role membership:

  1. Putting the attributes on the user
  2. Putting the attributes on the role

Jetspeed requires that 1 of 2 properties is set with a value to determine the model:

  • RoleMembershipAttributes
  • UserRoleMembershipAttributes


RoleMembershipAttributes

In order to store role membership on the role, we?ll set the RoleMembershipAttributes attribute by specifying the attribute on the role object that contains the membership information. We don?t provide a value for the UserRoleMembershipAttributes property.

<constructor-arg index="9">
  <value>member</value>
</constructor-arg>

This will make sure that the member attribute is set on the role object, as can be seen in the following screenshot. In the next example, the RoleMembershipAttribute will be blank, so the attributes will be on the user level.

In the screenshot below, we have a Role object defined by

cn=Role3,ou=Roles,ou=OrgUnit1,o=sevenSeas

The role contains a member attribute, listing all users belonging to that role.



A role with 2 members



The value of the member attribute is the fully qualified DN of the user (including the root context). As you can see, the user doesn't contain any attributes with regards to role membership.



A user



When this attribute is set, Jetspeed will determine the roles for a particular user by performing the following query:

(&(member=cn=user1,ou=people,ou=orgunit1,o=sevenSeas)(objectclass=groupOfNames))

This search filter will return any number of Roles in the directory. The next step for Jetspeed is to identifiy these roles internally. In order to uniquely identify a role, it will use the RoleIdAttribute.

In the example above, cn=Role1 would have been amongst the searchresult. Jetspeed will use the RoleIdAttribute to pickup the role name.



UserRoleMembershipAttributes

In order to store role membership on the user, we?ll set the UserRoleMembershipAttributes attribute by specifying the attribute on the user object that contains the membership information. We don?t provide a value for the RoleMembershipAttributes property.

<constructor-arg index="10">
  <value>memberOf</value>
</constructor-arg>

This will make sure that for each role the user belongs to, the memberOf attribute is set on the user object, as can be seen in the following screenshot:



User belonging to 4 different roles



The value of the memberOf attribute is the fully qualified DN of the role (including the root context). It is a multi valued attribute, so a user can have zero or more memberOf attribute values.

As you can see, the user belongs to a role defined by

cn=role1,ou=Roles,OrgUnit1,o=sevenSeas.

In order to resolve role membership, Jetspeed will search the directory for roles by using the following filter:

# define the filters needed to search for roles/groups/users
RoleFilter=(objectclass=groupOfUniqueNames)

As you can see in the screenshot, cn=role1,o=sevenSeas corresponds to an object representing a role.

Notice the empty uniqueMember attribute. Most LDAP schemas force you to have a uniqueMember attribute on a groupOfUniqueNames object. Since Jetspeed needs to be able to create roles (that are empty upon creation), an empty uniqueMember attribute needs to be set. This is configurable by Jetspeed through the RequiredAttributeClasses property.



A role without any members



Group membership

As already discussed, Jetspeed supports 2 models when it comes to Group membership:

  1. Putting the attributes on the user
  2. Putting the attributes on the group

Jetspeed requires that 1 of 2 properties is set with a value to determine the model:

  • GroupMembershipAttributes
  • UserGroupMembershipAttributes


GroupMembershipAttributes

In order to store group membership on the group, we'll set the GroupMembershipAttributes attribute by specifying the attribute on the group object that contains the membership information. We don?t provide a value for the UserGroupMembershipAttributes property.

<constructor-arg index="11">
  <value>uniqueMember</value>
</constructor-arg>

This will make sure that the uniqueMember attribute is set on the group object, as can be seen in the following screenshot. In the previous example, the GroupMembershipAttributes was blank, so instead the UserGroupMembershipAttributes was used on the user level:





The value of the uniquemember attribute is the fully qualified DN of the user (including the root context). As you can see, the user doesn?t contain any attributes with regards to group membership.





UserGroupMembershipAttributes

In order to store group membership on the user, we?ll set the UserGroupMembershipAttributes attribute by specifying the attribute on the user object that contains the membership information. We don?t provide a value for the GroupMembershipAttributes property.

<constructor-arg index="12">
  <value>memberOf</value>
</constructor-arg>

This will make sure that the memberOf attribute is set on the user object, as can be seen in the following screenshot.

Only one of those parameters can be filled in. If the GroupMemberShipAttributes is set, Jetspeed assumes that the attribute to determine group membership is on the group object.



User belonging to 2 different roles



The value of the memberOf attribute is the fully qualified DN of the role (including the root context). It is a multi valued attribute, so a user can have zero or more memberOf attribute values. In the screenshot above, we can see that user1 belongs to 2 roles.

As you can see, the role is defined in cn=role1,o=sevenSeas. (notice the empty uniqueMember attribute).



Role definition



Group membership (roles)

Besides storing users in a group, Jetspeed also supports storing roles into groups.

Again, just like with the basic group membership for users, Jetspeed supports 2 models when it comes to Group membership for roles:

  1. Putting the attributes on the role
  2. Putting the attributes on the group

Jetspeed requires that 1 of 2 properties is set with a value to determine the model:

  • GroupMembershipForRoleAttributes
  • RoleGroupMembershipForRoleAttributes


GroupMembershipForRoleAttributes

In order to store group membership on the group, we?ll set the GroupMembershipAttributes attribute by specifying the attribute on the group object that contains the membership information. We don?t provide a value for the UserGroupMembershipAttributes property.

<constructor-arg index="13">
  <value>uniqueMember</value>
</constructor-arg>

This will make sure that the uniqueMember attribute is set on the group object, as can be seen in the following screenshot. In the previous example, the GroupMembershipAttributes was blank, so instead the UserGroupMembershipAttributes was used on the user level.





The value of the uniquemember attribute is the fully qualified DN of the user (including the root context). As you can see, the user doesn?t contain any attributes with regards to group membership.





RoleGroupMembershipForRoleAttributes

In order to store group membership on the user, we?ll set the UserGroupMembershipAttributes attribute by specifying the attribute on the user object that contains the membership information. We don?t provide a value for the GroupMembershipAttributes property.

<constructor-arg index="14">
  <value>memberOf</value>
</constructor-arg>

This will make sure that the memberOf attribute is set on the user object, as can be seen in the following screenshot.





The value of the uniquemember attribute is the fully qualified DN of the user (including the root context). As you can see, the user doesn?t contain any attributes with regards to group membership.





Only one of those parameters can be filled in. If the GroupMemberShipAttributes is set, Jetspeed assumes that the attribute to determine group membership is on the group object.



User belonging to 2 different roles



The value of the memberOf attribute is the fully qualified DN of the role (including the root context). It is a multi valued attribute, so a user can have zero or more memberOf attribute values. In the screenshot above, we can see that user1 belongs to 2 roles.

As you can see, the role is defined in cn=role1,o=sevenSeas. (notice the empty uniqueMember attribute).



Role definition



DefaultSearchBase

Jetspeed allows you to define a default search base that will be used to search the directory

<constructor-arg index="15">
  <value></value>
</constructor-arg>

LDAP Object Filter base

Jetspeed allows you to define the search base that will be applied to queries for roles, groups and users.

Roles, groups and user are typically stored in well-defined containers within the LDAP structure.

  • Roles can be stored in ou=Roles,ou=OrgUnit1
  • Groups can be stored in ou=Groups,ou=OrgUnit1
  • Users can be stored in ou=People,ou=OrgUnit1

This allows you to have the following structure in your LDAP schema. Notice how there are many organizational units within the o=sevenSeas schema. Jetspeed will limit its search scope on the LDAP to the property values defined above. This means that only roles, groups and people within OrgUnit1 will be used by Jetspeed.





So, together with the object filers (RoleFilter, GroupFilter, UserFilter), Jetspeed will be able to locate the roles, groups and users within the directory.

Using these properties, Jetspeed will also create roles, groups and users using the provided ObjectClasses.



RoleFilterBase

Using the property value below, Jetspeed will search for roles in the ou=Roles,ou=OrgUnit subtree.

<constructor-arg index="16">
  <value>ou=Roles,ou=OrgUnit1</value>
</constructor-arg>





GroupFilterBase

Using the property value above, Jetspeed will search for groups in the ou=Groups,ou=OrgUnit subtree.

<constructor-arg index="17">
  <value>ou=Groups,ou=OrgUnit1</value>
</constructor-arg>





UserFilterBase

Using the property value above, Jetspeed will search for users in the ou=People,ou=OrgUnit subtree.

<constructor-arg index="18">
  <value>ou=People,ou=OrgUnit1</value>
</constructor-arg>



LDAP Object classes

Jetspeed allows you to define the ObjectClasses that are needed to create roles, groups and users through the following properties

  • RoleObjectClasses
  • GroupObjectClasses
  • UserObjectClasses

Through the administrative interface, Jetspeed allows an administrator to create roles, groups and users. Each directory server has its own way of defining a role, group or user. Some of the LDAP vendors use proprietary ObjectClasses to define these objects (for example Domino LDAP server uses an dominoGroup objectClass to define a group).

Using these properties, Jetspeed will create roles, groups and users using the provided ObjectClasses.



RoleObjectClasses

<constructor-arg index="19">
  <value>top,groupOfNames</value>
</constructor-arg>

Using the settings above, roles will be created like this



Notice how all of the objectClasses defined by the RoleObjectClasses attribute have been created in the LDAP



GroupObjectClasses

<constructor-arg index="20">
  <value>top,groupOfUniqueNames</value>
</constructor-arg>

Using the settings above, groups will be created like this



Notice how all of the objectClasses defined by the GroupObjectClasses attribute have been created in the LDAP



UserObjectClasses

<constructor-arg index="21">
  <value>top,groupOfUniqueNames</value>
</constructor-arg>

Using the settings above users will be created like this



Notice how all of the objectClasses defined by the UserObjectClasses attribute have been created in the LDAP

Naming Attributes

  • RoleIdAttribute
  • GroupIdAttribute
  • UserIdAttribute

The attributes above allow you to define the naming attribute for roles / groups and users. When an object is created in the directory, a naming attribute needs to be specified. The naming attribute is the attribute that uniquely defines the object within its subdirectory.

In the screenshot below, you can see that the admin user in OrgUnit1/People is defined by cn=admin.

cn is the naming attribute for the user object, as no 2 admin users can exist in the OrgUnit1/People subdirectory





By changing the property, you can control the way Jetspeed creates user objects.



RoleIdAttribute

<constructor-arg index="22">
  <value>cn</value>
</constructor-arg>



GroupIdAttribute

<constructor-arg index="23">
  <value>cn</value>
</constructor-arg>



UserIdAttribute

<constructor-arg index="24">
  <value>uid</value>
</constructor-arg>

In the screenshot below, users have the uid attribute as their naming attribute



UserId Attribute

When Jetspeed attempts to find a user, it does so based on the userId provided by the user in the login screen. This userId needs to be defined on the object through a specific attribute. Most LDAP servers have a uid attribute that defines the username of the user in the LDAP.

When Jetspeed builds a userPrincipal internally, it will use the attribute corresponding to the value of the userUidAttribute.





userUidAttribute

<constructor-arg index="25">
  <value>cn</value>
</constructor-arg>

This property is used in conjunction with the UidAttribute

UserIdAttribute=cn
UidAttribute=uid

membershipSearchScope

Jetspeed allows you to customize the search scope when it comes to membership

<constructor-arg index="26">
  <value>cn</value>
</constructor-arg>

RequiredAttributeClasses

Some ObjectClasses force you to add specific attributes on the object before storing it in the directory. Jetspeed allows you to specify these attributes for roles and groups through the following properties

  • roleObjectRequiredAttributeClasses
  • roleObjectRequiredAttributeClasses

For example, most LDAP schemas force you to have a uniqueMember attribute on a groupOfUniqueNames object.

Since Jetspeed needs to be able to create empty roles through the administrative console, an empty uniqueMember attribute needs to be set upon role creation.

This is handled internally by Jetspeed and can be customized by setting the groupObjectRequiredAttributeClasses property.



roleObjectRequiredAttributeClasses

The following property specifies that if a role is created, an empty member attribute will be created on the role object in order to comply with the LDAP schema.

<constructor-arg index="30">
  <value>member</value>
</constructor-arg>



groupObjectRequiredAttributeClasses

The following property specifies that if a group is created, an empty uniqueMember attribute will be created on the group object in order to comply with the LDAP schema.

<constructor-arg index="31">
  <value>uniqueMember</value>
</constructor-arg>

LDAP Object attributes

Jetspeed has an administrative console that allows an administrator to create groups, roles and users in the directory. The Jetspeed LDAP configuration has 3 properties that can manipulate the creation of those objects

  • userAttributes
  • roleAttributes
  • groupAttributes

Each property accepts a comma separated list of attributes. Placeholders can be used in the attribute value.



userAttributes

For example, the following userAttributes value will make sure that when Jetspeed creates a user in the directory, the sn, cn and uid attribute will be created containing the username of the user.

<constructor-arg index="32">
  <value>sn={u},cn={u}</value>
</constructor-arg>



roleAttributes

For example, the following roleAttributes value will make sure that when Jetspeed creates a user in the directory, the cn attribute will be created containing the username of the user.

<constructor-arg index="33">
  <value>cn={u}</value>
</constructor-arg>



groupAttributes

For example, the following groupAttributes value will make sure that when Jetspeed creates a user in the directory, the cn attribute will be created containing the username of the user.

<constructor-arg index="34">
  <value>cn={u}</value>
</constructor-arg>

LDAP Password attributes

During runtime, Jetspeed needs to read the password that is associated with a user. Jetspeed needs to know the attribute on the user object that contains the password. The userPasswordAttribute property defines the LDAP attribute that contains the password of the user

<constructor-arg index="35">
  <value>cn={u}</value>
</constructor-arg>

Known Attributes

When Jetspeed performs LDAP queries, we need to specify the set of attributes that we want to return. This is done by specifying a comma separated value of LDAP attributes in the knowAttributes property

<constructor-arg index="36">
  <value>cn,sn,o,uid,ou,objectClass,userPassword,member,uniqueMember,memberOf</value>
</constructor-arg>