OpenLDAP provides an LDAP directory service that is flexible and well-supported. However, out-of-the-box, the server itself communicates over an unencrypted web connection. In this guide, we will demonstrate how to encrypt connections to OpenLDAP using STARTTLS to upgrade conventional connections to TLS. We will be using an Ubuntu 14.04 as our LDAP server.
Before you get started with this guide, you should have a non-root user with sudo
set up on your server. To set up a user of this type, follow our Ubuntu 14.04 initial setup guide.
We will cover how to install OpenLDAP on an Ubuntu 14.04 server in this guide. If you already have OpenLDAP installed on your server, you can skip the relevant installation and configuration steps.
There are two ways to encrypt LDAP connections with SSL/TLS.
Traditionally, LDAP connections that needed to be encrypted were handled on a separate port, typically 636
. The entire connection would be wrapped with SSL/TLS. This process, called LDAP over SSL, uses the ldaps://
protocol. This method of encryption is now deprecated.
STARTTLS is an alternative approach that is now the preferred method of encrypting an LDAP connection. STARTTLS “upgrades” a non-encrypted connection by wrapping it with SSL/TLS after/during the connection process. This allows unencrypted and encrypted connections to be handled by the same port. This guide will utilize STARTTLS to encrypt connections.
Before you get started, we should set up our server so that it correctly resolves its hostname and fully qualified domain name (FQDN). This will be necessary in order for our certificates to be validated by clients. We will assume that our LDAP server will be hosted on a machine with the FQDN of ldap.example.com
.
To set the hostname in all of the relevant places on your server, use the hostnamectl
command with the set-hostname
option. Set the hostname to the short hostname (do not include the domain name component):
- sudo hostnamectl set-hostname ldap
Next, we need to set the FQDN of our server by making sure that our /etc/hosts
file has the correct information:
- sudo nano /etc/hosts
Find the line that maps the 127.0.1.1
IP address. Change the first field after the IP address to the FQDN of the server, and the second field to the short hostname. For our example, it would look something like this:
. . .
127.0.1.1 ldap.example.com ldap
127.0.0.1 localhost
. . .
Save and close the file when you are finished.
You can check that you’ve configured these values correctly by typing:
- hostname
This should return your short hostname:
ldap
Check the FQDN by typing:
- hostname -f
This should return the FQDN:
ldap.example.com
After ensuring that your hostname is set properly, we can install the software we need. If you already have OpenLDAP installed and configured, you can skip the first sub-section.
If you do not already have OpenLDAP installed, now is the time to fix that. Update your server’s local package index and install the software by typing:
- sudo apt-get update
- sudo apt-get install slapd ldap-utils
You will be asked to provide an LDAP administrative password. Feel free to skip the prompt, as we will be reconfiguring immediately after.
In order to access some additional prompts that we need, we’ll reconfigure the package after installation. To do so, type:
- sudo dpkg-reconfigure slapd
Answer the prompts appropriately, using the information below as a starting point:
example.com
(use the server’s domain name, minus the hostname. This will be used to create the base entry for the information tree)Once your OpenLDAP server is configured, we can go ahead and install the packages we’ll use to encrypt our connection. The Ubuntu OpenLDAP package is compiled against the GnuTLS SSL libraries, so we will use GnuTLS to generate our SSL credentials:
- sudo apt-get install gnutls-bin ssl-cert
With all of our tools installed, we can begin creating the certificates and keys needed to encrypt our connections.
To encrypt our connections, we’ll need to configure a certificate authority and use it to sign the keys for the LDAP server(s) in our infrastructure. So for our single server setup, we will need two sets of key/certificate pairs: one for the certificate authority itself and one that is associated with the LDAP service.
To create the certificates needed to represent these entities, we’ll create some template files. These will contain the information that the certtool
utility needs in order to create certificates with the appropriate properties.
Start by making a directory to store the template files:
- sudo mkdir /etc/ssl/templates
Create the template for the certificate authority first. We’ll call the file ca_server.conf
. Create and open the file in your text editor:
- sudo nano /etc/ssl/templates/ca_server.conf
We only need to provide a few pieces of information in order to successfully create a certificate authority. We need to specify that the certificate will be for a CA (certificate authority) by adding the ca
option. We also need the cert_signing_key
option to give the generated certificate the ability to sign additional certificates. We can set the cn
to whatever descriptive name we’d like for our certificate authority:
cn = LDAP Server CA
ca
cert_signing_key
Save and close the file.
Next, we can create a template for our LDAP server certificate called ldap_server.conf
. Create and open the file in your text editor with sudo
privileges:
- sudo nano /etc/ssl/templates/ldap_server.conf
Here, we’ll provide a few different pieces of information. We’ll provide the name of our organization and set the tls_www_server
, encryption_key
, and signing_key
options so that our cert has the basic functionality it needs.
The cn
in this template must match the FQDN of the LDAP server. If this value does not match, the client will reject the server’s certificate. We will also set the expiration date for the certificate. We’ll create a 10 year certificate to avoid having to manage frequent renewals:
organization = "Example Inc"
cn = ldap.example.com
tls_www_server
encryption_key
signing_key
expiration_days = 3652
Save and close the file when you’re finished.
Now that we have our templates, we can create our two key/certificate pairs. We need to create the certificate authority’s set first.
Use the certtool
utility to generate a private key. The /etc/ssl/private
directory is protected from non-root users and is the appropriate location to place the private keys we will be generating. We can generate a private key and write it to a file called ca_server.key
within this directory by typing:
- sudo certtool -p --outfile /etc/ssl/private/ca_server.key
Now, we can use the private key that we just generated and the template file we created in the last section to create the certificate authority certificate. We will write this to a file in the /etc/ssl/certs
directory called ca_server.pem
:
- sudo certtool -s --load-privkey /etc/ssl/private/ca_server.key --template /etc/ssl/templates/ca_server.conf --outfile /etc/ssl/certs/ca_server.pem
We now have the private key and certificate pair for our certificate authority. We can use this to sign the key that will be used to actually encrypt the LDAP session.
Next, we need to generate a private key for our LDAP server. We will again put the generated key in the /etc/ssl/private
directory for security purposes and will call the file ldap_server.key
for clarity.
We can generate the appropriate key by typing:
- sudo certtool -p --sec-param high --outfile /etc/ssl/private/ldap_server.key
Once we have the private key for the LDAP server, we have everything we need to generate a certificate for the server. We will need to pull in almost all of the components we’ve created thus far (the CA certificate and key, the LDAP server key, and the LDAP server template).
We will put the certificate in the /etc/ssl/certs
directory and name it ldap_server.pem
. The command we need is:
- sudo certtool -c --load-privkey /etc/ssl/private/ldap_server.key --load-ca-certificate /etc/ssl/certs/ca_server.pem --load-ca-privkey /etc/ssl/private/ca_server.key --template /etc/ssl/templates/ldap_server.conf --outfile /etc/ssl/certs/ldap_server.pem
We now have all of the certificates and keys we need. However, currently, our OpenLDAP process will be unable to access its own key.
A group called ssl-cert
already exists as the group-owner of the /etc/ssl/private
directory. We can add the user our OpenLDAP process runs under (openldap
) to this group:
- sudo usermod -aG ssl-cert openldap
Now, our OpenLDAP user has access to the directory. We still need to give that group ownership of the ldap_server.key
file though so that we can allow read access. Give the ssl-cert
group ownership over that file by typing:
- sudo chown :ssl-cert /etc/ssl/private/ldap_server.key
Now, give the ssl-cert
group read access to the file:
- sudo chmod 640 /etc/ssl/private/ldap_server.key
Our OpenSSL process can now access the key file properly.
We have our files and have configured access to the components correctly. Now, we need to modify our OpenLDAP configuration to use the files we’ve made. We will do this by creating an LDIF file with our configuration changes and loading it into our LDAP instance.
Move to your home directory and open a file called addcerts.ldif
. We will put our configuration changes in this file:
- cd ~
- nano addcerts.ldif
To make configuration changes, we need to target the cn=config
entry of the configuration DIT. We need to specify that we are wanting to modify the attributes of the entry. Afterwards we need to add the olcTLSCACertificateFile
, olcCertificateFile
, and olcCertificateKeyFile
attributes and set them to the correct file locations.
The end result will look like this:
dn: cn=config
changetype: modify
add: olcTLSCACertificateFile
olcTLSCACertificateFile: /etc/ssl/certs/ca_server.pem
-
add: olcTLSCertificateFile
olcTLSCertificateFile: /etc/ssl/certs/ldap_server.pem
-
add: olcTLSCertificateKeyFile
olcTLSCertificateKeyFile: /etc/ssl/private/ldap_server.key
Save and close the file when you are finished. Apply the changes to your OpenLDAP system using the ldapmodify
command:
- sudo ldapmodify -H ldapi:// -Y EXTERNAL -f addcerts.ldif
We can reload OpenLDAP to apply the changes:
- sudo service slapd force-reload
Our clients can now encrypt their connections to the server over the conventional ldap://
port by using STARTTLS.
In order to connect to the LDAP server and initiate a STARTTLS upgrade, the clients must have access to the certificate authority certificate and must request the upgrade.
If you are interacting with the OpenLDAP server from the server itself, you can set up the client utilities by copying the CA certificate and adjusting the client configuration file.
First, copy the CA certificate from the /etc/ssl/certs
directory to a file within the /etc/ldap
directory. We will call this file ca_certs.pem
. This file can be used to store all of the CA certificates that clients on this machine may wish to access. For our purposes, this will only contain a single certificate:
- sudo cp /etc/ssl/certs/ca_server.pem /etc/ldap/ca_certs.pem
Now, we can adjust the system-wide configuration file for the OpenLDAP utilities. Open up the configuration file in your text editor with sudo
privileges:
- sudo nano /etc/ldap/ldap.conf
Adjust the value of the TLS_CACERT
option to point to the file we just created:
. . .
TLS_CACERT /etc/ldap/ca_certs.pem
. . .
Save and close the file.
You should now be able to upgrade your connections to use STARTTLS by passing the -Z
option when using the OpenLDAP utilities. You can force STARTTLS upgrade by passing it twice. Test this by typing:
- ldapwhoami -H ldap:// -x -ZZ
This forces a STARTTLS upgrade. If this is successful, you should see:
anonymous
If you mis-configured something, you will likely see an error like this:
ldap_start_tls: Connect error (-11)
additional info: (unknown error code)
If you are connecting to your OpenLDAP server from remote servers, you will need to complete a similar process. First, you must copy the CA certificate to the client machine. You can do this easily with the scp
utility.
If you connect to your OpenLDAP server using SSH keys and your client machine is also remote, you will need to add them to an agent and forward them when connecting to your client machine.
To do this, on your local machine, start the SSH agent by typing:
- eval $(ssh-agent)
Add your SSH key to the agent by typing:
- ssh-add
Now, you can forward your SSH keys when you connect to your LDAP client machine by adding the -A
flag:
- ssh -A user@ldap_client
Once you are connected to the OpenLDAP client, you can copy the CA certificate by typing:
- scp user@ldap.example.com:/etc/ssl/certs/ca_server.pem ~/
Now, append the copied certificate to the list of CA certificates that the client knows about. This will append the certificate to the file if it already exists and will create the file if it doesn’t:
- cat ~/ca_server.pem | sudo tee -a /etc/ldap/ca_certs.pem
Next, we can adjust the global configuration file for the LDAP utilities to point to our ca_certs.pem
file. Open the file with sudo
privileges:
- sudo nano /etc/ldap/ldap.conf
Find the TLS_CACERT
option and set it to the ca_certs.pem
file:
. . .
TLS_CACERT /etc/ldap/ca_certs.pem
. . .
Save and close the file when you are finished.
Test the STARTTLS upgrade by typing this:
- ldapwhoami -H ldap://ldap.example.com -x -ZZ
If the STARTTLS upgrade is successful, you should see:
anonymous
We’ve successfully configured our OpenLDAP server so that it can seamlessly upgrade normal LDAP connections to TLS through the STARTTLS process. However, this still allows unencrypted sessions, which may not be what you want.
If you wish to force STARTTLS upgrades for every connection, you can adjust your server’s settings. We will only be applying this requirement to the regular DIT, not the configuration DIT accessible beneath the cn=config
entry.
First, you need to find the appropriate entry to modify. We will print a list of all of the DITs (directory information trees: the hierarchies of entries that an LDAP server handles) that the OpenLDAP server has information about as well as the entry that configures each DIT.
On your OpenLDAP server, type:
- sudo ldapsearch -H ldapi:// -Y EXTERNAL -b "cn=config" -LLL -Q "(olcSuffix=*)" dn olcSuffix
The response should look something like this:
dn: olcDatabase={1}hdb,cn=config
olcSuffix: dc=example,dc=com
You may have more DIT and database pairs if your server is configured to handle more than one DIT. Here, we have a single DIT with the base entry of dc=example,dc=com
, which would be the entry created for a domain of example.com
. This DIT’s configuration is handled by the olcDatabase={1}hdb,cn=config
entry. Make note of the DNs of the DITs you want to force encryption on.
We will use an LDIF file to make the changes. Create the LDIF file in your home directory. We will call it forcetls.ldif
:
- nano ~/forcetls.ldif
Inside, target the DN you want to force TLS on. In our case, this will be dn: olcDatabase={1}hdb,cn=config
. We will set the changetype
to “modify” and add the olcSecurity
attribute. Set the value of the attribute to “tls=1” to force TLS for this DIT:
dn: olcDatabase={1}hdb,cn=config
changetype: modify
add: olcSecurity
olcSecurity: tls=1
Save and close the file when you are finished.
To apply the change, type:
- sudo ldapmodify -H ldapi:// -Y EXTERNAL -f forcetls.ldif
Reload the OpenLDAP service by typing:
- sudo service slapd force-reload
Now, if you search the dc=example,dc=com
DIT, you will be refused if you do not use the -Z
option to initiate a STARTTLS upgrade:
- ldapsearch -H ldap:// -x -b "dc=example,dc=com" -LLL dn
Confidentiality required (13)
Additional information: TLS confidentiality required
We can demonstrate that STARTTLS connections still function correctly:
- ldapsearch -H ldap:// -x -b "dc=example,dc=com" -LLL -Z dn
dn: dc=example,dc=com
dn: cn=admin,dc=example,dc=com
You should now have an OpenLDAP server configured with STARTTLS encryption. Encrypting your connection to the OpenLDAP server with TLS allows you to verify the identity of the server you are connecting with. It also shields your traffic from intermediate parties. When connecting over an open network, encrypting your traffic is essential.
Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases.
This textbox defaults to using Markdown to format your answer.
You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link!
Sign up for Infrastructure as a Newsletter.
Working on improving health and education, reducing inequality, and spurring economic growth? We'd like to help.
Get paid to write technical tutorials and select a tech-focused charity to receive a matching donation.
Hello,
After working through this guide and completing successfully I unfortunately am no longer able to login to phpldapadmin.
I get the following error: Error: Confidentiality required (13) for user
I have added TLS_REQCERT allow
to my /etc/ldap/ldap.conf file and restart slapd and apache but still no luck.
Any ideas?
EDIT: Figured this out.
Poking in the phpldapadmin config.php file I found this. // $servers->setValue(‘server’,‘tls’,false);
I un commented it and changed the value to true and restarted apache. Good to go.
Hello,I have issues with connecting with a client after the forced TLS part
I followed this tutorial but when I ran the cmd ldapmodify to add addcerts.ldap getting the below error…
sudo ldapmodify -H ldapi:// -Y EXTERNAL -f addcerts.ldif
ldap_sasl_interactive_bind_s: Authentication method not supported (7) additional info: SASL(-4): no mechanism available: Couldn’t find mech EXTERNAL
Any suggestions ?
I setup apache with https, can I re-use those certs for ldap. Is it possible, but not best practise?
I followed the tutorial and was able to create the keys and certs and working with OpenLDAP - Thanks!
I noticed after I setup OpenLDAP that the CA cert is only valid for one year while the server cert is good for ~10 years. What happens when the CA cert expires? Does it invalidate the server cert? Is there a way to create a new CA cert and keep the server cert (does this break the “chain”)?
Thanks
I struggled with being unable to authenticate using su after following the “Force Connections to Use TLS (Optional)” settings. Finally, I found what seems to be the solution at the bottom of the following page: https://superuser.com/questions/1162946/make-nss-ldap-use-starttls
tldr; -
This comment has been deleted
This comment has been deleted
This comment has been deleted
This comment has been deleted