LDAP Connector module

Magnolia LDAP Connector module is Enterprise only. The 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 intranet environments where an enterprise-grade user management infrastructure already exists. With the JAAS standard support you can meet single sign-on requirements or connect to legacy LDAP/ADS directory servers.

Download

The LDAP module is available in the add-ons folder of the Enterprise Edition bundle. You can also download the module from Magnolia Store or Nexus repository.

Installing

To install the module, see the general module installation instructions.

The location of your ldap.properties file is configurable. You can place the file in an alternative location if you want. Add a new property jndi.ldap.config in the magnolia.properties file and set its value to a relative or absolute path to the webapp, or use ${magnolia.home}.

Uninstalling

See the general module uninstalling instructions and advice.

Groups and roles

LDAP typically mirrors the organization structure. If your company has Marketing, HR and Legal departments you would create marketing, hr and legal groups in your LDAP system, then assign employees to those groups. Just like LDAP groups, Magnolia groups are used to organize users into larger units. Examples of default Magnolia groups are editors and publishers which correspond to the responsibilities users have in the content approval workflow.

Magnolia also has roles. A role grants a user permission to do something. For example, the editor role grants the permission to edit content and the publisher role grants the permission to approve content for publishing. The permissions a role grants are configured with access control lists (ACL). A role can be assigned directly to an individual user or to a group.

Resolving

When the LDAP Connector module authenticates a user using the LDAP server it also tries to find out what groups and roles the user belongs to. This is called resolving. Since role is the element that grants the permission to do something, you need to use a resolver class that resolves at least roles. You can optionally also resolve groups.

Group resolving

The groupResolverClass fetches group names from the LDAP server and matches them with groups in Magnolia. The match must be an exact name match: an editors group in LDAP must match an editors group in Magnolia. When you use a group resolver you have to define groups in LDAP and in Magnolia.

The resolver implementation differs depending on which LDAP product you use. Magnolia provides ready-made group resolvers for Active Directory and OpenLDAP.

Best practice: If you use LDAP groups to assign user permissions then create one name-matching group per user role in Magnolia and add one or more Magnolia roles reflecting the needed permissions to that group. This minimizes the amount of groups needed in Magnolia.

Role resolving

The roleResolverClass works just like group resolving but it only resolves roles. A role resolver fetches role names for the authenticated user from LDAP and matches them to roles in Magnolia. If you use the default role names (editor, publisher etc.) provided by Magnolia you save some effort. For example, create an editor role in LDAP because the name already exists in Magnolia. However, you can create any custom roles you need.

NameResolver interface

NameResolver is an interface that allows you to create your own resolver implementation. Magnolia does not provide ready-made resolver classes for every possible LDAP product. If you need to connect to a new product, write your own class. For example, if no resolver class for OpenLDAP existed you would have to provide your own. Write a class that implements the NameResolver interface. The interface enforces you to implement the methods that are needed to fetch group names from that particular server.

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

The LDAP configuration defines how Magnolia can find the LDAP server and what it should resolve.

ldap.properties and ad.properties

Other properties are defined and documented in ldap.properties and ad.properties files.

jaas.config

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

In WEB-INF/config/jaas.config file:

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 
      skip_on_previous_success=true;
   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.

JBoss 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>

User manager

You also need to configure a UserManager:

1. Add a new content node called external under Configuration > /server/security/userManagers.
2. Under external, add a data node class with info.magnolia.jaas.sp.ldap.LDAPUserManager or info.magnolia.jaas.sp.ldap.ADUserManager as a value.
3. Under external, add a data node realmName and set its value to external.
4.  Make sure the nodes under userManagers are ordered so that external is before admin but after system. Any other order may result in 401 errors (authentication failed) during activation/deactivation.

If you need to access more user properties than name, full name and language, 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.

 If you are resolving roles or groups, add the allowCrossRealmDuplicateNames property under /server/security/userManagers/admin and set its value to true. This property allows you two create users with the same name in different realms when replicating LDAP/AD users in the repository. By default, Magnolia does not allow the same user name to be repeated. The allowCrossRealmDuplicateNames property is only available in Magnolia 4.5.9 and later.

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 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.