OpenKM v5.1.9 -> Active Directory Integration

By | May 5, 2012

I’m working on a project at work to transition a document repository from an out-of-date, archaic version of Application Xtender to something that’s newer and a little easier to maintain, and hopefully web-based to eliminate client installations. Some of my other requirements are the ability to OCR documents for full-text searching, a robust security model, integration with Active Directory to reduce user-access configuration, and plain old reliability.

After much searching on the Internet, I found a product that was open source and seemed to accommodate my every need. OpenKM is an interesting product. Feature rich, but a bear to install. Documentation is patchy, confusing and contradictory, but the product is very effective.

This article is an attempt to document one of the most confusing aspects of OpenKM, integrating it with Active directory so that all security features seem to work as expected. There are many articles on the Internet on how to configure this critical aspect of OpenKM, but because of the rapid develop cycle and addition of features, it’s hard to determine the correct way to configure the integration.

You may need to replace the double-quotes in the sample text below with a standard double-quote after you copy it into your text editor.

  <application-policy name=”OpenKM”>
    <authentication>
      <login-module code=”org.jboss.security.auth.spi.LdapExtLoginModule” flag=”required”>
        <module-option name=”java.naming.provider.url”>ldap://LDAPSERVERFQDN:389</module-option>
        <module-option name=”bindDN”>LDAPACCOUNT</module-option>
        <module-option name=”bindCredential”>LDAPACCOUNTPASSWORD</module-option>
        <module-option name=”baseCtxDN”>USERCONTAINER</module-option>
        <module-option name=”baseFilter”>(sAMAccountName={0})</module-option>
        <module-option name=”rolesCtxDN”>USERCONTAINER</module-option>
        <module-option name=”roleFilter”>(sAMAccountName={0})</module-option>
        <module-option name=”roleAttributeID”>memberOf</module-option>
        <module-option name=”roleNameAttributeID”>CN</module-option>
        <module-option name=”roleAttributeIsDN”>true</module-option>
        <module-option name=”roleRecursion”>5</module-option>
        <module-option name=”searchScope”>SUBTREE_SCOPE</module-option>
        <module-option name=”allowEmptyPasswords”>false</module-option>
        <!–module-option name=”defaultRole”>UserRole</module-option–> <!–Make sure you comment out this line or everyone will be assigned the default role and allowed to log in.–>
      </login-module>
    </authentication>
  </application-policy>

In versions of OpenKM prior to 5.x, configuration values were entered into the OpenKM.cfg file. As of v5.x, only 2 values are used in that file, with the rest moved inside the application’s Administration tab. For v5.1.9, you should enter the following values into the Administration panel:

principal.adapter=com.openkm.principal.LdapPrincipalAdapter
principal.database.filter.inactive.users=true
principal.ldap.mail.attribute=mail
principal.ldap.mail.search.base=USERCONTAINER
principal.ldap.mail.search.filter=(&(objectclass=person)(sAMAccountName={0}))
principal.ldap.referral=follow
principal.ldap.role.attribute=CN
principal.ldap.role.search.base=GROUPCONTAINER
principal.ldap.role.search.filter=(objectClass=group)
principal.ldap.roles.by.user.attribute=memberOf
principal.ldap.roles.by.user.search.base=USERCONTAINER
principal.ldap.roles.by.user.search.filter=(&(objectclass=person)(sAMAccountName={0}))
principal.ldap.security.credentials=LDAPACCOUNTPASSWORD
principal.ldap.security.principal=LDAPACCOUNT
principal.ldap.server=ldap://LDAPSERVERFQDN:389
principal.ldap.user.attribute=sAMAccountName
principal.ldap.user.search.base=USERCONTAINER
principal.ldap.user.search.filter=(&(objectclass=user)(memberOf=OPENKMUSERROLE))
principal.ldap.username.attribute=CN
principal.ldap.username.search.base=USERCONTAINER
principal.ldap.username.search.filter=(&(objectclass=person)(sAMAccountName={0}))
principal.ldap.users.by.role.attribute=sAMAccountName
principal.ldap.users.by.role.search.base=USERCONTAINER
principal.ldap.users.by.role.search.filter=(&(objectCategory=user)(memberof:1.2.840.113556.1.4.1941:=CN={0},GROUPCONTAINER))

Both of the above code examples use the following variable strings. Simply replace the following strings with your actual values:

  • LDAPSERVERFQDN: SERVERNAME.DOMAINNAME.TOPLEVELDOMAIN like “domaincontroller.contoso.com”.
  • LDAPACCOUNT: CN=LDAPACCOUNT,CN=LDAPACCOUNTCONTAINER,DC=DOMAINNAME,DC=TOPLEVELDOMAIN like “CN=Administrator,CN=Users,DC=contoso,DC=com”. Many LDAP tools allow you to get this information from your Active Directory.
  • LDAPACCOUNTPASSWORD: The password for the LDAPACCOUNT.
  • USERCONTAINER: OU=USERCONTAINER,DC=DOMAINNAME,dc=TOPLEVELDOMAIN like “OU=Contoso Users,DC=contoso,DC=com”.
  • GROUPCONTAINER: OU=GROUPCONTAINER,DC=DOMAINNAME,dc=TOPLEVELDOMAIN like “”.
  • OPENKMUSERROLE: CN=OpenKMUserRole,OU=GROUPCONTAINER,DC=DOMAINNAME,dc=TOPLEVELDOMAIN like “CN=OpenKMUserRole,OU=Contoso Groups,DC=contoso,DC=com”.
  • OPENKMADMINROLE: CN=OpenKMAdminRole,OU=GROUPCONTAINER,DC=DOMAINNAME,dc=TOPLEVELDOMAIN like “CN=OpenKMAdminRole,OU=Contoso Groups,DC=contoso,DC=com”.

This configuration appears to return all values correctly with one exception. My version of OpenKM doesn’t show the user’s name correctly. I plan to post additional articles documenting the correct configuration as we migrate to newer versions.

The configuration I’m running is as follows:

  • Microsoft Hyper-V Centos 6.2 64-bit VM, 2 processor, 4GB, running on a 120GB dynamic VHD
  • OpenKM v5.1.9

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.