OpenLDAP
OpenLDAP
A guide to the LDAP protocol and how to use it with OpenLDAP.
What you will need
This project assumes that you have already followed our Raspberry Pi installation project, and have the resulting configured Raspberry Pi. If you are installing on different hardware or a different OS, these steps may not all be the same for you.
System Setup
Before continuing with the project, make sure your system is up to date.
sudo apt updatesudo apt upgrade -yInstall a text editor of your choice. Here we use vim as an example.
sudo apt install vimConcepts
What is LDAP?
The Lightweight Directory Access Protocol (LDAP) is a protocol for managing hierarchical data. It basically can store all the information things (and I mean that quite broadly) on your network.
It can store information about:
- Users
- Credentials
- Groups
- Servers
- And a whole lot more!
Directory Servers
A directory server is a database that stores information using trees of entries. This operates much like a filesystem, where the branches of the tree are the folders in a filesystem, and the folders are at the end of each branch.
This will be a useful (albeit imperfect) analogy that we can use throughout our learning!
Entries
An entry is a collection of information about an entity. Each entry consists of three elements:
- A Distinguished Name (DN)
- A Collection of Attributes
- A Collection of Object Classes
Distinguished Names
A distinguished name (DN) uniquely identifies an entry by uniquely identifying its location in the directory information tree (DIT) hierarchy.
This is like the absolute path to a file, which specifies both the name of the file AND the path to get to it.
Relative Distinguished Names
The DN can be broken down into zero or more relative distinguished names (RDNs), which are a attribute-value pair like “uid=alvin.lin”. Think of these as the file name / directories that make up the absolute path to a file.
The RDNs of a DN are listed in descending order (the first is farthest from the root of the tree, the last is closest to the root of the tree)
Attributes
The attributes of an entry are where the data about that entry is stored. They are all the actually useful information about a given entry in LDAP.
The set of rules for what kinds of attributes should be assigned to a given entry is called a schema. A broad term for attributes, as well as other attribute-value pairs such as object classes, which we’ll talk about in a bit, are schema elements.
User Attribute Examples
- cn (Common Name): The full name of a person or the name of an object
- givenName: The first name of the person
- sn (Surname): The last name of the person
- uid (User ID): The login name for the User
- objectClass: : The schema type that defines what attributes an entry can or must have
Object Classes
Object Classes are schema elements that indicate what kind of object an entry represents, as well as what attributes should be assigned to it.
Every entry will have a structural object class, which indicates what kind of abject an entry represents, but an entry can also have additional object classes that suggest other attributes that this entry can have.
Lab Time!!!
Install Packages
Let’s begin by installing the server and the main command line utilities we will be using:
sudo apt install slapd ldap-utilsThe package slapd (the Stand-alone LDAP Daemon) creates a minimal working configuration with a top level entry, and an administrator’s Distinguished Name (DN)
Configuring the Base DN
The base DN (or suffix) is the top-most entry in your directory tree. We can reconfigure slpad with:
sudo dpkg-reconfigure slapdThis will bring you to a reconfiguration wizard which allows you to configure the base setup of slapd.
Off to See the Wizard
Counter-intuitively, at the first prompt click no.
Next, it will prompt you to configure:
- DNS Domain Name: This determines your suffix. We’ll use <hostname>.com as our domain name
- Organization Name: The name of the organization, stored as the o attribute of the base DN entry. To keep with theme, we can make this our hostname.
- Administrator Password: I’ll give you three guesses as to what this is. Make it something you’ll remember!
You can then move the old database when prompted, which we haven’t even bothered configuring yet!
Configuring Defaults
Throughout this guide we will issue many commands with the LDAP utilities. To save some typing, configure the OpenLDAP libraries with defaults by adding these lines in /etc/ldap/ldap.conf:
BASE dc=<hostname>,dc=comURI ldap:///Now, commands like ldapsearch -x -LLL -H ldap:/// -b dc=druid,dc=com dn simplify to ldapsearch -x -LLL dn
Default Configuration Tree1/2
To see what the slapd-config DIT looks like via the LDAP protocol, listing only the DNs, run this command:
sudo ldapsearch -Q -LLL -Y EXTERNAL -H ldapi:/// -b cn=config dnDefault Configuration Tree2/2
Flags/Options:
- -Q: Quiet mode for the SASL authentication setup.
- -LLL: Less verbose LDIF output. One “L” restricts output to LDIFv1; another disables comments; and the third one removes the LDIF version from the output.
- -Y EXTERNAL: Select the EXTERNAL SASL mechanism for authentication.
- -H ldapi:///: The URL to use to contact the server. In this case, it will use a local Unix socket.
- -b cn=config: Start the search at the cn=config base.
- dn: Only retrieve the dn attribute.
Seeing all Configurations
To look at all the configuration that was performed by slapd, you can run:
sudo ldapsearch -Q -LLL -Y EXTERNAL -H ldapi:/// -b cn=configThis will be a suuuuuuuper long output because there are a whole lot of configurations set up behind the scenes!
Default Data Tree (the important tree)
After installing the slapd package, a default data tree is configured, based on the detected domain name of the system. To see this we can run:
ldapsearch -x -LLL -H ldap:/// -b dc=<hostname>,dc=com dnOr, more simply because we set up the base suffix and the URI:
ldapsearch -x -LLL dnIntro to Existentialism (ldapwhoami)
A very handy tool to verify authentication is ldapwhoami, which can be used as follows:
ldapwhoami -xWho are we currently reading from the database as?
Authenticated Requests
Up until now, we’ve been viewing our (rather quite empty) database as a random anonymous person, but we want people to be able to actually login. We can test our ability to log in by logging in as the admin user that slapd set up for us:
ldapwhoami -x -D cn=admin,dc=<hostname>,dc=com -WNow what is the result?
Populating our Directory1/3
Time to actually fill our database with database things! We’re going to add a node for People, a node for groups, a user known as the mysterious Alvin Lin, a users group for Alvin to be in, as well as a grafana user in the grafana group, which we will talk about later.
To do this create a .ldif file using:
vim add_content.ldifThen add in the data:
Populating our Directory2/3
dn: ou=People,dc=example,dc=comobjectClass: organizationalUnitou: People
dn: ou=Groups,dc=example,dc=comobjectClass: organizationalUnitou: Groups
dn: uid=grafana,ou=People,dc=example,dc=comobjectClass: inetOrgPersonuid: grafanasn: grafanacn: grafana
dn: cn=users,ou=Groups,dc=example,dc=comobjectClass: posixGroupcn: usersgidNumber: 10000memberUid: alvin
dn: cn=grafana,ou=Groups,dc=example,dc=comobjectClass: groupOfNamescn: grafanamember: uid=alvin,ou=People,dc=example,dc=com
dn: uid=alvin,ou=People,dc=example,dc=comobjectClass: inetOrgPersonobjectClass: posixAccountobjectClass: shadowAccountuid: alvinsn: Lincn: Alvin Lindisplayname: Alvin LinuidNumber: 10000gidNumber: 10000loginShell: /bin/bashhomeDirectory: /home/alvinPopulating our Directory3/3
We can test our new entries with this command:
ldapadd -n -v -f add_content.ldif- -n (no-op): Does not actually add the the contents, just simulates what it would look like
- -v (verbose): Prints more detailed output
- -f (file): Specifies the input file, in our case “add_content.ldif”
BUT WAIT!! We have a problem!
Changing our .ldif suffix
The template we took off of the website uses the suffix dc=example,dc=com, which is not what we use. To fix this, we can use the sed command, which is a very versatile command, but is used most frequently for substituting text in a file:
sed -i 's/example/<hostname>/g' add_content.ldif- -i: makes said replace the values in the file, usually it just prints the changes to stdout without this flag.
- This command replaces all instances of “example” with "<hostname>"
Adding the Data
In order to finally add these entries, we can run this command:
ldapadd -x -D cn=admin,dc=<hostname>,dc=com -W -f add_content.ldifTesting
We can test that we added everything correctly using this command, which searches for alvin’s entry and lists his cn and gidNumber:
ldapsearch -x -LLL -b ou=People,dc=<hostname>,dc=com '(uid=alvin)' cn gidNumberSetting Alvin’s Password
It’s not very useful to have users if anyone can authenticate into their account, so lets do some fixing. We can set a password for alvin and grafana and test that password using these commands:
ldappasswd -x -D cn=admin,dc=<hostname>,dc=com -W -S uid=alvin,ou=people,dc=<hostname>,dc=comldappasswd -x -D cn=admin,dc=<hostname>,dc=com -W -S uid=grafana,ou=people,dc=<hostname>,dc=comldapwhoami -x -D uid=alvin,ou=people,dc=<hostname>,dc=com -WIMPORTANT: Make sure you make your password for the grafana user “password”, as it will be useful later.
Putting all this to use
Now its time to actually show how any of this is useful (hopefully you already have some ideas on what this could be used for)
What we’re going to be using our very simple and underpopulated ldap server for is AUTHENTICATION, everyone’s favorite thing!
We’ll use our server to authenticate into grafana, which we have utilized for multiple other labs.
Installing Grafana
Run these commands in order to install grafana on your system:
sudo mkdir -p /etc/apt/keyrings/wget -q -O - https://apt.grafana.com/gpg.key | gpg --dearmor | sudo tee /etc/apt/keyrings/grafana.gpg > /dev/nullecho "deb [signed-by=/etc/apt/keyrings/grafana.gpg] https://apt.grafana.com stable main" | sudo tee /etc/apt/sources.list.d/grafana.listsudo apt-get updatesudo apt-get install -y grafanaStarting Grafana
And use these commands to start Grafana:
sudo /bin/systemctl enable grafana-serversudo /bin/systemctl start grafana-serverNow, you should be able to pull up Grafana on http://localhost:3000
Configuring Grafana
The configuration files to use grafana with our ldap server are here:
ldap.toml makes references to example.com, so lets fix that:
sed -i 's/dc=example/dc=<hostname>/g' ~/Downloads/ldap.tomlApplying Configs
Then you can copy these config files to their correct place using:
sudo cp ~/Downloads/grafana.ini /etc/grafana/grafana.inisudo cp ~/Downloads/ldap.toml /etc/grafana/ldap.tomlAnd apply these changes by restarting grafana:
sudo /bin/systemctl restart grafana-serverTesting our setup
To test this, we can try logging in to grafana as Alvin. All we need to do is type in alvin’s uid as the username and his password as the password, and hopefully we should be let in!
Up next
Pi-hole