Matomo and LDAP
First question is, what is LDAP? LDAP stands for "Lightweight Directory Access Protocol" but as an adult, you probably already find out this definition on the internet, so what you may be asking is what's in it for me and how you can more easily understand what this is.
Well, first of all, you need a bit of imagination. You cannot think of LDAP if you are in charge of a tiny company, imagine that you are working on your own, then LDAP is not for you. If you are working for a huge organization and that you are a system administrator, then LDAP can fix one big issue for you which is the IT management of all the employees in terms of IT data (so to say credentials and profiles and add this the possibility that you can also manage the machines, computers and others as they were indviduals). And this is what LDAP is about, it is a directory of data in order to easily manage all your people information. It is like gathering the identity cards of all your organization.
Typical use case is the following one, you just installed a new software within the company and you need to give an access in some minutes to more than a thousand of people... this thousand of people is composed of only the people who are based in a specific city, working for a specific organization and doing a specific task in their job. LDAP is the technology which will give you this filter and if it is supported by the information system that you are using (for example Matomo) you can synchronize your directory with it. So to say this thousand of people will get an access without you or they to create an account in Matomo.
So big question, is this a thing for system administrators? The answer is yes.
Ok, how does this work? Which technology is behind? Well, LDAP is a specific kind of database as it is a directory, so a directory is different from traditionnal table databases as it has the structure of a tree. If you still have the paper Yellow pages in mind, then you see what we mean by directory, it means that a data is located within a category which belong to an upper category, to another category and so on and so forth.
In order to install an LDAP, you need to have a LDAP server, then you can decide if you want a web interface or not. For the sake of this tutorial, I am going to use OpenLDAP which is an open source software available at: https://www.openldap.org/.
The installation of OpenLDAP is really simple, though the use of OpenLDAP can be seen as very complex because it is far different than other technologies that you are used to see:
sudo apt install slapd ldap-utils
and then:
sudo dpkg-reconfigure slapd
Ok this step requires a bit of work, as they are going to ask you a lot of questions. Let's see what they are and what you should answer:
1) If you enable this option, no initial configuration or database will be created for you.
Say "No" here, because you want to create a new database.
2) The DNS domain name is used to construct the base DN of the LDAP directory. For example, 'foo.example.org' will create the directory with 'dc=foo, dc=example, dc=org' as base DN.
Here it referes to the DNS domain name that you want to use, in my case, as I just want to show it as a demo and that I am using it locally, I am going to enter something fake here, so let's say myorganization.com
3) Please enter the name of the organization to use in the base DN of your LDAP directory.
I entered myorganization.
4) Please enter the password for the admin entry in your LDAP directory.
I suggest you to put one here as sometimes some system are used to not accept blank passwords. Just ensure that you can easily remember this one.
5) HDB and BDB use similar storage formats, but HDB adds support for subtree renames. Both support the same configuration options. The MDB backend is recommended. MDB uses a new storage format and requires less configuration than BDB or HDB. In any case,
you should review the resulting database configuration for your needs. See /usr/share/doc/slapd/README.Debian.gz for more details.
The answer is within the question, they are asking you to choose MDB... so let's choose MDB.
6) Do you want the database to be removed when slapd is purged?
Well, in my case, I set OpenLDAP many times so I would like to start from scracth, so I am saying Yes, but in your case, that will be a No.
7) There are still files in /var/lib/ldap which will probably break the configuration process. If you enable this option, the maintainer scripts will move the old database files out of the way before creating a new database.
Here I said yes, because I don't want to have a buggy installation.
And then, congratulations your LDAP is running. Though, nothing really exciting will appear for the moment as everything is done through command line and as the directory is empty.
So, to look through the directory here is one command line to know:
sudo ldapsearch -Q -L -Y EXTERNAL -H ldapi:/// -b dc=myorganization,dc=com
which will display you what's in the tree of myorganization.com.
So far, nothing really sexy will be displayed except the admin and the organization. So what we are going to do is to add several people within our organization.
Here is the file that I will add:
dn: ou=People,dc=myorganization,dc=com
objectclass: organizationalUnit
ou: People
description: Employees
dn: ou=Machines,dc=myorganization,dc=com
objectclass: organizationalUnit
ou: Machines
description: Machines
dn: cn=John
Doe,ou=People,dc=myorganization,dc=com
objectClass: inetOrgPerson
givenName: John
sn: Doe
cn: John Doe
uid: jdoe
userPassword: jdoe
dn: cn=Lucy Dune,ou=People,dc=myorganization,dc=com
objectClass: inetOrgPerson
givenName:
Lucy
sn: Dune
cn: Lucy Dune
uid: ldune
userPassword: ldune
and I am going to name this file organization.ldif and I am going to fire the following command line:
ldapadd -x -D cn=admin,dc=myorganization,dc=com -W -f organization.ldif
which will add two people to the directory.
If you want to add more people, then create an independent ldif file for example:
dn: cn=Geralt Rivia,ou=People,dc=myorganization,dc=com
objectClass: inetOrgPerson
givenName: Geralt
sn: Rivia
mail: geralt.rivia@myorganization.com
cn: Geralt Rivia
uid: geralt
userPassword: grivia
sudo ldapadd -a -x -W -D "cn=admin,dc=myorganization,dc=com" -f geralt.ldif
How to use now LDAP in order to use it within an information system such as Matomo?
Well, there are several plugins within Matomo which support LDAP, the one I used for this tutorial is the one developed by the Matomo team, which is a simple integration of users. It is straightforward. The part you need to fill in is the last part, you will fill them with:
- server
- localhost
- 389
- dc=myorganization,dc=com
- cn=admin,dc=myorganization,dc=com
- the password I used for the LDAP server
and then I used the LDAP Search Filter to double check that the connection is fine.
Once done, I accessed to the Matomo server and launched:
sudo ./console loginldap:synchronize-users
Users get then syncronized.