OpenLDAP is an open-source implementation of the LDAP protocol. It is mainly used as an address book (for e.g. email clients) or authentication backend to various services (the most famous one being Samba, which is used to emulate a domain controller) and basically holds the user data.

+

+

The closest analogue to real life, would be the telephone directory. Another generalised explanation of what an LDAP server does is that it is a database (which it basically is, but it is not relational) which is optimised for accessing the data and not writing them.

+

+

Commands relate to OpenLDAP that begin with {{ic|ldap}} (like {{ic|ldapsearch}}) are client-side utilities while commands that begin with {{ic|slap}} (like {{ic|slapcat}}) are server-side.

−

OpenLDAP, LDAP & Directory services are an enormous topic. Configuration is therefore complex. This page is a starting point for a basic openldap install on Archlinux and a sanity check.

+

OpenLDAP, LDAP & Directory services are an enormous topic. Configuration is therefore complex. This page is a starting point for a basic OpenLDAP installation and a sanity check.

−

If you are totally new to those concepts, [http://www.brennan.id.au/20-Shared_Address_Book_LDAP.html here] is an good introduction that is easy to understand and that will get you started, even if you are new to everything LDAP.

+

If you are totally new to those concepts, [http://www.brennan.id.au/20-Shared_Address_Book_LDAP.html this] is an good introduction that is easy to understand and that will get you started, even if you are new to everything LDAP.

== Installation ==

== Installation ==

Line 18:

Line 23:

{{Note|If you already have an OpenLDAP database on your machine, remove it by deleting everything inside {{ic|/var/lib/openldap/openldap-data/}}.}}

{{Note|If you already have an OpenLDAP database on your machine, remove it by deleting everything inside {{ic|/var/lib/openldap/openldap-data/}}.}}

−

First prepare the database directory. You will need to copy the default config file and set the proper ownership.

+

The server configuration file is located at {{ic|/etc/openldap/slapd.conf}}.

Edit the suffix and rootdn. The suffix typically is your domain name but it does not have to be. It depends on how you use your directory. We will use ''example'' for the domain name, and ''com'' for the tld. The rootdn is your LDAP administrator's name (we'll use ''root'' here).

−

−

# mkdir /run/openldap

−

# chown ldap:ldap /run/openldap

−

−

==== /etc/openldap/slapd.conf ====

−

Next we prepare slapd.conf. Add some typically used schemas...

−

{{bc|

−

include /etc/openldap/schema/cosine.schema

−

include /etc/openldap/schema/nis.schema

−

include /etc/openldap/schema/inetorgperson.schema

−

}}

−

Edit the suffix. Typically this is your domain name but it does not have to be. It depends on how you use your directory. We will use 'example' for the domain name, and 'com' for the tld. Also set your ldap administrators name (we'll use 'root' here)

{{bc|<nowiki>

{{bc|<nowiki>

suffix "dc=example,dc=com"

suffix "dc=example,dc=com"

Line 45:

Line 35:

# echo "rootpw $(slappasswd)" >> slapd.conf #add a line which includes the hashed password output from slappasswd

# echo "rootpw $(slappasswd)" >> slapd.conf #add a line which includes the hashed password output from slappasswd

−

ldap won't find things unless you index them. Read the [http://www.zytrax.com/books/ldap/ch6/#index ldap documentation] for details, you can use the following to start with. (add them to your {{ic|slapd.conf}})

+

You will likely want to add some typically used [http://www.openldap.org/doc/admin24/schema.html schemas] to the top of {{ic|slapd.conf}}:

+

{{bc|

+

include /etc/openldap/schema/cosine.schema

+

include /etc/openldap/schema/inetorgperson.schema

+

include /etc/openldap/schema/nis.schema

+

}}

+

+

You will likely want to add some typically used [http://www.openldap.org/doc/admin24/tuning.html#Indexes indexes] to the bottom of {{ic|slapd.conf}}:

{{bc|

{{bc|

index uid pres,eq

index uid pres,eq

Line 54:

Line 51:

}}

}}

−

'''Note: '''

+

Now prepare the database directory. You will need to copy the default config file and set the proper ownership:

Don't forget to run {{ic|slapindex}} after you populate your directory. (slapd needs to be stopped to do this). Then change the ownership for all the generated files:

+

Now prepare the run directory:

−

# chown ldap:ldap /var/lib/openldap/openldap-data/*

+

# mkdir /run/openldap

−

+

# chown ldap:ldap /run/openldap

−

If you want to use SSL, you have to specify a path to your certificates here. See [[OpenLDAP Authentication]].

Finally you can start the slapd daemon with {{ic|slapd.service}} [[systemd#Using units|using systemd]].

Finally you can start the slapd daemon with {{ic|slapd.service}} [[systemd#Using units|using systemd]].

−

==== /etc/conf.d/slapd ====

+

If you want to use SSL, see [[#OpenLDAP over TLS]].

−

Very important, you define here on which port the server should listen and if you want to use SSL, you will want to use the ldaps:// URI instead of the default ldap://

+

−

You can also specify additional slapd options here.

+

{{note|Index the directory after you populate it. You should stop slapd before doing this.

+

# slapindex

+

# chown ldap:ldap /var/lib/openldap/openldap-data/*

+

}}

=== The client ===

=== The client ===

−

The client is usually not such a big deal, just keep in mind that your apps that require LDAP auth use it, so if something goes wrong with LDAP, do not waste your time with the app, start debugging the client instead.

+

{{Note|Keep in mind that your apps that require LDAP auth use it, so if something goes wrong with LDAP, do not waste your time with the app, start debugging the client instead.}}

−

The client config file is located at /etc/openldap/ldap.conf

+

The client config file is located at {{ic|/etc/openldap/ldap.conf}}.

−

It is actually very simple.

+

+

It is quite simple: you'll only have to alter {{ic|BASE}} to reflect the suffix of the server, and {{ic|URI}} to reflect the address of the server.

If you decide to use SSL:

If you decide to use SSL:

−

* The protocol (ldap or ldaps) in the URI entry has to conform with the slapd configuration

+

* The protocol (ldap or ldaps) in the {{ic|URI}} entry has to conform with the slapd configuration

−

* If you decide to use self-signed certificates, you have to add them to TLS_CACERT

+

* If you decide to use self-signed certificates, add a {{ic|TLS_REQCERT allow}} entry

=== Test your new OpenLDAP installation ===

=== Test your new OpenLDAP installation ===

This is easy, just run the command below:

This is easy, just run the command below:

−

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

+

$ ldapsearch -x '(objectclass=*)'

−

Or more explicitly using the example configuration we had above:

+

Or authenticating as the rootdn (replacing {{ic|-x}} by {{ic|-D <user> -W}}), using the example configuration we had above:

{{Note|[http://web.archive.org/web/20130211222328/http://www.openldap.org/pub/ksoper/OpenLDAP_TLS.html#4.0 upstream documentation] is much more useful/complete than this section}}

{{Note|[http://web.archive.org/web/20130211222328/http://www.openldap.org/pub/ksoper/OpenLDAP_TLS.html#4.0 upstream documentation] is much more useful/complete than this section}}

−

If you access the Openldap server over the network and especially if you have sensitive data stored on the server you run the risk of someone sniffing your data which is sent clear-text. The next part will guide you on how to setup an SSL connection between the LDAP server and the client so the data will be sent encrypted.

+

If you access the OpenLDAP server over the network and especially if you have sensitive data stored on the server you run the risk of someone sniffing your data which is sent clear-text. The next part will guide you on how to setup an SSL connection between the LDAP server and the client so the data will be sent encrypted.

In order to use TLS, we must first create a certificate. You can have a certificate signed, or create your own Certificate Authority (CA), but for our purposed, a self-signed certificate will suffice.

In order to use TLS, we must first create a certificate. You can have a certificate signed, or create your own Certificate Authority (CA), but for our purposed, a self-signed certificate will suffice.

You will be prompted for information about your LDAP server. Much of the information can be left blank. The most important information is the common name. This must be set to the DNS name of your LDAP server. If your LDAP server's IP address resolves to example.org but its server certificate shows a CN of bad.example.org, LDAP clients will reject the certificate and will be unable to negotiate TLS connections (apparently the results are wholly unpredictable).

You will be prompted for information about your LDAP server. Much of the information can be left blank. The most important information is the common name. This must be set to the DNS name of your LDAP server. If your LDAP server's IP address resolves to example.org but its server certificate shows a CN of bad.example.org, LDAP clients will reject the certificate and will be unable to negotiate TLS connections (apparently the results are wholly unpredictable).

Now that the certificate files have been created copy them to {{ic|/etc/openldap/ssl/}} (if this directory doesn't exist create it) and secure them.

Now that the certificate files have been created copy them to {{ic|/etc/openldap/ssl/}} (if this directory doesn't exist create it) and secure them.

−

'''IMPORTANT:''' slapdcert.pem must be world readable because it contains the public key. slapdkey.pem on the other hand should only be readable for the ldap user for security reasons:

+

{{ic|slapdcert.pem}} must be world readable because it contains the public key. {{ic|slapdkey.pem}} on the other hand should only be readable for the ldap user for security reasons:

−

{{bc|

+

# cp slapdcert.pem slapdkey.pem /etc/openldap/ssl/

−

cp slapdcert.pem slapdkey.pem /etc/openldap/ssl/

+

# chmod 400 slapdkey.pem

−

chown ldap slapdkey.pem

+

# chmod 444 slapdcert.pem

−

chmod 400 slapdkey.pem

+

# chown ldap slapdkey.pem

−

chmod 444 slapdcert.pem

−

}}

==== Configure slapd for SSL ====

==== Configure slapd for SSL ====

Line 124:

Line 124:

==== Start slapd with SSL ====

==== Start slapd with SSL ====

−

In order to tell OpenLDAP to start using encryption, edit /etc/conf.d/slapd, uncomment the SLAPD_SERVICES line and set it to the following:

+

You will have to edit {{ic|slapd.service}} to change to protocol slapd listens on.

−

{{bc|1=SLAPD_SERVICES="ldaps:///"}}

+

−

Localhost connections don't need to use SSL so you can use this instead:

+

First, disable {{ic|slapd.service}} if it's enabled.

−

{{bc|1=SLAPD_SERVICES="ldap://127.0.0.1 ldaps:///:}}

+

Then, copy the stock service to {{ic|/etc/systemd/system/}}:

+

# cp /usr/lib/systemd/system/slapd.service /etc/systemd/system/

+

Edit it, and add {{ic|-h "ldaps:///"}} to {{ic|ExecStart}}. It should look like this:

+

{{hc|/etc/systemd/system/slapd.service|<nowiki>

+

ExecStart=/usr/bin/slapd -u ldap -g ldap -h "ldaps:///"</nowiki>}}

−

'''IMPORTANT:''' If you created a self-signed certificate above be sure to add the following line to /etc/openldap/ldap.conf or you won't be able connect to the server to test it:

+

Then reenable and start it:

+

# systemctl daemon-reload

+

# systemctl enable slapd.service

+

# systemctl restart slapd.service

−

TLS_REQCERT allow

+

Localhost connections don't need to use SSL so you could replace {{ic|"ldaps:///"}} by {{ic|"ldap://127.0.0.1 ldaps:///"}}.

−

Finally restart the server.

+

{{Note|If you created a self-signed certificate above be sure to add {{ic|TLS_REQCERT allow}} to {{ic|/etc/openldap/ldap.conf}} or you won't be able connect to the server.}}

== Next Steps ==

== Next Steps ==

−

You now have a basic ldap installation. The step is to design your directory. The design is heavily dependent on what you are using it for. If you are new to ldap, consider starting with a directory design recommended by the specific client services that will use the directory (PAM, Postfix, etc).

+

You now have a basic LDAP installation. The next step is to design your directory. The design is heavily dependent on what you are using it for. If you are new to LDAP, consider starting with a directory design recommended by the specific client services that will use the directory (PAM, [[Postfix]], etc).

A directory for system authentication is the [[LDAP Authentication]] article.

A directory for system authentication is the [[LDAP Authentication]] article.

* [[phpLDAPadmin]] is a web interface tool in the style of phpMyAdmin.

* [[phpLDAPadmin]] is a web interface tool in the style of phpMyAdmin.

−

* {{AUR|apachedirectorystudio2}} from the [[Arch User Repository]] is an Eclipse-based LDAP viewer. Works perfect for OpenLDAP installations.

+

* [[LDAP Authentication]]

+

* {{AUR|apachedirectorystudio2}} from the [[Arch User Repository]] is an Eclipse-based LDAP viewer. Works perfect with OpenLDAP installations.

Revision as of 01:16, 6 November 2013

This article or section is out of date.

Reason: slapd.conf(5) is deprecated; use slapd-config(5) (Discuss in Talk:OpenLDAP#)

OpenLDAP is an open-source implementation of the LDAP protocol. It is mainly used as an address book (for e.g. email clients) or authentication backend to various services (the most famous one being Samba, which is used to emulate a domain controller) and basically holds the user data.

The closest analogue to real life, would be the telephone directory. Another generalised explanation of what an LDAP server does is that it is a database (which it basically is, but it is not relational) which is optimised for accessing the data and not writing them.

Commands relate to OpenLDAP that begin with ldap (like ldapsearch) are client-side utilities while commands that begin with slap (like slapcat) are server-side.

OpenLDAP, LDAP & Directory services are an enormous topic. Configuration is therefore complex. This page is a starting point for a basic OpenLDAP installation and a sanity check.

If you are totally new to those concepts, this is an good introduction that is easy to understand and that will get you started, even if you are new to everything LDAP.

Installation

Configuration

The server

Note: If you already have an OpenLDAP database on your machine, remove it by deleting everything inside /var/lib/openldap/openldap-data/.

The server configuration file is located at /etc/openldap/slapd.conf.

Edit the suffix and rootdn. The suffix typically is your domain name but it does not have to be. It depends on how you use your directory. We will use example for the domain name, and com for the tld. The rootdn is your LDAP administrator's name (we'll use root here).

suffix "dc=example,dc=com"
rootdn "cn=root,dc=example,dc=com"

Now we delete the default root password and create a strong one:

# sed -i "/rootpw/ d" slapd.conf #find the line with rootpw and delete it
# echo "rootpw $(slappasswd)" >> slapd.conf #add a line which includes the hashed password output from slappasswd

You will likely want to add some typically used schemas to the top of slapd.conf:

include /etc/openldap/schema/cosine.schema
include /etc/openldap/schema/inetorgperson.schema
include /etc/openldap/schema/nis.schema

You will likely want to add some typically used indexes to the bottom of slapd.conf:

OpenLDAP over TLS

If you access the OpenLDAP server over the network and especially if you have sensitive data stored on the server you run the risk of someone sniffing your data which is sent clear-text. The next part will guide you on how to setup an SSL connection between the LDAP server and the client so the data will be sent encrypted.

In order to use TLS, we must first create a certificate. You can have a certificate signed, or create your own Certificate Authority (CA), but for our purposed, a self-signed certificate will suffice.

Warning: OpenLDAP cannot use a certificate that has a password associated to it.

Create a self-signed certificate

You will be prompted for information about your LDAP server. Much of the information can be left blank. The most important information is the common name. This must be set to the DNS name of your LDAP server. If your LDAP server's IP address resolves to example.org but its server certificate shows a CN of bad.example.org, LDAP clients will reject the certificate and will be unable to negotiate TLS connections (apparently the results are wholly unpredictable).

Now that the certificate files have been created copy them to /etc/openldap/ssl/ (if this directory doesn't exist create it) and secure them.
slapdcert.pem must be world readable because it contains the public key. slapdkey.pem on the other hand should only be readable for the ldap user for security reasons:

The TLSCipherSuite specifies a list of OpenSSL ciphers from which slapd will choose when negotiating TLS connections, in decreasing order of preference. In addition to those specific ciphers, you can use any of the wildcards supported by OpenSSL. NOTE: HIGH, MEDIUM, and +SSLv2 are all wildcards.

Note: To see which ciphers are supported by your local OpenSSL installation, type the following: openssl ciphers -v ALL

Start slapd with SSL

You will have to edit slapd.service to change to protocol slapd listens on.

First, disable slapd.service if it's enabled.
Then, copy the stock service to /etc/systemd/system/:

# cp /usr/lib/systemd/system/slapd.service /etc/systemd/system/

Edit it, and add -h "ldaps:///" to ExecStart. It should look like this:

Localhost connections don't need to use SSL so you could replace "ldaps:///" by "ldap://127.0.0.1 ldaps:///".

Note: If you created a self-signed certificate above be sure to add TLS_REQCERT allow to /etc/openldap/ldap.conf or you won't be able connect to the server.

Next Steps

You now have a basic LDAP installation. The next step is to design your directory. The design is heavily dependent on what you are using it for. If you are new to LDAP, consider starting with a directory design recommended by the specific client services that will use the directory (PAM, Postfix, etc).