The Joomla! Community Portal ™

  • Print
  • Email
2008-07 Joomla! Community Magazine

Joomla! Community Magazine - Learning

Developer: LDAP from scratch

Requires: Joomla! 1.5.4, an LDAP server (OpenLDAP) and the LDAP User and Authentication Plugins

Written by Sam Moffatt

Difficulty: Advanced

Requires: Joomla! 1.5.4, or later, an LDAP server (OpenLDAP) and the LDAP User and Authentication Plugins

What we're going to look at today is building up a system with LDAP support and utilising a new tool to provide advanced integration and enable your Joomla! instance to control user details in LDAP like they would with the built-in Joomla! database. I'll open this with a caution that this is not a beginner task and suggest that you read through the entire document first and then attempt installation of your software. Installation might result in prompts that you can fill in with useful information once you've read the article to save you time later.

To start with we're going to utilise a fresh install of OpenLDAP. This is going to be different for each platform that you're working on, and is usually easiest on a Debian/Ubuntu style system which will allow you to install packages with ease using Synaptic or APT. Many Linux distributions are similar. For Mac OS X there is either Fink or Mac Ports, however they may not work as well on Leopard as Tiger. For Windows, there appears to be a binary release available though I have not used it, so your mileage may vary. For more information on tips for getting it working with Debian or Mac OS X 10.4, check out the how to [1] at the bottom. All of this article was written utilising a Debian Etch machine called 'pie'. Once you've got OpenLDAP installed we can continue to configure it for our needs.

In this example we're going to build a simple directory for Joomla.org, with a simple structure. In LDAP it is common to use the DNS name and expand it replacing each part with 'DC=', where DC stands for "Domain Component". In our case we're going to use Joomla.org, so this will look like DC=joomla,DC=org.

First we're going to need to locate the location of the slapd.conf file, which is usually /etc/ldap/slapd.conf or similar, so that we can do some changes. Once we've located it we'll need to put a copy of the Joomla! LDAP schema into the schema directory (usually in the same folder as slapd.conf). You can get the Schema off the JAuthTools web site [2]. Copy the file and place it into the schema folder as "joomla.schema." From here we need to open up the slapd.conf file and make some changes. A copy is included below, just copy this into the file:

# Joomla Group Attribute; free form text
attributetype ( 1.3.6.1.4.1.27457.1.1
				NAME 'JoomlaGroup'
				DESC 'Joomla: Group to belong to'
				EQUALITY caseIgnoreMatch
				SUBSTR caseIgnoreSubstringsMatch
				SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 )

# Joomla User Object Class
# Requires various elements
objectclass ( 1.3.6.1.4.1.27457.1.2
				NAME 'JoomlaUser'
				DESC 'User of a Joomla instance'
				AUXILIARY
				MUST ( cn $ JoomlaGroup $ uid $ mail $ userPassword )
				MAY ( givenName $ sn )
				)

The first change that we need to make in the file is to add an include to the file we just created. Additionally we'll utilise part of the inetorgperson schema, so we'll want to make sure that is there:

# Schema and objectClass definitions
include						  /etc/ldap/schema/core.schema
include						  /etc/ldap/schema/cosine.schema
include						  /etc/ldap/schema/nis.schema
include						  /etc/ldap/schema/inetorgperson.schema
include						  /etc/ldap/schema/joomla.schema

Again, the paths will be different depending on your system. Once we've updated our slapd.conf file to include these entries we continue through the file to look for "suffix" and "rootdn". If you're using Debian this might have already been filled out for you. In our case we're going to change suffix to "dc=joomla,dc=org" and the rootdn to be "cn=admin,dc=joomla,dc=org". In some cases you will need to might need to set the rootpw, however some systems will have it configured for you. So when its all configured it may look like this:

suffix			"dc=joomla,dc=org"
rootdn			"cn=admin,dc=joomla,dc=org"
rootpw			secret

Note: For this example I've used a plain text password, you can create a more secure password by utilising "slappasswd" to generate one, for example utilising "secret" returns "{SSHA}T1VAvNGHD6q3dyZrc9fT78Qu8ErmVdaY". Your installation may have already set the base user as well as their password when you installed, so the "rootpw" line might not be required. Once you've done that, restart the server (usually /etc/init.d/slapd restart) and we'll move onto the next phase.

At the present moment our tree is completely blank so we need to populate it with information. The first thing we need to do is create the root, so we'll do that with a file called root.ldif, that looks like this:

dn: dc=joomla,dc=org
objectClass: top
objectClass: dcObject
objectClass: organization
dc: joomla
o: joomla

And to import it into our directory, we'll use the following command:

ldapadd -D 'cn=admin, dc=joomla, dc=org' -x -f root.ldif -W

On my Debian testing box, the result was as such:

pasamio@pie:~/ldap$ ldapadd -D 'cn=admin, dc=joomla, dc=org' -x -f root.ldif -W
Enter LDAP Password:
adding new entry "dc=joomla,dc=org"

pasamio@pie:~/ldap$ 

Once we've done this we'll need to add in our user entry, so we'll create a file called "user.ldif" and put the following into it:

dn: cn=admin,dc=joomla,dc=org
objectclass: organizationalRole
cn: admin 

And import it similar to before:

pasamio@pie:~/ldap$ ldapadd -D 'cn=admin, dc=joomla, dc=org' -x -f user.ldif -W
Enter LDAP Password: 
adding new entry "cn=admin,dc=joomla,dc=org"

pasamio@pie:~/ldap$ 

Now we have only one more thing to create before we get started, and this is a simple container to hold our users in LDAP. In this case we're going for a simple flat structure to simplify things but we can use a more advance structure nested with hierarchies. The name of the last file is usercontainer.ldif:

dn: ou=users,dc=joomla,dc=org
objectclass: organizationalUnit
ou: users

And the commands:

pasamio@pie:~/ldap$ ldapadd -D 'cn=admin, dc=joomla, dc=org' -x -f usercontainer.ldif -W
Enter LDAP Password:
adding new entry "ou=users,dc=joomla,dc=org"

pasamio@pie:~/ldap$ 

So now we've got all of the LDAP server set up and we're ready to roll.

For a Joomla! tutorial, we've spent a lot of time getting the infrastructure up and running, so now its time to jump into Joomla!. For this part you're going to need Joomla! 1.5.4 due to some of the fixes that were added to it. At the time of writing 1.5.4 wasn't quite available, but you can get a nightly build at developer.joomla.org with the required features.

In addition, we're going to use a new extension I've written that will also populate our LDAP directory as we add users to Joomla!. So set up a new Joomla! install for this utilising the nightly 1.5.4 build (or a stable build when its released). You're also going to need to download the LDAP User Plugin (different from the LDAP Authentication plugin that ships with Joomla!), which is available from the JAuthTools FRS page[3] (direct download link[4]).

The majority of the configuration that we need to do is in the default LDAP Authentication plugin that ships with Joomla!. Because we're going to need to push back we're going to need to fill in the connect username and password.

The first step is to jump into the Joomla! administrator and navigate to Extensions -> Plugin Manager and select the Authentication - LDAP plugin to edit. We'll fill in our details similar to the following:

Host: localhost
LDAP v3: Yes
Authorization Method: Bind and Search
Base DN: ou=users,dc=joomla,dc=org
Search string: uid=[search]
Users DN: 
Connect Username: cn=admin,dc=joomla,dc=org
Connect Password: secret

If you installed LDAP on a different host, you'll need to put that in instead of localhost and your password should be the LDAP password you set earlier. You'll need to enable the LDAP plugin, though at the moment your tree will be entry. Joomla! can handle more than one authentication plugin at once, and it will work so long as at least one plugin returns a successful result. In the case where there is more than one successful result the first plugin to return a success will be used. So if both Joomla! and LDAP recognise the user the Joomla! details will be used by default because Joomla! is first.

The next step we need to take is to configure the LDAP User plugin. On a standard Joomla! install you probably won't see it in the list, so you'll have to look on page two. Alternatively you can use the filter to search for LDAP. Edit the "User - LDAP" and fill in the Default DN param with the value "ou=users,dc=joomla,dc=org". This is the container that the user is put into by default when they are created. You'll also need to enable the plugin before we can get started using it.

At this point we should have everything functional, so now we all need to do is create a new user. Head over to the user manager and create a new user like normal. If all goes well you shouldn't receive an error message and the user will be created in both Joomla! and LDAP. If some thing does for some reason fail, don't worry the users details are in Joomla! database and you can go back and resave the user (obviously you'll have to enter the password again!).

To verify that your system is working properly you can use an LDAP browser to check out your LDAP directory. A lot of the settings you will need for your browser are the same as the ones you entered into Joomla!'s plugin. The JAuthTools wiki has some suggestions for LDAP browsers and there are lots of free browsers available.

For the brave you can take the next step, which is to disable the Joomla! authentication plugin and just use the LDAP plugin to handle all authentication. Before you do this, remember to edit and save your administrator user with a new password to make sure its in the LDAP tree. If you find out that things aren't working completely fine if you run the following SQL against your database, it will re-enable the Joomla! authentication plugin and will let you back in:

UPDATE jos_plugins SET published = 1 WHERE folder = 'authentication' AND element = 'joomla'

Note: If your database prefix is different to jos_ then you'll need to change this to the relevant value.

I've got some further reading and information on my own web site on how to get started with some LDAP browsers and you'll want to check out the OpenLDAP website as well [5]. Once you've got LDAP up and running you can use this to start integrating other LDAP powered applications, all controlled centrally from Joomla!.

Further reading:

  1. A copy of my original How to with some more details: http://sammoffatt.com.au/jauthtools/LDAP_Tools/OpenLDAP_HowTo
  2. Schema Details for Joomla: http://sammoffatt.com.au/jauthtools/LDAP_Tools/Schema
  3. JAuthTools FRS: http://joomlacode.org/gf/project/jauthtools/frs/
  4. Direct LDAP User Plugin download link: http://joomlacode.org/gf/download/frsrelease/7849/28099/plgUserLDAP.zip
  5. OpenLDAP: http://www.openldap.org/