This is not meant to be a comprehensive guide by any means, but information on the Web for configuring OpenLDAP to authenticate using X.509 client certificates is lacking. And in some cases, over a decade old! It took me hours to find the documentation I needed, but only minutes to see it working once I had the correct “recipe”.
You should probably be running your own Certificate Authority for the purpose of generating client certificates, especially since you need one per user. You can lock it up tightly and only use it for the purposes of LDAP if you like. You can also use a certificate vendor like Thawte or GeoTrust or Comodo. Make sure you pick just one, though, because you will configure OpenLDAP to trust only that single CA to sign all the relevant client certificates. (This ensures that nobody can come in with a forged certificate signed by another vendor, or a self-signed one.)
The Ubuntu guide on making a CA is pretty decent, though unfortunately it uses the inferior GnuTLS package. That’s okay, because we are only using it for OpenLDAP. And actually, you can’t use OpenSSL generated certificates on Debian’s OpenLDAP because they patched it in such a way that the certificates cannot be read. (There are conflicting reports on whether this bug was fixed or not upstream.) Note that you definitely want to set a higher
expiration_days than the default 365! 10 or even 15 years isn’t unheard of, which is 5475 days if you were wondering.
Once you have either created your CA, or decided on a vendor, you may begin configuring OpenLDAP. Replace
authority.pem with the file name for your CA’s root certificate, and
ldap_key.pem for the server certificate and its private key. Note that the server certificate must have the FQDN of the LDAP server as its only CN. It may have a wildcard as a subjectAltName (or SAN) but the FQDN (normally something like ldap01.myproject.org) must be the CN.
TLSCACertificateFile /etc/ssl/certs/authority.pem TLSCertificateFile /etc/ssl/certs/ldap_cert.pem TLSCertificateKeyFile /etc/ssl/private/ldap_key.pem TLSVerifyCert try
With Dynamic Configuration, aka
cn=config, aka “OLC”/on-line configuration, aka …
dn: cn=config changetype: modify add: olcTLSCACertificateFile olcTLSCACertificateFile: /etc/ssl/certs/authority.pem - add: olcTLSCertificateFile olcTLSCertificateFile: /etc/ssl/certs/ldap_cert.pem - add: olcTLSCertificateKeyFile olcTLSCertificateKeyFile: /etc/ssl/private/ldap_key.pem - add: olcTLSVerifyCert olcTLSVerifyCert: try
Note that if you receive an error such as:
ldap_sasl_interactive_bind_s: Unknown authentication method (-6) additional info: SASL(-4): no mechanism available:
then you most likely forgot the
olcTLSVerifyCert like I did the first time 🙂 Note that there is nothing printed after “no mechanism available: “. That was the hardest part to debug! Hopefully this can help a few people out.
Also note that for client certificates to work correctly, the DN of the X.509 certificate must exactly match the DN of the LDAP object. If you cannot meet that requirement, you will need to look at authz-regexp: for cn=config, see this mailing list posting, and for standard configuration see the documentation. Note that I was unsuccessful in making this seemingly-useful feature work, but you may have better luck than I did.
- Configuring OpenLDAP for Client Certificate Authentication, The Moose and Squirrel Files
- OpenLDAP using OLC (cn=config), Zytrax LDAP
- Kerberos, GSSAPI, and SASL Authentication using LDAP: useful tips on ACLs for root DSE
- ldif(5) man page: always useful to have for cn=config
- The Source Code: sometimes you just have to see what’s going on inside
- GnuTLS certtool man page: for template format to make the CA cert much better than the Ubuntu guide suggested