LDAP Tools/OpenLDAP HowTo
From Authentication Tools for Joomla! (JAuthTools)
This is a step by step how to on how to get OpenLDAP installed and running as an authentication source for Joomla!.
OpenLDAP is a free, open source implementation of the Lightweight Directory Access Protocol (LDAP) which is often bundled with many Linux distributions. In this case we'll be using the Debian Etch distribution to install and configure OpenLDAP. Apologies for anything that might be specific to Debian.
Note: Mac OS X requires a lot of extra instructions, if you are compiling from source you will most likely have to complete similar if not the same tasks. Keep in mind that if you compile from source your Configuration directory is up to you.
Contents |
Installation and Server Configuration
Platform Installation Notes:
- Debian - Configuration directory at /etc/ldap
- Mac OS X - Configuration directory at /sw/etc/openldap (Fink) or /opt/local/etc/openldap (Ports)
Once you've got slapd installed the configuration fun begins. In the configuration directory, open up the slapd.conf file. You will need to be root to do this. By default it should have a few things like this:
Debian:
# 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
Mac OS X (Fink): (Note: You will need to alter your slapd.conf file to add the cosine and inetorgperson entries)
include /sw/etc/openldap/schema/core.schema include /sw/etc/openldap/schema/cosine.schema include /sw/etc/openldap/schema/inetorgperson.schema
Mac OS X (Ports): (Note: You will need to copy your slapd.conf from the slapd.conf.default file and add the cosine and inetorgperson entries)
include /opt/local/etc/openldap/schema/core.schema include /opt/local/etc/openldap/schema/cosine.schema include /opt/local/etc/openldap/schema/inetorgperson.schema
Progressing through the file we see some settings, what we're looking for is rootdn' and suffix:
suffix "dc=joomla,dc=org" rootdn "cn=admin,dc=joomla,dc=org"
Mac OS X will have them together. If you used Debian, some preconfiguration will have occured already.
Your suffix is whats often called the Base DN, its where your LDAP tree starts. Your root DN is typically the super user for LDAP. Finally there will also be a rootpw entry, which in the case of Mac OS X defaults to secret. Debian during install asks for this password. You should probably change this.
Now that we have our base setup fixed we can consider connecting to our LDAP server.
Connecting to the server
Again, Debian has already configured and started the server (which is very kind of it) but we get no such luck with Mac OS X. For Mac OS X we're going to have to start the server ourselves. Fortunately this isn't a hard task to achieve. First we'll test the configuration and then we'll start the server with maximum debugging in case something goes wrong.
sudo /sw/sbin/slapd -t -d 5 sudo /sw/sbin/slapd -d 255
The first command should run and complete with 'config check successful', and the second one should spawn and stay alive. Since we have the server up we're going to need to create a base entry for the LDAP server, heres a sample:
dn: dc=joomla,dc=org objectClass: top objectClass: dcObject objectClass: organization dc: joomla o: joomla
Save this to a file (in this case we called it 'base.ldif') and run the following command:
ldapadd -D 'cn=admin, dc=joomla, dc=org' -x -f base.ldif -W
Additionally you're going to want to define the admin/manager stle account, and theres an LDIF file here (called userbase.ldif):
dn: cn=admin,dc=joomla,dc=org objectclass: organizationalRole cn: admin
Again, we use a similar command as above to add it (instead of base.ldif its perhaps userbase.ldif).
Finally, before we get too far into things, it might be a good time to add the Joomla LDAP schema into your server setup. You're going to need to restart your server after you've done this to include it
Managing our LDAP server
So now we've got some entries, even some special Joomla! schema, but the interface isn't the most user friendly. Since we're doing all of this with the eventual goal of getting LDAP auth into Joomla!, we might as well use a web based admin tool as well. The one I suggest is phpLDAPAdmin because it seems to work so well. Now for Debian, this package is available via APT but Mac OS X set up is a bit more complicated. phpLDAPAdmin requires a few things, including gettext. The easiest way I've found to satisfy its dependencies is to install the entropy PHP package and use it instead of the system provided PHP. Theres instructions on installing entropy available on their site, and configuring phpLDAPAdmin is also documented. For my Mac, I just extracted it to somewhere in my Sites folder and configured it from there. Additionally, I use LDAP Browser/Editor to do investigative queries against systems (normally eDirectory/Active Directory). Its adding/editing interface is limited but for the most basic of operations its quite a valuable tool.
So hopefully at this point you have phpLDAPAdmin set up and its pointing to your newly configured server waiting for you to login. Login and it should have our base DN available to us. Expanding it reveals our adminisration user and a 'create new entry here option'. For Mac OS X, you can select the user, add the objectClass "simpleSecurityObject". Once you've done that, click 'add new attribute' and select 'userPassword'. Put in an entry and you'll want to probably change the type from plain to something more secure (e.g. md5). This will allow you to use this password to log into the OpenLDAP server.
Next on our list is creating a container for our users. Whilst we could put them all at the base, that ends up being quite messy. So lets create a new entry. This panel gives a large list of options to choose from, some of which will be disabled since we don't have those schemas enabled in our server. However the one we want to use is the 'organisational unit' one. So select 'organisational unit' and hit proceed where you will be prompted for its name. We'll call this one 'Users' and click through until we get to a screen displaying our newly created OU.
Now that we've created an OU, we're going to want to put users in it. Here is where a structural planning issue raises its head: do you want to put all of your users in one place or if you want to segment the users up into different sections. For example, one might have a "Core" OU, a "Public" OU and a "Working Groups" OU. And within the "Working Groups" OU there might be various other OU's to manage sub categorizations of people. For completeness I'm going to branch here into one tutorial on creating users in one location and configuring Joomla! to authenticate them and then another one with multiple OU's. If multipe OU's is your goal, read the single location one first as it covers some information you will need later.
Single OU Configuration
So we've got our Users OU set up now its time to create some users. If you still have the Users OU edit screen up you can click on "Create a child entry", alternatively ensure all the branches are expanded and s9elect "create a new entry here". In the resultant dialog this time we're going to select 'Custom' which will give us more power over our selections.
In the 'RDN' box, put the entry name in. This will be of the format 'uid=username'. So in our case we're going to go with 'uid=pasamio' for this value. Alerternatively you could use 'cn'. If you've added the Joomla! schema you will have JoomlaUser as an option there. Select both JoomlaUser and 'inetOrgPerson' and click proceed.
JoomlaUser, as an item is important because it specifies that certain attributes should be entered into the LDAP directory about a user. These pieces of information then become important for Joomla! (especially 1.5) when autocreating the user. In the page that comes up it is important to fill in every entry with some information. For the JoomlaGroup entry, just put a dummy entry if you do not feel like using the group mapping feature. Alternatively you may put anything you like in here as it is free form text - the group mapping system's group map will then translate it into the appropriate group within Joomla! (1.0.x only). Once this has been completed, scroll through completing anything that you might be interested in and add the entry. Once it is added you will notice that you can add multiple values to every attribute except for the one you specified as the RDN. This means that if you want your users to be able to have multiple users IDs associated with the same identity your RDN should probably be CN, but for most cases using UID should be fine. We can add more entries to populate our directory from here by repeating the same style procedure.
J!1.0 Configuraton
useglobal=0 host=horloge.pasamio.homelinux.net port=389 use_ldapV3=1 negotiate_tls=0 no_referrals=1 autocreate=1 autocreateregistered=1 defaultgroup=registered forceldap=0 base_dn=DC=pasamio,DC=homelinux,DC=net search_dn=DC=pasamio,DC=homelinux,DC=net search_string= auth_method=bind username= password= users_dn=uid=[username],ou=users,dc=pasamio,dc=homelinux,dc=net ldap_fullname=name ldap_email=mail ldap_uid=cn ldap_password=userPassword ldap_blocked=loginDisabled ldap_groupname=JoomlaGroup cbconfirm=0 groupMap=
J!1.5 Configuration
J!1.5 by default ships with far less options than the JAuthTools LDAP Tools mambots but many of the values are the same:
host=horloge.pasamio.homelinux.net port=389 use_ldapV3=1 negotiate_tls=0 no_referrals=0 auth_method=bind base_dn=dc=pasamio,dc=homelinux,dc=net search_string=uid=[search] users_dn=uid=[username],ou=users,dc=pasamio,dc=homelinux,dc=net username= password= ldap_fullname=fullName ldap_email=mail ldap_uid=uid
Multiple OU Configuraton
In this case we're creating sub OU's in our main OU of Users and working from there. Creating users should be done as above, the same with creating OU's. The main difference is that we need to now 'search' for our user before we can authenticate them. This creates a small overhead on the server (anonymous or authenticated bind, search and then bind as user) which is why it is typically avoided. However the configuration change is only slight.
J!1.0 Configuration
useglobal=0 host=horloge.pasamio.homelinux.net port=389 use_ldapV3=1 negotiate_tls=0 no_referrals=1 autocreate=1 autocreateregistered=1 defaultgroup=registered forceldap=0 base_dn=DC=pasamio,DC=homelinux,DC=net search_dn=DC=pasamio,DC=homelinux,DC=net search_string=uid=[search] auth_method=search username= password= users_dn= ldap_fullname=name ldap_email=mail ldap_uid=cn ldap_password=userPassword ldap_blocked=loginDisabled ldap_groupname=JoomlaGroup cbconfirm=0 groupMap=
J!1.5 Configuration
host=horloge.pasamio.homelinux.net port=389 use_ldapV3=1 negotiate_tls=0 no_referrals=0 auth_method=search base_dn=dc=pasamio,dc=homelinux,dc=net search_string=uid=[search] users_dn= username= password= ldap_fullname=fullName ldap_email=mail ldap_uid=uid
As you can see we've changed the method to search and removed the Users DN. If we weren't doing an anonymous bind (authenticated bind), the Users DN would remain the same and the username and password values would be set to the user we connect to the server with, which is typically a service account with read access to the relevant areas. This configuration will work for the above setup but if the above option is available this method is preferred for server performance reasons.
Notes
I tried phpLDAPAdmin 0.9.8.3 on my Mac and had some issues with it and ended up switching to 0.9.8.4 on my Debian server. Everything stated above was done in either of those released of phpLDAPAdmin. Safari has some slight issues with phpLDAPAdmin so keep in mind if using this browser, I suggest Firefox for use with this tool.
Sources
- Setting up slapd on Mac OS X - A blog entry useful for getting me started on Mac OS X
- LDAP authentication howto for Debian Sarge - one of the original documents I read on setting up OpenLDAP originally.
