# OpenLDAP Installation and Configuration

## Installing OpenLDAP Software

There are several options to install OpenLDAP

### Install OpenLDAP Using Stock Packages

The ideal way is to install OpenLDAP using packages from your OS distribution. E.g. for Ubuntu use:

``apt-get install slapd ldap-utils``

OS distribution packages used to be quite outdated in the past. However, it looks like the situation has improved and the packages are reasonable recent. E.g. Ubuntu 20.04 LTS comes with OpenLDAP 2.4.49.

### Install From Symas Packages

Symas Corporation is the commercial sponsor of OpenLDAP. Symas provides Silver and Gold version of OpenLDAP which can be downloaded here:

However, there is a catch. The Silver version does not contain several essential overlays such as sssvlv and does not support replication. This is practically useless. The Gold version is only available under commercial subscription.

Moreover, according to our experience, installation of Symas packages is not entirely straightforward.

## Slapdconf

Administration of OpenLDAP is not exactly easy. Therefore we have created an `slapdconf` utility to simplify some OpenLDAP administration tasks. The utility is a Perl script.

The script needs some common Perl libraries: `Net::LDAP`, `Authen::SASL` and perldoc. The libraries can usually be installed from OS packages. For example, this how to install them on Ubuntu:

``sudo apt install libnet-ldap-perl libauthen-sasl-perl perl-doc``

Slapdconf has a comprehensive help message:

``slapdconf --help``

In Ubuntu, the default OpenLDAP package (`slapd`) is pre-configured to tread the `root` user as LDAP server administrator. Therefore the easiest way to configure OpenLDAP is to run `slapdconf` as root:

``sudo slapdconf list-suffixes``

This is using the default `slapdconf` setting, which is to use `ldapi:///` endpoint of OpenLDAP and EXTERNAL SASL authentication. The `ldapi` endpoint may not be enabled by default. In Ubuntu, it can be enabled by modifying `SLAPD_SERVICES` line in `/etc/default/slapd` file (see below).

The rest of this guide will use `slapdconf` for configuring OpenLDAP, as doing it using the OpenLDAP way can be quite nightmarish.

## Setting up SSL/TLS

In theory, it is as simple as:

``````slapdconf set-server-prop olcTLSCACertificateFile:/etc/ldap/tls/cacert.pem
slapdconf set-server-prop olcTLSCertificateFile:/etc/ldap/tls/triglav.example.com-cert.pem
slapdconf set-server-prop olcTLSCertificateKeyFile:/etc/ldap/tls/triglav.example.com-privkey.pem
slapdconf set-server-prop olcTLSCipherSuite:NORMAL``````

However, OpenLDAP and TLS are never as easy in practice.

### TLS on Debian/Ubuntu

When running on Debian/Ubuntu, the things are a bit more difficult. Debian-based OpenLDAP packages are linked with GnuTLS instead of OpenSSL. The OpenLDAP-GnuTLS integration leaves a lot to be desired. E.g. you will not see any diagnostic or error message from GnuTLS. All you got is mysterious "code 80" error. There are also groups and apparmor that needs to be set up when using letsencrypt or similar certificate management.

Firstly, you have to make sure that OpenLDAP can read the certificates and the key. If you are using letsencrypt, you will need to make sure the files are readable by the `ssl-cert` group. Then you need to add `opendlap` account to the `ssl-cert` group. However, the access is still prohibited by apparmor. Therefore you need to allow `slapd` to access the `/etc/letsencrypt` directory:

/etc/apparmor.d/local/usr.sbin.slapd
``/etc/letsencrypt/** r,``
 It is perhaps better to be more specific in the pathname if your machine has several certificates. E.g. allow access only to certificate/keys for one specific host only. We leave that as an exercise for the reader.

Restart apparmor and slapd afterwards:

``````sudo systemctl restart apparmor
sudo systemctl restart slapd``````

GnuTLS needs to set both the cert and the key in one operation. Therefore you will need to do this:

``````slapdconf set-server-prop olcTLSCACertificateFile:/etc/ldap/tls/cacert.pem
slapdconf set-server-prop olcTLSCertificateFile:/etc/ldap/tls/triglav.example.com-cert.pem olcTLSCertificateKeyFile:/etc/ldap/tls/triglav.example.com-privkey.pem
slapdconf set-server-prop olcTLSCipherSuite:NORMAL``````

Finally, you need to add LDAPS port (663) to the list of ports that `slapd` listens on:

/etc/default/slapd
``SLAPD_SERVICES="ldap:/// ldaps:/// ldapi:///"``

and restart `slapd`

``sudo systemctl restart slapd``

If you ever encounter a GnuTLS problem, you will need to enable GnuTLS logging to see what is the problem. You can use `GNUTLS_DEBUG_LEVEL` environment variable to enable the logging. However, GnuTLS logs the messages on STDOUT/STDERR, not in syslog. Therefore perhaps the easiest way is to set the `GNUTLS_DEBUG_LEVEL` variable in shell and then run `slapd` in foreground by using the `-d` option (as root):

``````systemctl stop slapd
export GNUTLS_DEBUG_LEVEL=10
/usr/sbin/slapd -h "ldap:/// ldaps:/// ldapi:///" -g openldap -u openldap -F /etc/ldap/slapd.d -d 256``````

Once you figure out what the problem is, you can start OpenLDAP using `systemctl` again.

## Initializing OpenLDAP

The database and suffix might have been created during software installation. To check if that is the case use the following command:

### Ports

Ubuntu OpenLDAP has port specification in `/etc/default/slapd`:

/etc/default/slapd
``SLAPD_SERVICES="ldap://0.0.0.0:1389/ ldapi:///"``

Symas OpenLDAP has the specification of ports in /opt/symas/etc/openldap/symas-openldap.conf

/opt/symas/etc/openldap/symas-openldap.conf
``HOST_LIST="ldap://0.0.0.0:1389/"``

### Creating the Database and Suffix

To create new suffix:

``````$mkdir /var/lib/ldap/example$ chown openldap:openldap /var/lib/ldap/example
$slapdconf create-suffix dc=example,dc=com --dbDir /var/lib/ldap/example --rootPassword secret`````` This command creates a directory for the new database and sets correct permissions. The last line creates the database and suffix in the server. You may need to set maximum database size: ``$ slapdconf set-suffix-prop dc=example,dc=com olcDbMaxSize:100000000``
 On Ubuntu 16 to make the create suffix work, one has to first load the module. This does not seem to be necessary in newer OpenLDAP/Ubuntu versions. ``\$ slapdconf add-module back_mdb``

### Setting up Overlays

``````slapdconf add-module sssvlv

``````slapdconf add-module ppolicy
ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/ldap/schema/ppolicy.ldif

Installing `memberof` overlay

``````slapdconf add-module memberof

Installing refint overlay to support referential integrity - this requires `<explicitReferentialIntegrity>false</explicitReferentialIntegrity>` in midPoint resource association configuration

``````slapdconf add-module refint
slapdconf  add-overlay dc=example,dc=com refint olcRefintConfig 'olcRefintAttribute:memberof member manager owner'``````

### Populating the Suffix

When the suffix is created it is completely empty. Not even the base object is there. The following command creates the basic objects of the suffix:

``ldapgenerate -D "cn=admin,dc=example,dc=com" -w secret -i -s dc=example,dc=com``
 The suffix root user must be used explicitly when creating a base object for the suffix. The EXTERNAL SASL authentication will not work here.

## Setting up MidPoint Access

Create `ou=Administrators,dc=example,dc=com` subtree and adminstration user by importing following LDIF:

``````dn: ou=Administrators,dc=example,dc=com
objectclass: top
objectclass: organizationalunit

objectclass: top
objectclass: person
cn: idm
description: Special LDAP acccount used by the IDM
to access the LDAP data.
 Make sure that the empty line is really empty and that it does not contains spaces or any white characters.

Use the following command (as root):

``ldapadd -Y EXTERNAL -H ldapi:/// -f admin.ldif``

### Setting Up ACLs

Setup ACLs that allow access for midpoint user to the directory:

aci.ldif
``````dn: olcDatabase={1}mdb,cn=config
changetype: modify
replace: olcAccess
olcAccess: to attrs=userPassword,shadowLastChange by dn="cn=idm,ou=Administrators,dc=example,dc=com" write by dn.exact=gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth write by anonymous auth by self write by * none
olcAccess: to dn.base="" by * read
olcAccess: to dn.subtree="ou=people,dc=example,dc=com" by dn="cn=idm,ou=Administrators,dc=example,dc=com" write
olcAccess: to dn.subtree="ou=groups,dc=example,dc=com" by dn="cn=idm,ou=Administrators,dc=example,dc=com" write

Use the following command (as root):

``ldapmodify -Y EXTERNAL -H ldapi:/// -f aci.ldif``

Or you can use ldapconf to set up the ACLs:

``slapdconf edit-suffix-acis dc=example,dc=com``

### Setting Up Limits

limits.ldif
``````dn: olcDatabase={1}mdb,cn=config
changetype: modify
replace: olcLimits

Or you can use slapdconf:

``slapdconf set-suffix-prop dc=example,dc=com 'olcLimits:dn.exact="cn=idm,ou=Administrators,dc=example,dc=com" size.prtotal=unlimited'``

pwpolicy.ldif
``````dn: cn=pwpolicy,dc=example,dc=com
objectclass: pwdPolicy
objectClass: person
cn: pwpolicy
sn: pwpolicy
pwdMaxFailure: 3
pwdLockout: TRUE
pwdLockoutDuration: 60``````
``````ldapadd -Y EXTERNAL -H ldapi:/// -f pwpolicy.ldif
slapdconf set-overlay-prop dc=example,dc=com ppolicy olcPPolicyDefault:cn=pwpolicy,dc=example,dc=com``````

## How to install both Ubuntu OpenLDAP and Symas OpenLDAP

Overall, do not try this. But if you have to, this what you do.

1. Install Symas OpenLDAP from Symas deb packages

2. Initialize configuration as per Symas doc

3. Stop slapd: /etc/init.d/solserver stop

4. Edit /opt/symas/etc/openldap/symas-openldap.conf, change port number

5. Edit /etc/init.d/solserver and change "Provides: slapd" to "Provides: solserver"

6. apt-get install slapd