Page tree
Skip to end of metadata
Go to start of metadata

This is a quick guide to enabling LDAP in Magnolia with testing purposes. Although there are some public LDAP testing servers, it is not easy to find one which shows the full directory and all the needed info (u, uo, cn... ). So, in order to achieve a success LDAP login and not dying in the try because of bad credentials info, we will use our own Apache DS and configuration. This guide has been done following Lars Fisher post SSO Series - Setup Magnolia with LDAP and ApacheDS and official Magnolia LDAP documentation.

As an overview, we will go through 3 main steps:

  1. Download, install and configure Apache DS
  2. Magnolia setup
  3. Test our work

Step 1 - Download, install and configure Apache DS

Background: Apache DS is just an embedded directory server which is compatible with LDAPv3. This tool will allow us to setup a DS server and create our own groups, users, organization...

1.1.- Download, installation and server setup

Download and install Apache DS. Please notice that, as Lars says on his post, there is an issue with Apache DS that only works with java 8 or newer. There is a workaround for java 9 that consists on adding -add-modules=ALL-SYSTEM to ApacheDirectoryStudio.ini If you kept the default installation directory, that file can be found (in macOS) under /Applications/ApacheDirectoryStudio.app/Contents/Eclipse.

Open Apache DS and create a new server:

After creating it (just click finish button on the popup window), we need to create a new (first?) connection. For that task, we right click on the server and then 'Create a Connection'. This will create in the 'Connections' tab a new item with the default config.  (feel free to custom whatever you want but admin credentials, if you wish to modify them from its default values, follow this official Apache DS guide).


Now, if we double click on the 'Apache DS 2.0.0' connection it will be automatically open in the LDAP browser view:

If you already know what is a LDAP Namespace structure, skip to 1.2

Before getting scared when seeing something like "CN=spanish-support-team,OU=groups,DC=example,DC=com" I will make a 1 minute explanation so you can make try more customized tests in the future.

That's called LDAP Namespace Structure and must be read from right to the left. The meaning of the acronyms are described in here, but basically, for this guide you'll just need to know three of them:

  • DC = Domain Component
  • OU = Organizational Unit
  • CN = Common Name

So, going back to the Namespace example "CN=spanish-support-team,OU=groups,DC=example,DC=com", that would mean: From the com Domain Component, find the example Domain Component, inside that component find the Organizational Unit called groups and finally find the the object that has the common name  spanish-support-team.

Here you got it illustrated to clarify the hierarchy:

1.2.- LDAP structure: creating organizational unit → groups

Before opening the connection we created in the previous step, we need to start the Apache DS server, otherwise we will get an ERR_04110 (Connection refused). Now lets create our first group:

  • Right click on dc=example,dc-com, select New|New Entry
  • Select Create entry from scratch
  • Find organizationalUnit and add it to the right side, click next
  • Enter RDN: ougroups, click next and finish after the preview

1.3.- LDAP structure: creating organizational unit → users

Same steps as in the point 1.2 by changing the name of the organizational unit.

  • Right click on dc=example,dc-com, select New|New Entry
  • Select Create entry from scratch
  • Find organizationalUnit and add it to the right side, click next
  • Enter RDN: ouusers, click next and finish after the preview

1.4.- Sample data: adding users

  • Select the previously created ou=users node
  • Right click and select New|New Entry
  • Select Create entry from scratch
  • Find inetOrgPerson and add it to the right side, click next
  • Enter RDN: cn = supportUser, click next
  • Enter the desired value for *sn (Surename) in the next window, in our case John Doe and click finish

Now select the newly created user in the LDAP browser and add more attributes by right clicking the attribute window and selecting New attribute:

  • uid => supportUser (after creating the attribute, fill the column "value")
  • userPassword => enter your password (make sure plaintext is selected for the hash method)

The uid is the key the LDAP Connector module will use to find this user account in the ApacheDS directory. The account for supportUser now looks like this:

1.5.- Sample data: adding groups

  • Select the previously created ou=groups node
  • Right click and select New|New Entry
  • Select Create entry from scratch
  • Find groupOfNames and add it to the right side, click next
  • Enter RDN: cn = spanish-support-team, click next
  • Use the browse button and select user supportUser created before, click finish


For adding more users to a group later, add the attribute member and select the user account, so you will have a member row for each user belonging to that group:

member: cn=supportUser,ou=users,dc=example,dc=com

member: cn=supportUser2,ou=users,dc=example,dc=com

member: cn=supportUser3,ou=users,dc=example,dc=com

The group now looks like this:


This is the end of the Apache DS configuration. Now, lets move to the Magnolia side.

Step 2 - Magnolia setup

2.1.- Installing LDAP module

Whether you are using a Magnolia Bundle or you created your own Magnolia project vía mvn archetype, we will need to add the ldap module:

Or add the dependency to your pom file:

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

2.2.- Configuring JAAS

Now we will override the default JAAS configuration to include the LDAP authentication module. This file can be found under your WEB-INF/config/ folder. Edit it with any text editor and copy the snippet below:

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

2.3.- LDAP properties configuration

First of all, copy the blueprint file from the Magnolia Git repository to your web project to WEB-INF/config/ldap.properties. Open ldap.properties in the text editor and modify it according to our LDAP setup (the rest of the file remains unchanged). Please remember that in point '1.1.- Download, installation and server setup' we kept the default superuser credentials (admin/secret). If you followed the provided guide to modify them, then you must also modify the properties java.naming.security.principal and java.naming.security.credentials to match your custom configuration.

java.naming.provider.url=ldap://localhost:10389
java.naming.security.principal=uid=admin,ou=system
java.naming.security.credentials=secret
initialSearchAttributes=OU=Users,dc=example,dc=com
groupSearchContext=ou=groups,dc=example,dc=com
##########################################################################
# Name mapping between magnolia defined attributes and how attributes are named
# in custom directory
##########################################################################
Organization=o
OrganizationUnit=ou
CommonName=cn
Surname=sn
GivenName=givenname
uid=uid
dn=dn
Password=pass
Language=language
##########################################################################
# EXAMPLE : Setup if groups are not maintained in LDAP
##########################################################################
# => comment out because we manage groups in ApacheDS
groupResolverClass=info.magnolia.jaas.sp.ldap.resolver.OpenLDAPGroupResolver
groupSearchFilter=(&(objectClass=groupOfNames)(member=MEMBERSHIP_VALUE))
groupMembershipAttributeValue=dn
groupIdAttribute=cn
groupMembershipAttribute=member
java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory

2.4.- Reference LDAP configuration

Now we tell Magnolia where is the LDAP configuration file. For that, just edit magnolia.properties file and add the following line:

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

2.5.- Set LDAP in userManager

In your Magnolia instance, go to the Configuration's app → server → security → userManagers. By default, you have three nodes there: system, admin and public. In order to get LDAP working we need to create a new node named external between system and admin nodes. The fastest way of achieving this is copy-paste public node and editing the properties class and realmName to match the following values:

class: info.magnolia.jaas.sp.ldap.LDAPUserManager
realmName: external

Your userManagers node must look like the following:

2.6.- Create LDAP group

For achieving a success login, the user must belongs to a group that exists in both sides: ApacheDS and Magnolia's. The simplest way of make this work would have been, in step 1.5, to have created a group that already existed in Magnolia (e.g. travel-demo-editors). In that case, if we would try to login right now with supportUser account it would work. But life's not always easy, so let's create and configure spanish-support-team.

Go to Security app and select the Groups tab. Now add a new group and set the config you wish (admin, publisher, editor... ).

I granted him superuser rights:

Important: you can create users for login in Magnolia at any time (without stopping Magnolia) as far as they belong to an already existing Magnolia group. But if you create a new group (like in this example) you will need to restart your bundle.

  • New user → Already existing Magnolia → No restart needed
  • New user → New group needed in Magnolia → Restart is mandatory

Step 3 - Test our work

Now just use the supportUser credentials to login Magnolia:



  • No labels