LDAP Connector 1.4 module

Magnolia LDAP Connector module is a standard JAAS login module, which connects to any LDAP V3 supported directory service. This module is useful when deploying Magnolia in large-scale intranet environments where an enterprise-grade user management infrastructure already exists. With the JAAS standard support you can meet single sign-on requirements or to connect to legacy LDAP/ADS directory servers.

Download

Download the LDAP module from Magnolia Store or Nexus repository.

Installing

LDAP Connector is an enterprise module available in the add-ons folder of the Enterprise Edition bundle. To install the module, see the general module installation instructions . Additionally, copy ldap.properties (or ad.properties for Active Directory) to WEB-INF/config/ldap/.

Note: Unlike most modules, installing the LDAP module doesn't trigger upgrade or installation tasks. It will quietly make the necessary classes available for your configuration, but you won't see it listed in the modules section of your configuration, nor will it trigger the "Upgrade Needed" notification.

Uninstalling

See the general  module uninstalling instructions and advice.

Available LDAP Modules

1. LDAPAuthenticationModule : this module can be used to authenticate against any LDAP directory. You would use this together with MagnoliaGroupResolver and MagnoliaRoleResolver (users replicated in the JCR repository) or with specific NameResolver implementations to resolve groups and roles for your LDAP users.
2. ADAuthenticationModule : a specialized version of the LDAPAuthenticationModule for Active Directory.

Configuration

ldap.properties

The following properties have to be configured in ldap.properties (or ad.properties):

• java.naming.provider.url: the fully qualified URL to your LDAP server.
• java.naming.security.authentication: refer to ldap.properties for possible values.
• java.naming.security.principal: needs to use the proper DN/CN for your LDAP server.
• initialSearchAttributes: this string is used to build initial search against the server, for instance CN=Users,dc=example,dc=com.
• Name mapping: the mapping between Magnolia defined attributes and how these attributes are named in your specific LDAP installation.
• groupResolverClass: this specifies the class responsible for resolving the groups assigned to a user, and must implement info.magnolia.jaas.sp.ldap.resolver.NameResolver. Existing and provided implementations:
  • info.magnolia.jaas.sp.ldap.resolver.MagnoliaGroupResolver
  • info.magnolia.jaas.sp.ldap.resolver.ADGroupResolver
  • info.magnolia.jaas.sp.ldap.resolver.OpenLDAPGroupResolver
• roleResolverClass: this specifies the class responsible for resolving the roles assigned to a user, and must implement info.magnolia.jaas.sp.ldap.resolver.NameResolver. Existing and provided implementations:
  • info.magnolia.jaas.sp.ldap.resolver.MagnoliaRoleResolver

• Other properties are defined and documented in ldap.properties/ad.properties.

jaas.config

If you run JBoss application server edit login-config.xml instead.

Edit WEB-INF/config/jaas.config:

1. Add the JCR authentication module as a first optional login module. This will allow to authenticate against the users only available in Magnolia.
2. Add the LDAP authentication module as a requisite login module. Set skip_on_previous_success to skip this module if the previous module was successful.

For example, replace:

    magnolia {
        info.magnolia.jaas.sp.jcr.JCRAuthenticationModule requisite;
        info.magnolia.jaas.sp.jcr.JCRAuthorizationModule required;
    };

with:

    magnolia {
        info.magnolia.jaas.sp.jcr.JCRAuthenticationModule optional;
        info.magnolia.jaas.sp.ldap.LDAPAuthenticationModule requisite realm=admin skip_on_previous_success=true jndi.ldap.config=ldap.properties;
        info.magnolia.jaas.sp.jcr.JCRAuthorizationModule required;
    };

The first module is needed to be able to authenticate the superuser and anonymous users. Note that the second module could also be info.magnolia.jaas.sp.ldap.ADAuthenticationModule and that you need to set its jndi.ldap.config property to the configuration file name that you used (ldap.properties or ad.properties).

login-config.xml

For JBoss application server, edit login-config.xml as follows:

<application-policy name="magnolia">
   <authentication>
      <login-module code="info.magnolia.jaas.sp.jcr.JCRAuthenticationModule" 
                    flag = "optional" />
      <login-module code="info.magnolia.jaas.sp.ldap.LDAPAuthenticationModule" 
                    flag = "requisite">
          <module-option name="realm">admin</module-option>
          <module-option name="skip_on_previous_success">true</module-option>
          <module-option name="jndi.ldap.config">ldap.properties</module-option>
      </login-module>
      <login-module code="info.magnolia.jaas.sp.jcr.JCRAuthorizationModule" 
                    flag = "required" />
   </authentication>
</application-policy>

<application-policy name="Jackrabbit">
   <authentication>
      <login-module code="org.apache.jackrabbit.core.security.SimpleLoginModule"
         flag = "required" />
   </authentication>
</application-policy>

User manager

You also need to configure a UserManager:

1. Add a new content node called external under Configuration -> server -> security -> userManagers.
2. Add a nodeData called class with info.magnolia.cms.security.ExternalUserManager as a value
3. Make sure the nodes under "userManagers" are ordered so that external is ordered before admin but after system. Not doing so may result in 401 errors (authentication failed) during activation/deactivation.

If you need to access more user properties than the basic name, fullName and language, you will need to extend info.magnolia.jaas.sp.ldap.LDAPAuthenticationModule#setEntity to push the desired properties into the Entity object, and the info.magnolia.cms.security.ExternalUserManager/info.magnolia.cms.security.ExternalUser pair to expose it.

Mapping LDAP Attributes

Before using the connector you will need to map Magnolia specific names with the attribute names used in your LDAP server, e.g. in Organization=o, "Organization" is a keyword for Magnolia and "o" refers to the attribute name as defined for the LDAP server.

Organization=o
OrganizationUnit=ou
CommonName=cn
Surname=sn
GivenName=givenname
uid=sAMAccountName
dn=dn
mail=mail
GroupId=memberOf
Password=pass
Language=language

Testing and validating LDAP Configuration

The magnolia-ldap-tester artifact is a self-contained executable jar, which can simply be executed with:

 java -jar magnolia-ldap-tester-<version>.jar <LoginModule class name> <config.properties> <username> <password>

<LoginModule class name> should be either info.magnolia.jaas.sp.ldap.LDAPAuthenticationModule or info.magnolia.jaas.sp.ldap.ADAuthenticationModule, depending on which one you're using in jaas.config (or login-config.xml with JBoss).

The tool simulates a user login with the given credentials and configuration, outputs the main results, and logs everything else in magnolia-ldap-tester.log.

A successful login attempt looks like this in the log:

INFO  i.m.jaas.sp.ldap.ConnectionFactory - Trying to log in as 
   cn=jsmith,dc=example,dc=com with a password.
DEBUG i.m.jaas.sp.ldap.ConnectionFactory - Login succeeded.
DEBUG i.m.j.s.l.Tester$MockSecuritySupport - Getting user jsmith from realm admin
INFO  info.magnolia.ldap.tool.LDAPTester - Login result: true
INFO  info.magnolia.ldap.tool.LDAPTester - Commit result: true
DEBUG info.magnolia.ldap.tool.LDAPTester - Subject:
DEBUG info.magnolia.ldap.tool.LDAPTester - User: null
INFO  info.magnolia.ldap.tool.LDAPTester - 
   Properties: {title=jsmith, 
   email=john.smith@example.com, 
   name=jsmith, 
   fullName=jsmith, 
   password=secret}
DEBUG info.magnolia.ldap.tool.LDAPTester - 
   State: {groupNames=[], 
   statusValue=1, 
   roleNames=[]}
INFO  info.magnolia.ldap.tool.LDAPTester - Group names: (none)
INFO  info.magnolia.ldap.tool.LDAPTester - Role names: (none)
DEBUG info.magnolia.ldap.tool.LDAPTester - AttributesMap

Do not expect to see any groups or roles assigned. The tester tool does not connect to Magnolia in any way. It connects to the LDAP. It is normal for group assignments handled in Magnolia to not show up.