LDAP Connector module
Security and authentication Bundled: DX Core
| Edition | DX Core |
|---|---|
License |
|
Issues |
|
Maven site |
|
Latest |
1.10.4 |
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 (SSO) requirements or connect to legacy LDAP servers.
Installing with Maven
Bundled modules are automatically installed for you.
If the module is unbundled, add the following to your bundle including your project’s <dependencyManagement> section and your webapp’s <dependencies> section.
If the module is unbundled but the version is managed by the parent POM, add the following to your webapp’s <dependencies> section.
<dependency>
<groupId>info.magnolia</groupId>
<artifactId>magnolia-ldap</artifactId>
<version>1.10.4</version> (1)
</dependency>| 1 | Should you need to specify the module version, do it using <version>. |
Module configuration
Since module version 1.9, the configuration of the following is done directly in the User Manager:
-
allowPartialResults -
ignoreGroupsWithIllegalName -
pageSize -
envPropertiesPredicate
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.propertiesdefines an LDAP server. -
ad.propertiesdefines an Active Directory server.
Properties (LDAP and/or Active Directory)
Properties used in the ldap.properties and/or ad.properties file(s):
| File(s) | Property | Description | ||
|---|---|---|---|---|
both |
|
required URL of the LDAP/AD service provider. Example: |
||
both |
|
required, default is the LDAP provider’s default User or program doing the authentication. Use an appropriate DN/CN for your server. Example: Originally interchangeable with the now deprecated |
||
both |
|
required Password or encrypted data such as a digital certificate that the implementation uses to authenticate the client. Originally interchangeable with the now deprecated |
||
both |
|
optional, default is `none` Authentication mechanism (password encryption) used. Possible values are |
||
both |
|
optional, default is `ignore` Indicates to the service provider how to handle referrals. Valid values are If the LDAP/AD service provider receives a referral despite you having set the property to To deal with the |
||
both |
|
optional (but recommended) The class name of the of the initial context. The class must implement the The default value for |
||
both |
|
required Defines the initial connect point to the directory service. Example: |
||
both |
|
required Name mapping(s) taking the form
See also: Accessing properties from LDAP. |
||
both |
|
optional When searching a user from a wide Example:
|
||
both |
|
optional A custom filter can be used also when searching all users from a wide Example: ADUserManager default users search filter is: |
||
both |
|
required (if The value is a class responsible for resolving groups assigned to a user. The class must implement the [.inlineBean]#info.magnolia.jaas.sp.ldap.resolver.NameResolver` interface. Implementations:
|
||
both |
|
required (if A class responsible for resolving roles assigned to a user. The class must implement the info.magnolia.jaas.sp.ldap.resolver.NameResolver interface. Roles can’t be maintained in LDAP, they must be in Magnolia. Implementation:
|
||
ad. |
|
optional, default is Set |
||
ad. |
|
required (only if The name of the user attribute which specifies the groups the user is a member of. Example: |
||
ldap. |
|
required (if A filter used to find groups the user is a member of. Example: |
||
ldap. |
|
required (if The value of the Example: |
||
both |
|
required (only if either The name of the group ID attribute in LDAP/AD. Example: |
||
both |
|
optional (only if either A subtree for groups in the LDAP/AD structure if groups are managed in a different subtree than the users. If not set, then the Example: |
||
both |
|
optional (only if either
A filter for searching groups in LDAP/AD. |
||
both |
|
required (only if either The name of the group attribute which specifies the members belonging to the group. Example: Deprecated properties:
Instead, use |
magnolia.properties
Put the ldap.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.
magnolia.propertiesjndi.ldap.config=WEB-INF/config/ldap.propertiesConfiguring 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.
magnolia.properties.jndi.ldap.config.ad=WEB-INF/config/ad.properties (1)
jndi.ldap.config.ldap=WEB-INF/config/ldap.properties (2)
jndi.ldap.config=WEB-INF/config/default-ldap.properties (3)| 1 | A user manager with realm name ad uses an Active Directory property file defined under the jndi.ldap.config.ad key. |
| 2 | A user manager with realm name ldap uses an LDAP property file defined under the jndi.ldap.config.ldap key. |
| 3 | A user manager with realm name external uses 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
From LDAP Connector 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 (that is, it’s loaded after) the LDAP Connector 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.
For more information, see * JAAS security setup.
jaas.config for Tomcat
For the Tomcat application server, create a jaas.config file and list the LoginModules in the following format:
jaas.config syntaxmagnolia {
<LoginModule> <flag> <options>;
<LoginModule> <flag> <options>;
<LoginModule> <flag> <options>;
};| Property | Description | ||||||
|---|---|---|---|---|---|---|---|
|
required A class that implements the desired authentication technology. Implementations:
Set also the |
||||||
|
required The flag indicates whether success of the preceding See the |
||||||
|
optional Options is a space-separated list of Options for
|
User manager
You must also configure an external UserManager.
Make sure your external UserManager 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.
|
| Property | Description | ||
|---|---|---|---|
|
optional, default is Allows duplicate usernames in different realms. Only applicable to |
||
|
required A class that implements the info.magnolia.cms.security.UserManager interface. Implementations:
|
||
|
optional, default is Allows to disable caching if set to |
||
|
required Realm name corresponding to JAAS login configuration. |
||
|
optional, default is Indicates what methods are used to deal with the
|
||
|
optional A subnode that allows you to specify a custom |
||
|
The class that implements the The default class used is Two additional implementations are available:
|
||
|
optional A subnode that specifies the If not defined explicitly, then the predicate accepts anything within the following namespaces:
|
||
|
The class that implements the The default class is |
||
|
optional A subnode that defines the decoding method of the admin password used by the
|
||
|
The decoder is available in three implementations:
|
||
|
optional, default is Specifies the number of objects to be returned in a single search result. |
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 bootstrapped into /modules/cache/config/cacheFactory/caches/ldap-user-manager-cache. You can disable caching 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 doesn’t 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 permission to edit content. Permissions are configured using access control lists. A role can be assigned directly to a 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 the role is the element that grants the user 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.
Best practice
When you store groups in LDAP, create one matching group per role in Magnolia. Assign roles to the group in Magnolia to grant users the permissions they need. This minimizes the number of groups you need to create in Magnolia.
| Magnolia | LDAP | ||
|---|---|---|---|
Roles |
Groups |
Groups |
Users |
|
|
|
|
|
|
|
|
When creating a group name, make sure that it doesn’t contain an illegal character. See also the ignoreGroupsWithIllegalName property in module configuration.
|
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
userrolesworkspace in Magnolia.
Testing and validating LDAP configuration
You can use the magnolia-ldap-tester, a standalone module for testing ldap/ad configuration outside of Magnolia. The module is available from Magnolia Nexus: magnolia-ldap-tester-1.10.4.jar
Use the following command to execute the jar:
java -jar magnolia-ldap-tester-1.10.4.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 - AttributesMapDon’t expect to see any groups or roles assigned. The tester tool doesn’t connect to Magnolia in any way. It connects to the LDAP. It’s normal for group assignments handled in Magnolia to not show up.