Magnolia 5.3 reached end of life on June 30, 2017. This branch is no longer supported, see End-of-life policy.
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.
LDAP is an Enterprise Edition feature. Download the LDAP bundle from our Nexus repository
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 to use in a ldap.properties
file:
| required URL of the LDAP service provider. |
| optional, default is the LDAP provider's default User or program doing the authentication. Use an appropriate DN/CN for your LDAP server. Example: |
| optional Password or encrypted data such as a digital certificate that the implementation uses to authenticate the client. |
| optional, default is Authentication mechanism (password encryption) used. Possible values are |
| optional, default is Indicates to the service provider how to handle referrals. Valid values are If the LDAP service provider receives a referral despite you having set the property to To deal with the
|
| required An entry in the directory consists of a set of attributes. An attribute has a name and one or more values. The attributes are defined in a schema. The Example: Attributes:
|
| optional Define this property if you maintain user groups in LDAP. The value is a class responsible for resolving groups assigned to a user. The class must implement the Implementations:
|
| required A class responsible for resolving roles assigned to a user. The class must implement the Implementations:
|
Properties to use in a ldap.properties
file for Microsoft Active Directory:
| required URL of the Active Directory service provider. |
| optional, default is Indicates to the service provider how to handle referrals. Valid values are If the LDAP service provider receives a referral despite you having set the property to To deal with the
|
| required Distinguished name (DN) of an admin user who has permissions to search the tree defined in Example: |
| required Admin user password. |
| optional , default is Set |
| optional, default is Authentication mechanism (password encryption) used. Possible values are |
| required An entry in the directory consists of a set of attributes. An attribute has a name and one or more values. The attributes are defined in a schema. The Example: Example attributes:
See also: Accessing properties from LDAP |
| optional Define this property if you maintain user groups in Active Directory. The value is a class responsible for resolving groups assigned to a user. The class must implement the Implementations:
|
| required A class responsible for resolving roles assigned to a user. The class must implement the Implementations:
|
groupId | optional, default is The value of this property should be |
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.
jndi.ldap.config=WEB-INF/config/ldap.properties
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=WEB-INF/config/default-ldap.properties jndi.ldap.config.ldap=WEB-INF/config/ldap.properties jndi.ldap.config.ad=WEB-INF/config/ad.properties
Explanation:
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.ldap
will use an LDAP property file defined under the jndi.ldap.config.ldap
key.ad
will use an Active Directory property file defined under the jndi.ldap.config.ad
key.Corresponding user manager configuration:
Node name | Value |
---|---|
server | |
security | |
userManagers | |
system | |
ad | |
class | info.magnolia.jaas.sp.ldap.ADUserManager |
realmName | ad |
ldap | |
class | info.magnolia.jaas.sp.ldap.LDAPUserManager |
realmName | ldap |
external | |
class | info.magnolia.jaas.sp.ldap.LDAPUserManager |
realmName | external |
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.
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:
| required A class that implements the desired authentication technology. Implementations:
Set also the |
| required The flag indicates whether success of the preceding LoginModule is |
options | optional Options is a space-separated list of LoginModule-specific values which are passed directly to the LoginModule. The options are defined by the LoginModule itself, and control its behavior. Options for
|
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:
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.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
.JCRAuthorizationModule
is required
to succeed.For JBoss Application Server, edit the login-config.xml
file instead.
Example: Authenticate against LDAP on JBoss AS
<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>
You also need to configure an external UserManager
.
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 publishing and unpublishing of content.
Node name | Value |
---|---|
server | |
security | |
userManagers | |
system | |
external | |
class | info.magnolia.jaas.sp.ldap.LDAPUserManager |
realmName | external |
admin | |
public |
Properties:
allowCrossRealmDuplicateNames | optional, default is Allows duplicate usernames in different realms. Only applicable to |
| required A class that implements the UserManager interface. Implementations:
|
lockTimePeriod | optional, default is Time in minutes the account is locked after |
maxFailedLoginAttempts | optional, default is Number of failed attempts allowed before locking the account. |
realmName | required Realm name corresponding to JAAS login configuration. |
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.
Node name | Value |
---|---|
security | |
userManagers | |
system | |
external | |
admin | |
allowCrossRealmDuplicatNames | true |
class | info.magnolia.cms.security.MgnlUserManager |
lockTimePeriod | 0 |
maxFailedLoginAttempts | 5 |
realmName | admin |
public |
See also: Configuring multiple directory servers
Before using the connector, map Magnolia-specific attributes to LDAP attributes. For example, 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
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. Examples of default Magnolia groups are editors
and publishers
which correspond to the responsibilities users have in the content workflow.
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.
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.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.Magnolia does not provide ready-made resolver classes for every possible LDAP product but you can write your own class. Implement the NameResolver
interface and the methods to fetch group names from the directory.
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.