LDAP Connector module

Magnolia LDAP Connector is a JAAS login module that connects to any LDAP v3 directory service. The LDAP Connector is used in intranet environments where an enterprise user management infrastructure already exists. With JAAS you can meet single sign-on requirements or connect to legacy LDAP servers.

Installing

<dependency>
  <groupId>info.magnolia</groupId>
  <artifactId>magnolia-ldap</artifactId>
</dependency>

Module configuration

LDAP configuration

An LDAP configuration file tells Magnolia where to find your LDAP directory server. The file also says whether Magnolia should resolve users, groups or both from the directory.

The LDAP Connector module bundle provides two sample files in the configuration-samples folder:

• ldap.properties defines an LDAP server.
• ad.properties defines an Active Directory server.

Properties (LDAP and/or Active Directory)

Properties used in the ldap.properties and/or ad.properties file(s):

Deprecated properties:

• adminUserDN
• adminUserPassword

Instead use java.naming.security.principal  and java.naming.security.credentials  properties respectively.

magnolia.properties

Put theldap.properties or  ad.properties file inside your Magnolia webapp, for example in /<CATALINA_HOME>/webapps/<contextPath>/WEB-INF/config . Reference the file location from a magnolia.properties file using the jndi.ldap.config property. Set the value to an absolute or relative path inside the webapp. You can also use the ${magnolia.home} variable.

jndi.ldap.config=WEB-INF/config/ldap.properties

Configuring multiple directory servers

To configure multiple LDAP and AD directories, use the pattern jndi.ldap.config.<realmName> where realmName corresponds to a realm name in the user manager.

Example: Configuring multiple directory servers in magnolia.properties .

jndi.ldap.config.ad=WEB-INF/config/ad.properties
jndi.ldap.config.ldap=WEB-INF/config/ldap.properties
jndi.ldap.config=WEB-INF/config/default-ldap.properties

Explanation:

• A user manager with realm name ad will use an Active Directory property file defined under the jndi.ldap.config.ad key.
• A user manager with realm name ldap will use an LDAP property file defined under the jndi.ldap.config.ldap key.
• A user manager with realm name external will use the default LDAP property file defined under the jndi.ldap.config key since no specific property file is configured for this realm.

Corresponding user manager configuration:

A custom configuration resolver

( LDAP module 1.9+) You can write your own configuration resolver in JAVA. Add the following component to your module descriptor,

<components>
 <id>main</id>
 <component>
  <type>info.magnolia.jaas.sp.ldap.config.ConfigResolver</type>
  <implementation>your-own-resolver-class</implementation>
 </component>
</components>

change the implementation class accordingly, and make sure that your module depends on (i.e. is loaded after) Magnolia's LDAP module.

JAAS login configuration

Magnolia uses the Java Authentication and Authorization Service (JAAS) to authenticate users. When you store users in a directory outside of Magnolia configure the directory as a LoginModule. You can list several LoginModules. Authentication proceeds down the module list in the order you specify with flags, see javax.security.auth.login.Configuration. Depending on the servlet container you use the configuration for JAAS is slightly different.

jaas.config for Tomcat

For the Tomcat application server, create a jaas.config file and list the LoginModules in the following format:

magnolia { 
   <LoginModule> <flag> <options>;
   <LoginModule> <flag> <options>;
   <LoginModule> <flag> <options>;
   };

Properties:

Example 1:  Authenticate against Magnolia on Tomcat

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

Example 2: Authenticate against LDAP on Tomcat

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;
   };

Notes about example 2:

1. JCRAuthenticationModule authenticates users who are stored only in Magnolia such as superuser and anonymous . optional means the module is not required to succeed. Authentication proceeds to the next module whether the user is found or not.
2. LDAPAuthenticationModule authenticates users who are stored in LDAP. requisite means that if the login module succeeds, authentication continues down the list. If the module fails, authentication does not proceed down the list. This module is skipped if the previous module was successful. This module could also be info.magnolia.jaas.sp.ldap.ADAuthenticationModule  .
3. JCRAuthorizationModule is required to succeed.

User manager

You also need to configure an external UserManager .  Make sure it is placed before the admin but after the system user managers. Any other order may result in 401 errors (authentication failed) during publishing and unpublishing of content.

Properties:

User managers and caching

By default the ad and ldap user managers use a basic cache (Cache modules) to avoid repeated calls to LDAP/AD. If Ehcache is used then the default configuration is automatically bootstraped into /modules/cache/config/cacheFactory/caches/ldap-user-manager-cache . Caching may disabled by adding the disableCache property to the manager's node and setting it to true , for example

Accessing properties from LDAP

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.

Same-name users in different realms

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

See also: Configuring multiple directory servers

Groups and roles

LDAP typically mirrors the organization structure. If your company has a Marketing department then create a  marketing group in the LDAP directory and assign employees to the group. Magnolia also organizes users into groups.

Magnolia also has roles. A role grants a user permission to do something. For example, the editor role grants the user a permission to edit content. Permissions are configured using access control lists. A role can be assigned directly to an user or to a group.

When you authenticate users against an LDAP directory a resolver class finds the groups and roles the user belongs to. This process is called resolving. Since role is the element that grants the user a permission to do something, you must resolve at least roles. You can optionally also resolve groups.

Group resolving

A groupResolverClass configured in ldap.properties finds groups in the LDAP directory and matches them to groups in Magnolia. The group names must match exactly.

Choose a resolver depending on where the groups are stored:

• info.magnolia.jaas.sp.ldap.resolver.MagnoliaGroupResolver resolves groups from Magnolia.
• info.magnolia.jaas.sp.ldap.resolver.OpenLDAPGroupResolver resolves groups from any LDAP directory.
• info.magnolia.jaas.sp.ldap.resolver.ADGroupResolver resolves groups from Active Directory.

Role resolving

A roleResolverClass configured in ldap.properties  finds  roles. Roles must always be stored in Magnolia, they cannot be stored in the LDAP directory. The reason is that the ACLs that grant permissions are attached to roles.

Magnolia provides one role resolver:

• info.magnolia.jaas.sp.ldap.resolver.MagnoliaRoleResolver resolves roles from the userroles workspace in Magnolia.

Implementing your own resolver

Magnolia does not provide ready-made resolver classes for every possible LDAP product but you can write your own class. Implement the info.magnolia.jaas.sp.ldap.resolver.NameResolver interface and the methods to fetch group names from the directory.

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 not to show up.