Integrating JBoss with Active Directory

Resolving The Problem

Before we get started we will need a few pieces of information. The most vital is Light Directory Interchange Format (LDIF) exports of some objects in your active directory. The full documentation of which is documented here: http://wiki.jboss.org/wiki/Wiki.jsp?page=LdapExtLoginModule.

Here is what we will need:

1. An LDIF export of your Bind User. This is the user that jBoss will be using to log into your LDAP server. This user does not have to be an LDAP admin user, but it should have full query rights to your LDAP server. It should not be a regular user as the password should not change frequently. If the password does change you will need to edit your jBoss config files and restart your jBoss servers.
2. An LDIF export of a user that you plan to have use your jBoss / TeamWorks server
3. An LDIF export of a group the user in #2 is a member of
4. The host and port of the LDAP server

Here is an abbreviated LDIF from the Lombardi development LDAP server's bind user :

dn: CN=foo, CN=Users, DC=devlombardi,DC=com
displayName: foo bar
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: user
cn: foo bar
sAMAccountName: fbar
name: foo bar

The dn is what we are interested in. We will be using this field in the bindDN field of the login-config.xml file.

Here is an abbreviated LDIF of a user that will be using teamworks:

dn: CN=dparish, OU=Users, OU=External, DC=devlombardi,DC=com
memberOf: CN=ACME,OU=Groups,OU=External, DC=devlombardi,DC=com
memberOf: CN=All External Support Users,OU=Groups,OU=External, DC=devlombardi,DC=com
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: user
name: dparish
sn: David Parish
cn: dparish
displayName: David Parish
sAMAccountName: dparish

We need the dn here as well. What we are interested in is the container the user is in. An OU, an O and a DC are all LDAP containers. In this case the dparish user is in the Users OU whose full name is: "OU=Users, OU=External, DC=devlombardi,DC=com". We will be using this field in the baseCtxDN of the login-config.xml. By specifying this we are saying we ONLY want users in the Users Organizational Unit. (It will also find users in child OU's). If you plan on opening up to a wider collection of users, let's not worry about that right now, let's just use this OU. Once you know it works, you can open it up to more users by choosing a parent container.

Here is an abbreviated LDIF of a group that user is in:

dn: CN=ACME, OU=Groups, OU=External, DC=devlombardi,DC=com
member: CN=dparish,OU=Users,OU=External,DC=devlombardi,DC=com
objectClass: top
objectClass: group
cn: ACME
distinguishedName: CN=ACME,OU=Groups,OU=External,DC=devlombardi,DC=com
sAMAccountName: ACME
name: ACME

Same rules as the user, except this time it's a group. We only want the container the ACME group is in so we need: "CN=ACME,OU=Groups,OU=External,DC=devlombardi,DC=com". This will go in the rolesCtxDN. This will restrict your groups to just those in this OU (and child containers). You may have other groups in other containers, but just like the users, let's hold off on putting in another value until we know jBoss works and can find this group.

The host is: devldap.lombardi.com
The port is: 389

You should try telneting to the host and port from the jBoss server just to make sure it works. Given the above the telnet would be: "telnet devldap.lombardi.com 389". It is also possible to use an SSL port to connect with LDAP, but the scope of that is beyond this article and definitely should not be attempted until you know everything works via the non-ssl port.

Given the above let's now setup the jBoss server to use our LDAP server.

The first step is to copy the following to process-server/resources/config/100CustomLDAP.xml. This will then be picked up by the config on startup and allow both the teamworks internal provider (where tw_admin lives) and your LDAP server to co-exist.

<properties>

<common merge="mergeChildren">

<security merge="mergeChildren">
com.lombardisoftware.userorg.JBossLdapExtUserRegistryModule
</access-controller-manager>
</security>

</common>

</properties>

When you restart teamworks, look at process-server/resources/config/TeamWorksConfiguration.running.xml you should see the following (notice both providers are enabled):

<access-controller-manager>

<access-controller>com.lombardisoftware.userorg.JBossInternalUserRegistryModule</access-controller>
<access-controller>com.lombardisoftware.userorg.JBossLdapExtUserRegistryModule</access-controller>

</access-controller-manager>

Now we need to modify process-server/conf/login-config.xml. The below listed xml is from the application-policy block at the end of the file. I've added comments inside the xml to explain where the values from the LDIF's made it into the config file.

<application-policy name = "other">

<authentication>

<login-module code = "com.lombardisoftware.security.provider.authentication.jboss.TWInternalLoginModuleImpl" flag = "optional">

<!-- this is now optional so you can use ldap and the internal provider -->

<module-option name="password-stacking">useFirstPass</module-option>

</login-module>

<!-- LDAP -->

<login-module code="org.jboss.security.auth.spi.LdapExtLoginModule" flag="optional" >


<!-- notice this is also set to optional -->

<!-- this is the host and the port of the ldap server -->

<module-option name="java.naming.provider.url">ldap://devldap.lombardi.com:389/</module-option>

<!-- this is the bind user from the LDIF you need the dn value from the LDIF - this is the fully qualified distinguished name for the user -->

<module-option name="bindDN">CN=foo, CN=Users, DC=devlombardi,DC=com</module-option>

<!-- this is the password for the bindDN user, keep it in plain text for now, you can encrypt later it as per the jBoss docs-->

<module-option name="bindCredential">changeme</module-option>

<!-- this is where the users exist, it is built from the dn attribute of the LDIF of the user with the username and attribute removed -->

<module-option name="baseCtxDN">OU=Users, OU=External, DC=devlombardi,DC=com</module-option>

<!-- the following should not need to be changed for most active directory installations -->

<module-option name="baseFilter">(sAMAccountName={0})</module-option>

<module-option name="roleFilter">(member={1})</module-option>

<!-- this is where the groups exist, it is built from the dn attribute LDIF of the group with the group name removed -->

<module-option name="rolesCtxDN">OU=Groups, OU=External, DC=devlombardi,DC=com</module-option>

<!-- the following should not need to be changed for most active directory installations -->

<module-option name="roleAttributeID">cn</module-option>

<module-option name="roleAttributeIsDN">false</module-option>

<module-option name="roleNameAttributeID">cn</module-option>

<module-option name="password-stacking">useFirstPass</module-option>

<!-- these are NOT in the stock login-config.xml but should be added -->

<!-- this allows your ldap server to follow referrals it is usually need for Active Directory -->

<module-option name="java.naming.referral">follow</module-option>

<!-- this forces the user to have to have a password - if set to true any user would be able to login if they did not enter a password -->

<module-option name="allowEmptyPasswords">false</module-option>

<!-- these are all teamworks specific attributes - they do not need to be changed for most active directory installations -->

<module-option name="twUserFilter">(objectClass=person)</module-option>

<module-option name="twGroupFilter">(objectClass=group)</module-option>

<module-option name="twUserNameAttribute">sAMAccountName</module-option>

<module-option name="twGroupNameAttribute">cn</module-option>

<module-option name="twUserDescriptionAttribute">description</module-option>

<module-option name="twGroupDescriptionAttribute">description</module-option>

<module-option name="twGroupMemberAttribute">member</module-option>

</login-module>

<!-- these last two login-module sections stay the defaults.-->

<login-module code="com.lombardisoftware.security.provider.authentication.jboss.TWAuthenticatedRoleLoginModuleImpl" flag="required">

<module-option name="authenticatedRole">twuser</module-option>

</login-module>

<login-module code = "org.jboss.security.ClientLoginModule" flag = "required"/>


</authentication>

</application-policy>

After adding the 100CustomLDAP.xml and modifying your login-config.xml using the above reference and restarting you should now have the ability to login as either a stock teamworks internal user (such as tw_admin) or as any user in the user context you specified in baseCtxDN. You will need to make the same modifications to the performance-server once the process server is working properly.

To test that your group works, go to the logical roles screen and add your ldap group to the tw_admins logical role (you will need to do this as tw_admin). You can then login as your ldap user and they should have full access to the teamworks console as if they were the tw_admin user.