= LewisSetupLdapServer =

This LewisSetup sub-guide describes the steps necessary to make the computer an OpenLDAP LDAP server.  The LDAP Server will be used to host the `dc=davisonlinehome,dc=name` domain.


== Installing LDAP ==

References:
 * https://help.ubuntu.com/8.10/serverguide/C/openldap-server.html

Run the following command to install OpenLDAP and related tools:
{{{
# apt-get install slapd ldap-utils
}}}
 * ''Administrator password:'' Enter a secure password, that you write down and store somewhere safe.

After installing, reconfigure the `slapd` to configure the OpenLDAP server:
{{{
# dpkg-reconfigure slapd
}}}
 * ''Omit OpenLDAP server configuration?:'' '''No'''
 * ''DNS domain name:'' enter the name of the server's domain, e.g. `davisonlinehome.name`
 * ''Organization name:'' enter the human-readable version of the server's domain, e.g. `Davis Online Home`
 * ''Administrator password:'' Enter a secure password, that you write down and store somewhere safe.
 * ''Database backend to use:'' '''HDB'''
 * ''Do you want the database to be removed when slapd is purged?:'' '''Yes'''
 * ''Move old database?:'' '''Yes'''
 * ''Allow LDAPv2 protocol?:'' '''No'''


The `/etc/default/slapd` configuration file stores the default settings that will be passed to the OpenLDAP server when it is started.  The `SLAPD_SERVICES` parameter needs to be edited to enable LDAP communication over secured and unsecured ports.  Later, unencrypted communication will be disabled.  Find the relevant line in the file and edit it to read as follows (replace "`hostname.domain.tld`" with the name of the LDAP server):
{{{
SLAPD_SERVICES="ldap://127.0.0.1:389/ ldap://hostname.domain.tld:389/ ldaps:/// ldapi:///"
}}}

Restart `slapd`:
{{{
# /etc/init.d/slapd restart
}}}


=== Testing Installation ===

Run the following command from the computer LDAP is installed on as well as from a remote computer (replace "`hostname.domain.tld`" with the name of the LDAP server):
{{{
$ ldapsearch -x -b dc=domain,dc=tld -D cn=admin,dc=domain,dc=tld -W -H ldap://hostname.domain.tld:389/
}}}

This should return two entries: the domain's `dc` object and an `admin` account.


== Populating LDAP ==

The simplest way to populate an LDAP directory is via [http://en.wikipedia.org/wiki/LDAP_Data_Interchange_Format LDIF files] and the [http://manpages.ubuntu.com/manpages/hardy/en/man1/ldapadd.1.html ldapadd] command.

The following is an example LDIF file that creates `systemAccounts`, `people`, and `groups` organizational Units (OUs) in an existing `dc=davisonlinehome,dc=name` domain as well as some objects for those OUs:
{{{
dn: ou=systemAccounts,dc=davisonlinehome,dc=name
objectClass: organizationalUnit
ou: systemAccounts

dn: ou=people,dc=davisonlinehome,dc=name
objectClass: organizationalUnit
ou: people

dn: ou=groups,dc=davisonlinehome,dc=name
objectClass: organizationalUnit
ou: groups

dn: uid=karl_admin,ou=systemAccounts,dc=davisonlinehome,dc=name
objectClass: simpleSecurityObject
objectClass: account
uid: karl_admin
description: LDAP administrator
userPassword: {KERBEROS}karl/admin@DAVISONLINEHOME.NAME

dn: uid=karl,ou=people,dc=davisonlinehome,dc=name
objectClass: inetOrgPerson
objectClass: posixAccount
uid: karl
sn: Davis
givenName: Karl
cn: Karl M. Davis
displayName: Karl M. Davis
initials: KMD
uidNumber: 10000
gidNumber: 10000
userPassword: {KERBEROS}karl@DAVISONLINEHOME.NAME
loginShell: /bin/bash
homeDirectory: /home/karl
mail: karl@davisonlinehome.name
postalAddress: 5872 North Edenbrook Lane
l: Tucson
st: Arizona
postalCode: 85741
mobile: 5208701461

dn: cn=karl,ou=groups,dc=davisonlinehome,dc=name
objectClass: posixGroup
cn: karl
gidNumber: 10000

dn: uid=erica,ou=people,dc=davisonlinehome,dc=name
objectClass: inetOrgPerson
objectClass: posixAccount
uid: erica
sn: Davis
givenName: Erica
cn: Erica A. Davis
displayName: Erica A. Davis
initials: EAD
uidNumber: 10001
gidNumber: 10001
userPassword: {KERBEROS}erica@DAVISONLINEHOME.NAME
loginShell: /bin/bash
homeDirectory: /home/erica
mail: ericaannedavis@gmail.com
postalAddress: 5872 North Edenbrook Lane
l: Tucson
st: Arizona
postalCode: 85741
mobile: 5203028170

dn: cn=erica,ou=groups,dc=davisonlinehome,dc=name
objectClass: posixGroup
cn: erica
gidNumber: 10001
}}}

To import an LDIF file, `somefile.ldif`, run the following command:
{{{
ldapadd -H ldap://hostname.domain.tld:389/ -D cn=admin,dc=domain,dc=tld -x -W -f somefile.ldif
}}}


== Enabling SASL Authentication ==

References:
 * http://docs.lucidinteractive.ca/index.php/OpenLDAP%2C_Kerberos%2C_GSSAPI
 * http://www.openldap.org/doc/admin24/sasl.html

OpenLDAP can be configured to use Kerberos for authentication.  The mechanisms used to achieve this are [http://en.wikipedia.org/wiki/Simple_Authentication_and_Security_Layer SASL] and [http://en.wikipedia.org/wiki/Generic_Security_Services_Application_Program_Interface GSSAPI].

Before starting, ensure that the correct DNS entries are set for the LDAP server:
 1. There must be a forward record that points from `hostname.domain.tld` to the LDAP server's IP address.
 1. There must be ''only one'' reverse record for the LDAP server's IP, which must point to the forward lookup record.

To enable this, do the following:
 1. Install the `libsasl2-modules-gssapi-mit` package:
{{{
# apt-get install libsasl2-modules-gssapi-mit
}}}
 1. Create a host principal for the LDAP server and export it to the default local keytab:
{{{
# kadmin -p krbuser/admin
kadmin:  addprinc -randkey host/hostname.domain.tld
kadmin:  ktadd host/hostname.domain.tld
kadmin:  quit
}}}
 1. Create an `ldap` principal for the LDAP server and export it to a separate keytab, which will keep the host keytab from becoming compromised if the OpenLDAP server is (replace "`krbuser/admin`" and "`hostname.domain.tld`" with appropriate values):
{{{
# kadmin -p krbuser/admin
kadmin:  addprinc -randkey ldap/hostname.domain.tld
kadmin:  ktadd -k /etc/ldap/ldap.keytab ldap/hostname.domain.tld
kadmin:  quit
# chown openldap /etc/ldap/ldap.keytab
}}}
 1. Set the `KRB5_KTNAME` variable in the `/etc/default/slapd` configuration file as follows:
{{{
export KRB5_KTNAME=/etc/ldap/ldap.keytab
}}}
 1. Add the required SASL configuration parameters to the end of the `/etc/ldap/slapd.conf` file (replace all realms, hostnames, and LDAP paths as appropriate):
{{{
# SASL Configuration
sasl-realm DAVISONLINEHOME.NAME
sasl-host lewis.davisonlinehome.name
authz-regexp
	uid=karl/admin,cn=davisonlinehome.name,cn=gssapi,cn=auth
	uid=karl_admin,ou=systemAccounts,dc=davisonlinehome,dc=name
authz-regexp
	uid=(.*),cn=davisonlinehome.name,cn=gssapi,cn=auth
	uid=$1,ou=people,dc=davisonlinehome,dc=name
}}}
 1. Restart `slapd`:
{{{
# /etc/init.d/slapd restart
}}}

Run the following command to test the SASL-GSSAPI setup:
{{{
$ ldapsearch -b dc=davisonlinehome,dc=name -H ldap://lewis.davisonlinehome.name:389/ -Y GSSAPI
}}}


=== Troubleshooting ===

If the server's reverse DNS entry is not setup correctly, you may observe the following symptoms:
 1. The test command will output the following:
{{{
SASL/GSSAPI authentication started
ldap_sasl_interactive_bind_s: Local error (-2)
}}}
 1. The following error will be recorded in the LDAP server's `/var/log/auth.log` file after running the test command:
{{{
ldapsearch: GSSAPI Error: Unspecified GSS failure.  Minor code may provide more information (Server not found in Kerberos database)
}}}

If the `sasl-realm` or `sasl-host` configuration directives are missing, the test command many output the following:
{{{
SASL/GSSAPI authentication started
ldap_sasl_interactive_bind_s: Other (e.g., implementation specific) error (80)
}}}


== Enabling TLS Encryption ==

[http://en.wikipedia.org/wiki/Transport_Layer_Security TLS] is a form of SSL encryption for communications.  With LDAP, TLS communications are identified by the `ldaps:///` protocol.  Enabling TLS for OpenLDAP requires an SSL certificate.  There are a few options for acquiring such a certificate:
 1. "Self-sign" a certificate.
    * Free.
    * Self-signed certificates have to be manually installed on each client, as they do not derive from the trusted root certificates already installed.
 1. Purchase a certificate from someone like [http://www.rapidssl.com/index_ssl.htm RapidSSL] or [http://www.verisign.com/ssl/index.html?sl-hppd Verisign].
    * These are generally easy to use but cost upwards of $75 per year.
 1. Purchase a chained certificate from someone like [https://www.godaddy.com/gdshop/ssl/ GoDaddy].
    * These certificates are more affordable: generally around $30 per year.
    * Certificates from these providers are "farther down" the certificate trust chain: they generally aren't descended directly from root certificates.  This isn't a problem per-se but it can be trickier to get them working with some applications.


=== Generating a Certificate Signing Request ===

Regardless of how the certificate is being created, the first thing to do is create a Certificate Signing Request (CSR).  To do so, follow these steps:
 1. Install the `openssl` package:
{{{
# apt-get install openssl
}}}
 1. Create a non-password-protected private key for the certificate/CSR:
{{{
$ openssl genrsa -out davisonlinehome.name.key 2048
}}}
 1. Generate the CSR:
{{{
$ openssl req -new -key davisonlinehome.name.key -out davisonlinehome.name.csr
}}}
    * ''Country Name (2 letter code) [AU]:'' `US`
    * ''State or Province Name (full name) [Some-State]:'' `Arizona`
    * ''Locality Name (eg, city) []:'' (leave this blank)
    * ''Organization Name (eg, company) [Internet Widgits Pty Ltd]:'' `Davis Family`
    * ''Organizational Unit Name (eg, section) []:'' (leave this blank)
    * ''Common Name (eg, YOUR name) []:'' `davisonlinehome.name`
    * ''Email Address []:'' `karl@davisonlinehome.name`
    * ''A challenge password []:'' (make something up and keep it temporarily)
    * ''An optional company name []:'' (leave this blank)


=== Generating a Self-Signed Certificate ===

TODO


=== Installing Certificate ===

Installing the certificate is simple:
 1. Copy the `.crt` file to `/etc/ssl/certs/`:
{{{
# cp davisonlinehome.name.crt /etc/ssl/certs/
}}}
 1. Copy the certificate's key file to `/etc/ssl/private/`:
{{{
# cp davisonlinehome.name.key /etc/ssl/private/
}}}
 1. Also copy the certificate's key file to `/etc/ldap/` and secure it:
{{{
# cp davisonlinehome.name.key /etc/ldap/
# chown openldap /etc/ldap/davisonlinehome.name.key
# chmod u=r,g=,o= /etc/ldap/davisonlinehome.name.key
}}}


==== Using a Certificate from !GoDaddy ====

References:
 * https://certs.godaddy.com/Repository.go

In order to use an SSL certificate purchased from !GoDaddy, their root and intermediate certificates will also need to be installed.  Follow these steps:
 1. Download their certificate bundle:
{{{
$ wget https://certs.godaddy.com/repository/gd_bundle.crt --no-check-certificate
}}}
 1. Copy the bundle `.crt` file to `/etc/ssl/certs/`:
{{{
# cp gd_bundle.crt /etc/ssl/certs/
}}}

Test the certificate chain with the following command:
{{{
$ openssl verify -CAfile /etc/ssl/certs/gd_bundle.crt /etc/ssl/certs/davisonlinehome.name.crt
}}}


=== Enabling TLS in OpenLDAP ===

Once the certificate chain has been verified as working, enabling its usage in OpenLDAP is simple:
 1. Edit `/etc/ldap/slapd.conf` and add:
{{{
# SSL Certificate Information
TLSCertificateFile /etc/ssl/certs/davisonlinehome.name.crt
TLSCertificateKeyFile /etc/ldap/davisonlinehome.name.key
TLSCACertificateFile /etc/ssl/certs/gd_bundle.crt
}}}
 1. Edit the `SLAPD_SERVICES` variable in `/etc/default/slapd` to disable non-encrypted communications (except from the server itself):
{{{
SLAPD_SERVICES="ldap://127.0.0.1:389/ ldaps:/// ldapi:///"
}}}
 1. Restart `slapd`:
{{{
# /etc/init.d/slapd restart
}}}