Installing an OpenLDAP server on FreeNAS

Learn how to install an OpenLDAP server in a jail on your FreeNAS server. Use OpenLDAP as a central store of user information that you can use in business applications, such as file sharing, collaboration, and chat.

In this tutorial, learn how to install OpenLDAP—an open source LDAP server—in a jail on your FreeNAS appliance. This tutorial also shows how to configure transport layer security (TLS) using a Let’s Encrypt certificate and how to install phpLDAPadmin to manage the directory using a web browser.

Preparing the jail

The instructions in this post host the app server in a jail on FreeBSD. To learn why we use jails for this purpose, check the Application server section of our self-hosted architecture post.

In this section, you’ll perform the following tasks:

• Create a jail.
• Configure networking on the jail.
• Install the prerequisite packages.

Run the commands from a session in your FreeBSD host.

To create a jail:

1. Fetch or update the release version of FreeBSD for jail usage:

   iocage fetch --release 11.3-RELEASE
   

2. Create a jail named ldapserver:

   iocage create --name ldapserver --release 11.3-RELEASE
   

To configure networking on the jail:

1. Configure the IP address. The following example sets the IP address to 192.168.1.123 using a subnet mask of 24 bits on the em0 interface. The command uses the CIDR notation.

   iocage set ip4_addr="em0|192.168.1.123/24" ldapserver
   

2. Configure the default router. The following example sets the default router to 192.168.1.1:

   iocage set defaultrouter=192.168.1.1 ldapserver
   

Start the jail and open a session to complete the rest of the tasks in this section:

iocage start ldapserver
iocage console ldapserver

Install the following packages:

• openldap-server
• openssl
• perl5
• ca_root_nss

pkg update
pkg install --yes openldap-server openssl perl5 ca_root_nss

Finally, copy the certificate files to the jail, including the files with the crt, key, and fullchain extensions. Then, register the certificate with the following command:

c_rehash PATH_TO_CERTIFICATE_FILES

Creating the database definition files

You can use the LDAP Data Interchange Format (LDIF) to define the OpenLDAP databases. You need the following information to create the LDIF files:

• The hostname of the LDAP server
• The absolute path to the files of your certificate

You need an LDIF file that defines the configuration database and another that defines the base objects of the domain. The slapd.ldif and domain.ldif files represent the configuration database and base domain objects, respectively.

To create the slapd.ldif file:

1. Create a hashed password for the LDAP administrator account using the slappasswd command. Save the original password and take note of the hashed password, which uses the following notation:

   {SSHA}hashed_password
   

2. Using a text editor, create a slapd.ldif file using the sample below. Edit the following sections of the file to suit your needs:
   • The olcTLSCertificate attributes, which specify the location of your certificate files.
   • The olcAccess attribute of the frontend settings. The value of the attribute specified below defines the following access level:
     • Users can edit their own entries.
     • Authenticated users can read all entries.
   • The olcRootPW attribute, which contains the hashed password of the administrator account. The slapd.ldif files uses this attribute twice.
   • Instances of ldapserver.example.org, which you should replace with the host of your LDAP server.
   • Instances of dc=example,dc=org, which you should replace with your own domain components.

   # See slapd-config(5) for details on configuration options.
   # This file should NOT be world readable.
   dn: cn=config
   objectClass: olcGlobal
   cn: config
   
   # Define global ACLs to disable default read access.
   olcArgsFile: /var/run/openldap/slapd.args
   olcPidFile: /var/run/openldap/slapd.pid
   olcTLSCertificateFile: ABSOLUTE_PATH_TO_YOUR_CERTIFICATE'S_CRT_FILE
   olcTLSCertificateKeyFile: ABSOLUTE_PATH_TO_YOUR_CERTIFICATE'S_KEY_FILE
   olcTLSCACertificateFile: ABSOLUTE_PATH_TO_YOUR_CERTIFICATE'S_FULLCHAIN_FILE
   olcTLSCipherSuite: ALL:!NULL
   olcTLSProtocolMin: 3.1
   olcTLSVerifyClient: never
   
   # Load dynamic backend modules:
   dn: cn=module,cn=config
   objectClass: olcModuleList
   cn: module
   olcModulepath: /usr/local/libexec/openldap
   olcModuleload: back_mdb.la
   
   dn: cn=schema,cn=config
   objectClass: olcSchemaConfig
   cn: schema
   
   include: file:///usr/local/etc/openldap/schema/core.ldif
   include: file:///usr/local/etc/openldap/schema/cosine.ldif
   include: file:///usr/local/etc/openldap/schema/inetorgperson.ldif
   include: file:///usr/local/etc/openldap/schema/nis.ldif
   
   # Frontend settings
   dn: olcDatabase={-1}frontend,cn=config
   objectClass: olcDatabaseConfig
   objectClass: olcFrontendConfig
   olcDatabase: {-1}frontend
   olcAccess: to *
          by self write
          by users read
          by anonymous auth
   
   dn: olcDatabase={0}config,cn=config
   objectClass: olcDatabaseConfig
   olcDatabase: {0}config
   olcAccess: to * by * none
   olcRootPW: HASHED_PASSWORD_INCLUDING_{SSHA}_PREFIX
   
   dn: olcOverlay=syncprov,olcDatabase={0}config,cn=config
   objectClass: olcOverlayConfig
   objectClass: olcSyncProvConfig
   olcOverlay: syncprov
   
   # LMDB database definitions
   dn: olcDatabase={1}mdb,cn=config
   objectClass: olcDatabaseConfig
   objectClass: olcMdbConfig
   olcDatabase: {1}mdb
   olcSuffix: dc=example,dc=org
   olcRootDN: cn=admin,dc=example,dc=org
   olcRootPW: HASHED_PASSWORD_INCLUDING_{SSHA}_PREFIX
   olcDbDirectory: /usr/local/etc/openldap/data
   olcDbIndex: objectClass eq
   
   dn: olcOverlay=syncprov,olcDatabase={1}mdb,cn=config
   objectClass: olcOverlayConfig
   objectClass: olcSyncProvConfig
   olcOverlay: syncprov
   

The domain.ldif file includes the following base objects of the domain:

• The organization object, which serves as the top level object in the database.
• A groups organizational unit, which hosts all the groups in the database.
• A users group, which hosts the users of the organization.
• An example user.

To create the domain.ldif file:

1. Create a hashed password for the example user account using the slappasswd command. Save the original password and take note of the hashed password, which uses the following notation:

   {SSHA}hashed_password
   

2. Using a text editor, create a domain.ldif file using the sample below. Edit the following sections of the file to suit your needs:
   • Instances of dc=example,dc=org, which you should replace with your own domain components.
   • Instances of example.org, which you should replace with the domain part of your LDAP server.
   • The userPassword attribute, which contains the hashed password of the example user account.

   dn: dc=example,dc=org
   objectClass: dcObject
   objectClass: organization
   o: example.org
   dc: home
   
   dn: ou=groups,dc=example,dc=org
   objectClass: top
   objectClass: organizationalunit
   ou: groups
   
   dn: ou=users,dc=example,dc=org
   objectClass: top
   objectClass: organizationalunit
   ou: users
   
   dn: uid=username,ou=users,dc=example,dc=org
   objectClass: top
   objectClass: posixAccount
   objectClass: shadowAccount
   objectClass: inetOrgPerson
   cn: Example User
   givenName: Example
   sn: User
   mail: [email protected]
   uid: username
   uidNumber: 10001
   gidNumber: 10001
   homeDirectory: /home/user/
   loginShell: /bin/bash
   userPassword: HASHED_PASSWORD_INCLUDING_{SSHA}_PREFIX
   

Loading the database definition files

1. Stop the sladp service:

   service slapd stop
   

2. Delete current configuration database:

   rm -rf /usr/local/etc/openldap/slapd.d
   mkdir /usr/local/etc/openldap/slapd.d
   

3. Delete current data folder:

   rm -rf /usr/local/etc/openldap/data
   mkdir /usr/local/etc/openldap/data
   

4. Import the slapd.ldif file:

   /usr/local/sbin/slapadd -n0 -F /usr/local/etc/openldap/slapd.d/ -l slapd.ldif
   

5. Start the service:

   /usr/local/libexec/slapd -F /usr/local/etc/openldap/slapd.d/
   

6. Load the base objects of the domain. Replace cn=admin,dc=example,dc=org with the user ID of your LDAP administrator account.

   ldapadd -W -D "cn=admin,dc=example,dc=org" -f domain.ldif
   

Configuring the service startup

Use the sysrc command to start the LDAP service when the jail boots. Replace ldapserver.example.org with the hostname of your LDAP server.

sysrc slapd_enable="YES"
sysrc slapd_flags='-h "ldapi://%2fvar%2frun%2fopenldap%2fldapi/ ldap://ldapserver.example.org/"'
sysrc slapd_sockets="/var/run/openldap/ldapi"
sysrc slapd_cn_config="YES"

This is a good time to restart the jail. Exit the session and restart the jail from the Jails page or running the following command on the Shell page:

iocage restart ldapserver

Querying the OpenLDAP service

To check that the service is running, you can use a query from a host that has the LDAP tools installed. In Debian-based distributions of Linux, such as Ubuntu, you can install the LDAP tools with the following command:

apt install ldap-utils

The following queries test different aspects of the service:

• To query the service anonymously:

  ldapwhoami -H ldap://ldapserver.example.org -x
  

  Expected output: anonymous

• To query the service in the context of a user:

  ldapwhoami -H ldap://ldapserver.example.org -x -D "uid=username,ou=users,dc=example,dc=org" -W
  

  Expected output: dn:uid=username,ou=users,dc=example,dc=org

• To query the service using TLS:

  ldapwhoami -H ldap://ldapserver.example.org -x -ZZ -D "uid=username,ou=users,dc=example,dc=org" -W
  

  Expected output: dn:uid=username,ou=users,dc=example,dc=org

You can add more objects to your LDAP database using the ldapmodify or ldapadd commands.

(Optional) Installing phpLDAPadmin

phpLDAPadmin is a web-based LDAP client that you can use to manage your directory. To use phpLDAPadmin:

Install the required packages and enable the web server:

1. Install the apache24, mod_php73, and phpldapadmin-php73 packages:

   pkg install --yes apache24 mod_php73 phpldapadmin-php73
   

2. Enable the web server at startup:

   sysrc apache24_enable="yes"
   

To configure the web server, update the following entries in the /usr/local/etc/apache24/httpd.conf file:

1. To configure the web server to process php files using the PHP module, add the following section:

   <FilesMatch "\.php$">
    SetHandler application/x-httpd-php
   </FilesMatch>
   <FilesMatch "\.phps$">
       SetHandler application/x-httpd-php-source
   </FilesMatch>
   

2. To configure index.php as the resource to look for when clients request an index of the directory, add index.php to the DirectoryIndex entry:

   <IfModule dir_module>
       DirectoryIndex index.php index.html
   </IfModule>
   

   Note that the previous DirectoryIndex entry should already exist. Just add index.php to the list of files.

3. Replace /usr/local/www/apache24/data in the DocumentRoot and Directory entries with /usr/local/www/phpldapadmin/htdocs:

   DocumentRoot "/usr/local/www/apache24/data"
   <Directory "/usr/local/www/apache24/data">
   

To configure phpLDAPadmin, add the following entries to the /usr/local/www/phpldapadmin/config/config.php file:

$servers->setValue('server','host','ldapserver.example.org');
$servers->setValue('server','port',389);
$servers->setValue('server','base',array('dc=example,dc=org'));
$servers->setValue('login','auth_type','session');
$servers->setValue('server','tls',true);

To configure access over HTTPS, you need an SSL certificate, such as the ones provided by Let’s Encrypt. Copy the crt and key files of your certificate to a folder in the jail. To configure your certificate:

1. In the /usr/local/etc/apache24/httpd.conf file:
   • Uncomment the LoadModule directives to enable the SSL and socache_shmcb modules by removing the leading # character:

     LoadModule ssl_module libexec/apache24/mod_ssl.so
     LoadModule socache_shmcb_module libexec/apache24/mod_socache_shmcb.so 
     

   • Uncomment the Include directive to add the SSL configuration file:

     Include etc/apache24/extra/httpd-ssl.conf
     

2. In the /usr/local/etc/apache24/extra/httpd-ssl.conf file.
   • Replace the DocumentRoot declaration. Replace the following line:

     DocumentRoot "/usr/local/www/apache24/data"
     

     with

     DocumentRoot "/usr/local/www/phpldapadmin/htdocs"
     

   • Replace the ServerName declaration. Replace the following line:

     ServerName www.example.org:443
     

     with the server name that matches your host and the server on the certificate:

     ServerName ldapserver.example.org:443
     

   • Update the SSLCertificateFile and SSLCertificateKeyFile entries with the path of the crt and key files of your certificate:

     SSLCertificateFile "path_to_your_certificate.crt" 
     SSLCertificateKeyFile "path_to_your_certificate.key"
     

Restart the web server:

service apache24 onerestart

Go to https://ldapserver.example.org and sign in with the cn=admin,dc=example,dc=org username.