Magnolia 4.5 reached end of life on June 30, 2016. This branch is no longer supported, see End-of-life policy.
This document applies to LDAP Connector 1.6. This version authenticates only against one LDAP or Active Directory server at a time. If you have more servers and want to be authenticated against all of them, stay at LDAP Connector 1.4 until this limitation is removed.
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.
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
See the general module uninstalling instructions and advice.
LDAP typically mirrors the organization structure. If your company has Marketing, HR and Legal departments you would create
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
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.
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.
What is managed in LDAP
What is managed in Magnolia
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.
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 (
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 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.
LDAPAuthenticationModule: this module can be used to authenticate against any LDAP directory. You would use this together with
MagnoliaRoleResolver(users replicated in the JCR repository) or with specific
NameResolverimplementations to resolve groups and roles for your LDAP users.
ADAuthenticationModule: a specialized version of the
LDAPAuthenticationModulefor Active Directory.
The LDAP configuration defines how Magnolia can find the LDAP server and what it should resolve.
A fully qualified URL to your LDAP server.
Password encryption type:
Optional. Identity of the principal to be authenticated. Use an appropriate DN/CN for your LDAP server.
This string is used to build an initial search against the server, for example
The class responsible for resolvin groups assigned to a user. The class must implement the
The class responsible for resolving roles assigned to a user. The class must implement the
Distinguished name of an admin user who has permissions to search the tree defined in
Password of the admin user.
Name mapping (multiple properties)
Mapping between Magnolia-defined attributes and how these attributes are named in your specific LDAP installation.
Other properties are defined and documented in
If you run JBoss application server editinstead.
skip_on_previous_successto skip this module if the previous module was successful.
For example, replace:
The first module is needed to be able to authenticate the superuser and anonymous users. Note that the second module could also be
For JBoss application server, edit
login-config.xml as follows:
You also need to configure a
externalunder Configuration >
external, add a data node
info.magnolia.jaas.sp.ldap.ADUserManageras a value.
external, add a data node
realmNameand set its value to
userManagersare ordered so that
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.ExternalUser pair to expose it.
If you are resolving roles or groups, add the
allowCrossRealmDuplicateNames property under
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.
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.
magnolia-ldap-tester artifact is a self-contained executable jar which can be executed with:
<LoginModule class name> should be either
info.magnolia.jaas.sp.ldap.ADAuthenticationModule, depending on which one you're using in
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
A successful login attempt looks like this in the log:
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.