LDAP

We use OpenLDAP for directory services. Our primary LDAP server is auth1 and our secondary LDAP server is auth2.

ehashman's Guide to Setting up OpenLDAP on Debian

Welcome to my nightmare.

What is LDAP?

LDAP: Lightweight Directory Access Protocol
An open, vendor-neutral, industry standard application protocol for accessing and maintaining distributed directory information services over an Internet Protocol (IP) network. — Wikipedia: LDAP

In this case, "directory" refers to the user directory, like on an old-school Rolodex. Many groups use LDAP to maintain their user directory, including the University (the "WatIAM" identity management system), the Computer Science Club, and even the UW Amateur Radio Club.

This is a guide documenting how to set up LDAP on a Debian Linux system.

First steps

Ensure that openldap is installed on the machine:
```
# apt-get install slapd ldap-utils
```
Debian will do a lot of magic and set up a skeleton LDAP server and get it running. We need to configure that further.
Let's set up logging before we forget. Create the following files in /var/log:
```
# mkdir /var/log/ldap
# touch /var/log/ldap.log
```
Set ownership correctly:
```
# chown openldap:openldap /var/log/ldap
```

Set up rsyslog to dump the LDAP logs into /var/log/ldap.log by adding the following lines:

# vim /etc/rsyslog.conf
...
# Grab ldap logs, don't duplicate in syslog
local4.*                        /var/log/ldap.log

Set up log rotation for these by creating the file /etc/logrotate.d/ldap with the following contents:

/var/log/ldap/*log {
    weekly
    missingok
    rotate 1000
    compress
    delaycompress
    notifempty
    create 0640 openldap adm
    postrotate
        if [ -f /var/run/slapd/slapd.pid ]; then
            /etc/init.d/slapd restart >/dev/null 2>&1
        fi
    endscript
}

/var/log/ldap.log {
    weekly
    missingok
    rotate 24
    compress
    delaycompress
    notifempty
}

As of OpenLDAP 2.4, it doesn't actually create a config file for us. Apparently, this is a "feature": LDAP maintainers think we should want to set this up via dynamic queries. We don't, so the first thing we need is our slapd.conf file.

Building `slapd.conf` from scratch

Get a copy to work with:

# scp uid@auth1.csclub.uwaterloo.ca:/etc/ldap/slapd.conf /etc/ldap/  ## you need CSC root for this

You'll want to comment out the TLS lines, and anything referring to Kerberos and access for now. You'll also want to comment out lines specifically referring to syscom and office staff.
Make sure you remove the reference to nonMemberTerm as an index, as we're going to remove this field.
You'll also need to generate a root password for the LDAP to bootstrap auth, like so:
```
# slappasswd
New password: 
Re-enter new password:
{SSHA}longhash
```
Add this line below rootdn in the slapd.conf:
```
rootpw          {SSHA}longhash
```

Now we want to edit all instances of "csclub" to be "wics" instead, e.g.:

suffix     "dc=wics,dc=uwaterloo,dc=ca"
rootdn     "cn=root,dc=wics,dc=uwaterloo,dc=ca"

Next, we need to grab all the relevant schemas:

scp -r uid@auth1.csclub.uwaterloo.ca:/etc/ldap/schema/ /tmp/schemas

Use the include directives to help you find the ones you need. I noticed we were missing sudo.schema, csc.schema, and rfc2307bis.schema.
Open up the csc.schema for editing; we're not using it verbatim. Remove the attributes studentid and nonMemberTerm and the objectclass club. Also make sure you change the OID so we don't clash with the CSC. Because we didn't want to go through the process of requesting a PEN number, we chose arbitrarily to use 26338, which belongs to IWICS Inc.
We also need to can the auto-generated config files, so do that:
```
# rm -rf /etc/openldap/slapd.d/*
```
Also nuke the auto-generated database:
```
# rm /var/lib/ldap/__db.*
```

Configure the database:

# cp /usr/share/slapd/DB_CONFIG /var/lib/ldap/
# chown openldap:openldap /var/lib/ldap/DB_CONFIG

Now we can generate the new configuration files:

# slaptest -f /etc/ldap/slapd.conf -F /etc/ldap/slapd.d/

And ensure that the permissions are all set correctly, lest this break something:
```
# chown -R openldap:openldap /etc/ldap/slapd.d
```

If at this point you get a nasty error, such as

5657d4db hdb_db_open: database "dc=wics,dc=uwaterloo,dc=ca": db_open(/var/lib/ldap/id2entry.bdb) failed: No such file or directory (2).
5657d4db backend_startup_one (type=hdb, suffix="dc=wics,dc=uwaterloo,dc=ca"): bi_db_open failed! (2)
slap_startup failed (test would succeed using the -u switch)

Just try restarting slapd, and see if that fixes the problem:

# service slapd stop
# service slapd start

Congratulations! Your LDAP service is now configured and running.

Getting TLS Up and Running

Now that we have our LDAP service, we'll want to be able to serve encrypted traffic. This is especially important for any remote access, since binding to LDAP (i.e. sending it a password for auth) occurs over plaintext, and we don't want to leak our admin password.
Our first step is to copy our SSL certificates into the correct places. Public ones go into /etc/ssl/certs/ and private ones go into /etc/ssl/private/.
Since the LDAP daemon needs to be able to read our private cert, we need to grant LDAP access to the private folder:
```
# chgrp openldap /etc/ssl/private 
# chmod g+x /etc/ssl/private
```

Next, uncomment the TLS-related settings in slapd.conf. These are TLSCertificateFile (the public cert), TLSCertificateKeyFile (the private key), TLSCACertificateFile (the intermediate CA cert), and TLSVerifyClient (set to "allow").

# enable TLS connections
TLSCertificateFile      /etc/ssl/certs/wics-wildcard.crt
TLSCertificateKeyFile   /etc/ssl/private/wics-wildcard.key

# enable TLS client authentication
TLSCACertificateFile    /etc/ssl/certs/GlobalSign_Intermediate_Root_SHA256_G2.pem
TLSVerifyClient         allow

Update all your LDAP settings:

# rm -rf /etc/openldap/slapd.d/*
# slaptest -f /etc/ldap/slapd.conf -F /etc/ldap/slapd.d/
# chown -R openldap:openldap /etc/ldap/slapd.d

And last, ensure that LDAP will actually serve ldaps:// by modifying the init script variables in /etc/default/:
```
# vim /etc/default/slapd
...
SLAPD_SERVICES="ldap:/// ldapi:/// ldaps:///"
...
```
Now you can restart the LDAP server:
```
# service slapd restart
```

And assuming this is successful, test to ensure LDAP is serving on port 636 for ldaps://:

# netstat -ntaup
Active Internet connections (servers and established)
Proto Recv-Q Send-Q Local Address           Foreign Address         State       PID/Program name
tcp        0      0 0.0.0.0:389             0.0.0.0:*               LISTEN      22847/slapd     
tcp        0      0 0.0.0.0:636             0.0.0.0:*               LISTEN      22847/slapd

Populating the Database

Now you'll need to start adding objects to the database. While we'll want to mostly do this programmatically, there are a few entries we'll need to bootstrap.

Root Entries

Start by creating a file tree.ldif to create a few necessary "roots" in our LDAP tree, with the contents:

dn: dc=wics,dc=uwaterloo,dc=ca
objectClass: dcObject
objectClass: organization
o: Women in Computer Science
dc: wics

dn: ou=People,dc=wics,dc=uwaterloo,dc=ca
objectClass: organizationalUnit
ou: People

dn: ou=Group,dc=wics,dc=uwaterloo,dc=ca
objectClass: organizationalUnit
ou: Group

Now attempt an LDAP add, using the password you set earlier:

# ldapadd -cxWD cn=root,dc=wics,dc=uwaterloo,dc=ca -f tree.ldif
Enter LDAP Password:
adding new entry "dc=wics,dc=uwaterloo,dc=ca"

adding new entry "ou=People,dc=wics,dc=uwaterloo,dc=ca"

adding new entry "ou=Group,dc=wics,dc=uwaterloo,dc=ca"

Test that everything turned out okay, by performing a query of the entire database:

# ldapsearch -x -h localhost
# extended LDIF
#
# LDAPv3
# base <dc=wics,dc=uwaterloo,dc=ca> (default) with scope subtree
# filter: (objectclass=*)
# requesting: ALL
#

# wics.uwaterloo.ca
dn: dc=wics,dc=uwaterloo,dc=ca
objectClass: dcObject
objectClass: organization
o: Women in Computer Science
dc: wics

# People, wics.uwaterloo.ca
dn: ou=People,dc=wics,dc=uwaterloo,dc=ca
objectClass: organizationalUnit
ou: People

# Group, wics.uwaterloo.ca
dn: ou=Group,dc=wics,dc=uwaterloo,dc=ca
objectClass: organizationalUnit
ou: Group

# search result
search: 2
result: 0 Success

# numResponses: 4
# numEntries: 3

Users and Groups

Next, add users to track the current GID and UID. This will save us from querying the entire database every time we make a new user or group. Create this file, nextxid.ldif:

dn: uid=nextuid,ou=People,dc=wics,dc=uwaterloo,dc=ca
cn: nextuid
objectClass: account
objectClass: posixAccount
objectClass: top
uidNumber: 20000
gidNumber: 20000
homeDirectory: /dev/null

dn: cn=nextgid,ou=Group,dc=wics,dc=uwaterloo,dc=ca
objectClass: group
objectClass: posixGroup
objectClass: top
gidNumber: 10000

You'll see here that our first GID is 10000 and our first UID is 20000.

Now add them, like you did with the roots of the tree:

# ldapadd -cxWD cn=root,dc=wics,dc=uwaterloo,dc=ca -f nextxid.ldif
Enter LDAP Password:
adding new entry "uid=nextuid,ou=People,dc=wics,dc=uwaterloo,dc=ca"

adding new entry "cn=nextgid,ou=Group,dc=wics,dc=uwaterloo,dc=ca"

Special `sudo` Entries

We also need to add a sudoers OU with a defaults object for default sudo settings. We also need entries for syscom, such that members of the syscom group can use sudo on all hosts, and for termcom, whose members can use sudo on only the office terminals. Call this one sudoers.ldif:

dn: ou=SUDOers,dc=wics,dc=uwaterloo,dc=ca
objectClass: organizationalUnit
ou: SUDOers

dn: cn=defaults,ou=SUDOers,dc=wics,dc=uwaterloo,dc=ca
objectClass: top
objectClass: sudoRole
cn: defaults
sudoOption: !lecture
sudoOption: env_reset
sudoOption: listpw=never
sudoOption: mailto="wics-sys@lists.uwaterloo.ca"
sudoOption: shell_noargs

dn: cn=%syscom,ou=SUDOers,dc=wics,dc=uwaterloo,dc=ca
objectClass: top
objectClass: sudoRole
cn: %syscom
sudoUser: %syscom
sudoHost: ALL
sudoCommand: ALL
sudoRunAsUser: ALL

dn: cn=%termcom,ou=SUDOers,dc=wics,dc=uwaterloo,dc=ca
objectClass: top
objectClass: sudoRole
cn: %termcom
sudoUser: %termcom
sudoHost: honk
sudoHost: hiss
sudoHost: gosling
sudoCommand: ALL
sudoRunAsUser: ALL

Now add them:

# ldapadd -cxWD cn=root,dc=wics,dc=uwaterloo,dc=ca -f sudoers.ldif
Enter LDAP Password:
adding new entry "ou=SUDOers,dc=wics,dc=uwaterloo,dc=ca"

adding new entry "cn=defaults,ou=SUDOers,dc=wics,dc=uwaterloo,dc=ca"

adding new entry "cn=%syscom,ou=SUDOers,dc=wics,dc=uwaterloo,dc=ca"

adding new entry "cn=%termcom,ou=SUDOers,dc=wics,dc=uwaterloo,dc=ca"

Last, add some special local groups via local-groups.ldif:
```
# ldapadd -cxWD cn=root,dc=wics,dc=uwaterloo,dc=ca -f local-groups.ldif
```
The local groups are special because they usually are present on all systems, but we want to be able to add users to them at the LDAP level. For instance, the audio group controls access to sound equipment, and the adm group controls log read access.
That's all the entries we have to add manually! Now we can use software for the rest. See weo for more details.

Querying LDAP

There are many tools available for issuing LDAP queries. Queries should be issued to ldap1.csclub.uwaterloo.ca. The search base you almost certainly want is dc=csclub,dc=uwaterloo,dc=ca. Read access is available without authentication; Kerberos is used to authenticate commands which require it.

Example:

ldapsearch -x -h ldap1.csclub.uwaterloo.ca -b dc=csclub,dc=uwaterloo,dc=ca uid=ctdalek

The -x option causes ldapsearch to switch to simple authentication rather than trying to authenticate via SASL (which will fail if you do not have a Kerberos ticket).

The University LDAP server (uwldap.uwaterloo.ca) can also be queried like this. Again, use "simple authentication" as read access is available (from on campus) without authentication. SASL authentication will fail without additional parameters.

Example:

ldapsearch -x -h uwldap.uwaterloo.ca -b dc=uwaterloo,dc=ca "cn=Prabhakar Ragde"

Replication

While ldap1.csclub.uwaterloo.ca (auth1) is the LDAP master, an up-to-date replica is available on ldap2.csclub.uwaterloo.ca (auth2).

In order to replicate changes from the master, the slave maintains an authenticated connection to the master which provides it with full read access to all changes.

Specifically, /etc/systemd/system/k5start-slapd.service maintains an active Kerberos ticket for ldap/auth2.csclub.uwaterloo.ca@CSCLUB.UWATERLOO.CA in /var/run/slapd/krb5cc. This is then used to authenticate the slave to the server, who maps this principal to cn=ldap-slave,dc=csclub,dc=uwaterloo,dc=ca, which in turn has full read privileges.

In the event of master failure, all hosts should fail LDAP reads seamlessly over to the slave.

Modifying LDAP entry

Editing entries can be easily done with ldapvi. First search for the entry using ldapsearch like above, and change ldapsearch -x to ldapvi -Y GSSAPI to make your edits.

Note that if your EDITOR enviroment is set to something not avaliable it will give out errors like

error (misc.c line 180): No such file or directory
editor died
error (ldapvi.c line 83): No such file or directory

This can be fixed by something like

EDITOR=vi ldapvi ******

Changing a user's username

Only a member of the Systems Committee can change a user's username. At all times, a user's username must match the user's username in WatIAM.

All changes to an account MUST be done in person so that identity can be confirmed. If a member cannot attend in person, then an alternate method of identity verification may be chosen by the Systems Administrator.

Edit entries in LDAP (ldapvi -Y GSSAPI)
- Find and replace the user's old username with the new one (%s/$OLD/$NEW/g)
Change the user's Kerberos principal (on auth1, renprinc $OLD $NEW)
Move the user's home directory (on aspartame, mv /users/$OLD /users/$NEW)
Change the user's csc-general (and csc-industry, if subscribed) email address for $OLD@csclub.uwaterloo.ca to $NEW@csclub.uwaterloo.ca
- https://mailman.csclub.uwaterloo.ca/admin/csc-general
If the user has vhosts on caffeine, update them to point to their new username

If the user's account has been around for a while, and they request it, forward email from their old username to their new one.

Edit /etc/aliases on mail. $OLD: $NEW
Run newaliases

LDAP

Contents

ehashman's Guide to Setting up OpenLDAP on Debian

What is LDAP?

First steps

Building `slapd.conf` from scratch

Getting TLS Up and Running

Populating the Database

Root Entries

Users and Groups

Special `sudo` Entries

Querying LDAP

Replication

Modifying LDAP entry

Changing a user's username

Navigation menu

LDAP

ehashman's Guide to Setting up OpenLDAP on Debian

What is LDAP?

First steps

Building slapd.conf from scratch

Getting TLS Up and Running

Populating the Database

Root Entries

Users and Groups

Special sudo Entries

Querying LDAP

Replication

Modifying LDAP entry

Changing a user's username

Navigation menu

Search

Building `slapd.conf` from scratch

Special `sudo` Entries