Configure OpenLDAP: Difference between revisions

From Alpine Linux
m (→‎Creating an Organizational Structure: Marked a URL that can't be upgraded to https)
 
(34 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{ draft }}
Lightweight Directory Access Protocol (LDAP) is often employed as an authentication mechanism, providing a common username and password across many different applications. This tutorial shows how to install and configure the OpenLDAP package on Alpine Linux.
Lightweight Directory Access Protocol (LDAP) is often employed as an authentication mechanism, providing a common username and password across many different applications. This tutorial shows how to install and configure the OpenLDAP package on Alpine Linux.


Line 9: Line 7:
Here's how:
Here's how:


  apk add openldap openldap-back-mdb openldap-clients
{{Cmd|# apk add openldap openldap-back-mdb openldap-clients}}


But, before you start up the slapd service and go, there's a bit of configuration to do.
But, before you start up the slapd service and go, there's a bit of configuration to do.
Line 19: Line 17:
First, create the slapd.d directory with the proper ownership and permissions.
First, create the slapd.d directory with the proper ownership and permissions.


  install -m 755 -o ldap -g ldap -d /etc/openldap/slapd.d
{{Cmd|# install -m 755 -o ldap -g ldap -d /etc/openldap/slapd.d}}


Next, edit the slapd startup configuration to use the directory instead of the file.
Next, edit the slapd startup configuration to use the directory instead of the file.


# Open up /etc/conf.d/slapd in your favorite editor
# Open up <code>/etc/conf.d/slapd</code> in your favorite editor
# Comment out cfgfile="/etc/openldap/slapd.conf"
# Comment out <code>cfgfile="/etc/openldap/slapd.conf"</code>
# Uncomment cfgdir="/etc/openldap/slapd.d"
# Uncomment <code>cfgdir="/etc/openldap/slapd.d"</code>


Finally, get rid of the included slapd.conf file.
Finally, get rid of the included slapd.conf file.


  rm /etc/openldap/slapd.conf
{{Cmd|# rm /etc/openldap/slapd.conf}}


== Updating Shared Libraries Filenames ==
== Updating Shared Libraries File Names ==


Open up /etc/openldap/slapd.ldif in your favorite editor. Search for the filenames ending with <code>.la</code> and change the extension to <code>.so</code>
Open up <code>/etc/openldap/slapd.ldif</code> in your favorite editor. Search for the file names ending with <code>.la</code> and change the extension to <code>.so</code>
 
Or, you can do...
 
  sed -i s/\.la$/.so/g slapd.ldif


== Customizing Configuration for Your Domain ==
== Customizing Configuration for Your Domain ==
Line 44: Line 38:


# Edit slapd.ldif again.
# Edit slapd.ldif again.
# Find <code>olcSuffix:</code>
# Find the <code>olcSuffix:</code> keyword.
# Change to match your domain
# Change the value to match your domain
# Find <code>olcRootDN:</code>
# Find <code>olcRootDN:</code>
# Change to match your domain
# Change the value to match your domain


Or, assuming your domain is 'contoso.com' you can do...
Later, this document will assume the domain is <code>dc=home</code> or <code>dc=contoso,dc=com</code>, reflecting a domain of <code>home</code> or <code>contoso.com</code> respectively.
 
 
  sed -i s/dc=my-domain,dc=com/dc=contoso,dc=com/g /etc/openldap/slapd.ldif
== Adding Schema for Linux User Accounts ==
 
The basic OpenLDAP configuration does not include anything other than core schema definitions. To be useful for Linux systems, the inetOrgPerson schema and NIS schema are often included. The schema files are provided with the OpenLDAP package. All that needs to be done is to include them in the slapd.ldif configuration along with the cosine.ldif dependency.
 
# Edit <code>slapd.ldif</code> again.
# Find the line <code>include: file:///etc/openldap/schema/core.ldif</code>
# Append similar lines referencing ''cosine.ldif'', ''inetorgperson.ldif'', and ''nis.ldif''.
 
It should look like this when you're done:
 
{{Cat|/etc/openldap/slapd.ldif|include: file:///etc/openldap/schema/core.ldif
include: file:///etc/openldap/schema/cosine.ldif
include: file:///etc/openldap/schema/inetorgperson.ldif
include: file:///etc/openldap/schema/nis.ldif}}


== Import the Configuration ==
== Importing the Configuration ==
Before starting the slapd service, import the configuration into the backend database.


Use the <code>slapadd</code> command like this:
Verify slapd.ldif one last time and use the <code>slapadd</code> command to import it into the backend database.


  slapadd -n 0 -F /etc/openldap/slapd.d -l /etc/openldap/slapd.ldif
{{Cmd|# slapadd -n 0 -F /etc/openldap/slapd.d -l /etc/openldap/slapd.ldif}}


There should be no errors, only a "Closing DB..." message.
There should be no errors, only a "Closing DB..." message.


Change ownership on the files or the slapd service will refuse to start.
Next, change ownership on the resulting files in <code>/etc/openldap/slapd.d</code>


  chown -R ldap:ldap /etc/openldap/slapd.d/*
'''If you skip this step, the slapd service will refuse to start.'''
 
{{Cmd|# chown -R ldap:ldap /etc/openldap/slapd.d/*}}


== Configuring the slapd Service ==
== Configuring the slapd Service ==


The pid directory is missing. We'll need to create it or the service won't start.
The pid directory is missing. We'll need to create it or the service won't start, so this needs to be done first.
 
{{Cmd|# install -m 755 -o ldap -g ldap -d /var/lib/openldap/run}}
 
Next, you can start the service and enable it at boot.


  install -m 755 -o ldap -g ldap -d /var/lib/openldap/run
{{Cmd|# rc-service slapd start
&#35; rc-update add slapd}}


== Testing ==
== Testing ==
Line 76: Line 89:
The OpenLDAP quickstart guide uses the <code>ldapsearch</code> utility to test the configuration.
The OpenLDAP quickstart guide uses the <code>ldapsearch</code> utility to test the configuration.


  ldapsearch -x -b '' -s base '(objectclass=*)' namingContexts
{{Cmd|$ ldapsearch -x -b "" -s base '(objectclass{{=}}*)' namingContexts}}


You should see your domain.
You should see your domain.
Line 82: Line 95:
You can also test with <code>slapcat</code>
You can also test with <code>slapcat</code>


  slapcat -n 0
{{Cmd|$ slapcat -n 0}}


This will dump the entire config database in LDIF format. You can also pipe to grep and specify your domain name to verify everything looks correct. When using grep, remember LDAP uses the format dc=domain,dc=com and not the more familiar domain.com.
This will dump the entire config database in LDIF format. You can also pipe to grep and specify your domain name to verify everything looks correct. When using grep, remember LDAP uses the format dc=domain,dc=com and not the more familiar domain.com.
Line 88: Line 101:
Later, when you begin populating your LDAP database, you can use <code>slapcat -n 1</code> to see your information. (Zero is the config database. Numbers above zero are user-defined databases.)
Later, when you begin populating your LDAP database, you can use <code>slapcat -n 1</code> to see your information. (Zero is the config database. Numbers above zero are user-defined databases.)


== Reference ==
Finally, you can run <code>netstat -tln</code> and look for LDAP port 389 in the output.
 
== Scripted Installation ==
 
If you want to automate the steps above, use the following script. Be sure to adjust the DOMAIN value to fit your needs.
 
  export DOMAIN="dc=home"
 
  echo "Installing packages..."
  apk add openldap openldap-back-mdb openldap-clients
 
  echo "Configuring for v2.3+ style slapd.d config directory..."
  install -m 755 -o ldap -g ldap -d /etc/openldap/slapd.d
  sed -i~ \
    -e 's/^cfgfile=/#cfgfile=/' \
    -e 's/^#cfgdir=.*/cfgdir=\"\/etc\/openldap\/slapd.d\"/' \
    /etc/conf.d/slapd
  rm /etc/openldap/slapd.conf
 
  echo "Customizing for domain: ${DOMAIN}..."
  sed -i~ \
    -e 's/\.la$/.so/' \
    -e "s/dc=my-domain,dc=com/${DOMAIN}/" /etc/openldap/slapd.ldif
 
  echo "Adding schema for Linux user accounts..."
  cp /etc/openldap/slapd.ldif /etc/openldap/slapd.ldif~1
  awk '{ print } /^include:/ { sub("core", "cosine", $0); print $0; sub("cosine", "inetorgperson"); print $0; sub("inetorgperson", "nis"); print  }' /etc/openldap/slapd.ldif~1 >/etc/openldap/slapd.ldif
 
  echo "Importing configuration..."
  slapadd -n 0 -F /etc/openldap/slapd.d -l /etc/openldap/slapd.ldif
  chown -R ldap:ldap /etc/openldap/slapd.d/*
 
  echo "Configuring slapd service..."
  install -m 755 -o ldap -g ldap -d /var/lib/openldap/run
  service slapd start
  rc-update add slapd
 
== Creating an Organizational Structure ==
 
Now that the installation is done, you can start using your LDAP database. At a minimum, you'll need to create an organization within your LDAP directory. This is covered as step 11 in the OpenLDAP [https://openldap.org/doc/admin26/quickstart.html quickstart] document.
 
Here is an example using the contoso.com domain as the organization and <code>home</code>/<code>dc=home</code> as the base DN (update the baseDN if yours differs):
 
  cat <<EOF >org.ldif
  dn: dc=contoso,dc=com
  objectclass: dcObject
  objectclass: organization
  o: Fictional Company
  dc: contoso
 
  dn: cn=Manager,dc=contoso,dc=com
  objectclass: organizationalRole
  cn: Manager
  EOF
 
  ldapadd -x -D "cn=Manager,dc=home" -w secret -f org.ldif
 
You may also want to create organizational units (OUs) to help keep your directory tidy.
 
Here's an LDIF to create ''People'' and ''Groups'' as OUs:
 
  # Organizational unit for users
  dn: ou=People,dc=home
  changetype: add
  objectClass: organizationalUnit
  ou: People
 
  # Organizational unit for groups.
  dn: ou=Groups,dc=home
  changetype: add
  objectClass: organizationalUnit
  ou: Groups
 
Import the OUs with an ldapadd command similar to the one used to create the organization.
 
Now that this is done, you're ready to connect to the LDAP server with the administration tool of your choice and begin populating users, groups, etc. [http://ldapadmin.org/ LDAPAdmin]{{insecure url|TLS cert invalid}}  is an oldie, but a goodie for Windows users.
 
== Next Steps ==
 
The configuration presented here does not include provisions for TLS (encrypted) communication. It should not be used on an untrusted network. Refer to the official OpenLDAP docs  for instructions on setting up encrypted LDAP connections.
 
== References ==
 
* [https://openldap.org/doc/admin26/quickstart.html OpenLDAP Software 2.6 Administrator's Guide: A Quick-Start Guide]
* [https://stackoverflow.com/questions/72132704/did-i-import-inetorgperson-schema-correctly-for-openldap-on-alpine-linux/ ldap - Did I import inetOrgPerson schema correctly for OpenLDAP on Alpine Linux? - Stack Overflow]


https://openldap.org/doc/admin26/quickstart.html
[[Category:Networking]]

Latest revision as of 21:26, 26 July 2023

Lightweight Directory Access Protocol (LDAP) is often employed as an authentication mechanism, providing a common username and password across many different applications. This tutorial shows how to install and configure the OpenLDAP package on Alpine Linux.

Installing Packages

There is an Alpine package for OpenLDAP. However, simply adding the openldap apk is not enough to get you up and running. You'll also need to install a backend database and some LDAP command-line tools.

Here's how:

# apk add openldap openldap-back-mdb openldap-clients

But, before you start up the slapd service and go, there's a bit of configuration to do.

Customizing Configuration for OpenLDAP 2.3+

The Alpine OpenLDAP package can use either a configuration directory (slapd.d) or a configuration file (slapd.conf). Since OpenLDAP version 2.3, the preferred method is to use the slapd.d configuration directory. Any official OpenLDAP documentation, including their quickstart guide, will use this configuration method.

First, create the slapd.d directory with the proper ownership and permissions.

# install -m 755 -o ldap -g ldap -d /etc/openldap/slapd.d

Next, edit the slapd startup configuration to use the directory instead of the file.

  1. Open up /etc/conf.d/slapd in your favorite editor
  2. Comment out cfgfile="/etc/openldap/slapd.conf"
  3. Uncomment cfgdir="/etc/openldap/slapd.d"

Finally, get rid of the included slapd.conf file.

# rm /etc/openldap/slapd.conf

Updating Shared Libraries File Names

Open up /etc/openldap/slapd.ldif in your favorite editor. Search for the file names ending with .la and change the extension to .so

Customizing Configuration for Your Domain

Your LDAP domain can be the same as your DNS domain or it can be completely different. Whatever you choose, be sure to use the LDAP naming convention of dc=domain,dc=tld rather than the dot separated DNS style of domain.tld

  1. Edit slapd.ldif again.
  2. Find the olcSuffix: keyword.
  3. Change the value to match your domain
  4. Find olcRootDN:
  5. Change the value to match your domain

Later, this document will assume the domain is dc=home or dc=contoso,dc=com, reflecting a domain of home or contoso.com respectively.

Adding Schema for Linux User Accounts

The basic OpenLDAP configuration does not include anything other than core schema definitions. To be useful for Linux systems, the inetOrgPerson schema and NIS schema are often included. The schema files are provided with the OpenLDAP package. All that needs to be done is to include them in the slapd.ldif configuration along with the cosine.ldif dependency.

  1. Edit slapd.ldif again.
  2. Find the line include: file:///etc/openldap/schema/core.ldif
  3. Append similar lines referencing cosine.ldif, inetorgperson.ldif, and nis.ldif.

It should look like this when you're done:

Contents of /etc/openldap/slapd.ldif

include: file:///etc/openldap/schema/core.ldif include: file:///etc/openldap/schema/cosine.ldif include: file:///etc/openldap/schema/inetorgperson.ldif include: file:///etc/openldap/schema/nis.ldif

Importing the Configuration

Verify slapd.ldif one last time and use the slapadd command to import it into the backend database.

# slapadd -n 0 -F /etc/openldap/slapd.d -l /etc/openldap/slapd.ldif

There should be no errors, only a "Closing DB..." message.

Next, change ownership on the resulting files in /etc/openldap/slapd.d

If you skip this step, the slapd service will refuse to start.

# chown -R ldap:ldap /etc/openldap/slapd.d/*

Configuring the slapd Service

The pid directory is missing. We'll need to create it or the service won't start, so this needs to be done first.

# install -m 755 -o ldap -g ldap -d /var/lib/openldap/run

Next, you can start the service and enable it at boot.

# rc-service slapd start # rc-update add slapd

Testing

The OpenLDAP quickstart guide uses the ldapsearch utility to test the configuration.

$ ldapsearch -x -b "" -s base '(objectclass=*)' namingContexts

You should see your domain.

You can also test with slapcat

$ slapcat -n 0

This will dump the entire config database in LDIF format. You can also pipe to grep and specify your domain name to verify everything looks correct. When using grep, remember LDAP uses the format dc=domain,dc=com and not the more familiar domain.com.

Later, when you begin populating your LDAP database, you can use slapcat -n 1 to see your information. (Zero is the config database. Numbers above zero are user-defined databases.)

Finally, you can run netstat -tln and look for LDAP port 389 in the output.

Scripted Installation

If you want to automate the steps above, use the following script. Be sure to adjust the DOMAIN value to fit your needs.

 export DOMAIN="dc=home"
 
 echo "Installing packages..."
 apk add openldap openldap-back-mdb openldap-clients
 
 echo "Configuring for v2.3+ style slapd.d config directory..."
 install -m 755 -o ldap -g ldap -d /etc/openldap/slapd.d
 sed -i~ \
   -e 's/^cfgfile=/#cfgfile=/' \
   -e 's/^#cfgdir=.*/cfgdir=\"\/etc\/openldap\/slapd.d\"/' \
   /etc/conf.d/slapd
 rm /etc/openldap/slapd.conf
 
 echo "Customizing for domain: ${DOMAIN}..."
 sed -i~ \
   -e 's/\.la$/.so/' \
   -e "s/dc=my-domain,dc=com/${DOMAIN}/" /etc/openldap/slapd.ldif
 
 echo "Adding schema for Linux user accounts..."
 cp /etc/openldap/slapd.ldif /etc/openldap/slapd.ldif~1
 awk '{ print } /^include:/ { sub("core", "cosine", $0); print $0; sub("cosine", "inetorgperson"); print $0; sub("inetorgperson", "nis"); print  }' /etc/openldap/slapd.ldif~1 >/etc/openldap/slapd.ldif
 
 echo "Importing configuration..."
 slapadd -n 0 -F /etc/openldap/slapd.d -l /etc/openldap/slapd.ldif
 chown -R ldap:ldap /etc/openldap/slapd.d/*
 
 echo "Configuring slapd service..."
 install -m 755 -o ldap -g ldap -d /var/lib/openldap/run
 service slapd start
 rc-update add slapd

Creating an Organizational Structure

Now that the installation is done, you can start using your LDAP database. At a minimum, you'll need to create an organization within your LDAP directory. This is covered as step 11 in the OpenLDAP quickstart document.

Here is an example using the contoso.com domain as the organization and home/dc=home as the base DN (update the baseDN if yours differs):

 cat <<EOF >org.ldif
 dn: dc=contoso,dc=com
 objectclass: dcObject
 objectclass: organization
 o: Fictional Company
 dc: contoso
 
 dn: cn=Manager,dc=contoso,dc=com
 objectclass: organizationalRole
 cn: Manager
 EOF
 
 ldapadd -x -D "cn=Manager,dc=home" -w secret -f org.ldif

You may also want to create organizational units (OUs) to help keep your directory tidy.

Here's an LDIF to create People and Groups as OUs:

 # Organizational unit for users
 dn: ou=People,dc=home
 changetype: add
 objectClass: organizationalUnit
 ou: People
 
 # Organizational unit for groups.
 dn: ou=Groups,dc=home
 changetype: add
 objectClass: organizationalUnit
 ou: Groups

Import the OUs with an ldapadd command similar to the one used to create the organization.

Now that this is done, you're ready to connect to the LDAP server with the administration tool of your choice and begin populating users, groups, etc. LDAPAdmin 🔓 is an oldie, but a goodie for Windows users.

Next Steps

The configuration presented here does not include provisions for TLS (encrypted) communication. It should not be used on an untrusted network. Refer to the official OpenLDAP docs for instructions on setting up encrypted LDAP connections.

References