Kerberos supports a few different database backends. The default one (which we have used in our other Kerberos guides so far) is called db2. The DB types documentation shows all the options, one of which is LDAP.
Why use LDAP?
There are several reasons why one would want to have the Kerberos principals stored in LDAP as opposed to a local on-disk database. There are also cases when it is not a good idea. Each site has to evaluate the pros and cons. Here are a few:
- Pros:
- OpenLDAP replication is faster and more robust than the native Kerberos one, based on a cron job
- If you already have OpenLDAP set up for other things, such as storing users and groups, adding the Kerberos attributes can be beneficial, providing an integrated story
- Cons:
- Setting up the LDAP backend isn’t a trivial task and shouldn’t be attempted by administrators without prior knowledge of OpenLDAP
- As highlighted in the LDAP section of DB types, since
krb5kdcis single-threaded there may be higher latency in servicing requests when using the OpenLDAP backend
In this guide
In this section we’ll configure a primary and secondary Kerberos server to use OpenLDAP for the principal database. Note that as of version 1.18, the Key Distribution Center (KDC) from MIT Kerberos does not support a primary KDC using a read-only consumer (secondary) LDAP server. What we have to consider here is that a primary KDC is read-write, and it needs a read-write backend. The secondary KDCs can use both a read-write and read-only backend, because they are expected to be read-only. Therefore there are only some possible layouts we can use:
- Simple case:
- Primary KDC connected to primary OpenLDAP
- Secondary KDC connected to both primary and secondary OpenLDAP
- Extended simple case:
- Multiple primary KDCs connected to one primary OpenLDAP
- Multiple secondary KDCs connected to primary and secondary OpenLDAP
- OpenLDAP with multi-master replication:
- Multiple primary KDCs connected to all primary OpenLDAP servers
We haven’t covered OpenLDAP multi-master replication in this guide, so we will show the simple case only. The second scenario is an extension: just add another primary KDC to the mix, talking to the same primary OpenLDAP server.
Configure OpenLDAP
We are going to install the OpenLDAP server on the same host as the KDC, to simplify the communication between them. In such a setup, we can use the ldapi:/// transport, which is via a UNIX socket, and we don’t need to set up SSL certificates to secure the communication between the Kerberos services and OpenLDAP. Note, however, that SSL is still needed for the OpenLDAP replication. See LDAP with TLS for details.
If you want to use an existing OpenLDAP server, that’s also possible, but keep in mind that you should then use SSL for the communication between the KDC and this OpenLDAP server.
First, the necessary schema needs to be loaded on an OpenLDAP server that has network connectivity to both the primary and secondary KDCs. The rest of this section assumes that you also have LDAP replication configured between at least two servers. For information on setting up OpenLDAP see OpenLDAP Server.
Note:
cn=admin,dc=example,dc=comis a default admin user that is created during the installation of theslapdpackage (the OpenLDAP server). The domain component will change for your server, so adjust accordingly.
-
Install the necessary packages (it’s assumed that OpenLDAP is already installed):
sudo apt install krb5-kdc-ldap krb5-admin-server -
Next, extract the
kerberos.schema.gzfile:sudo cp /usr/share/doc/krb5-kdc-ldap/kerberos.schema.gz /etc/ldap/schema/ sudo gunzip /etc/ldap/schema/kerberos.schema.gz -
The Kerberos schema needs to be added to the
cn=configtree. This schema file needs to be converted to LDIF format before it can be added. For that we will use a helper tool, calledschema2ldif, provided by the package of the same name which is available in the Universe archive:sudo apt install schema2ldif -
To import the Kerberos schema, run:
$ sudo ldap-schema-manager -i kerberos.schema SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 executing 'ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/ldap/schema/kerberos.ldif' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 adding new entry "cn=kerberos,cn=schema,cn=config" -
With the new schema loaded, let’s index an attribute often used in searches:
$ sudo ldapmodify -Q -Y EXTERNAL -H ldapi:/// <<EOF dn: olcDatabase={1}mdb,cn=config add: olcDbIndex olcDbIndex: krbPrincipalName eq,pres,sub EOF modifying entry "olcDatabase={1}mdb,cn=config" -
Let’s create LDAP entries for the Kerberos administrative entities that will contact the OpenLDAP server to perform operations. There are two:
ldap_kdc_dn: needs to have read rights on the realm container, principal container and realm sub-trees. Ifdisable_last_successanddisable_lockoutare not set, however, thenldap_kdc_dnneeds write access to the Kerberos container just like the admin DN below.ldap_kadmind_dn: needs to have read and write rights on the realm container, principal container and realm sub-trees
Here is the command to create these entities:
$ ldapadd -x -D cn=admin,dc=example,dc=com -W <<EOF dn: uid=kdc-service,dc=example,dc=com uid: kdc-service objectClass: account objectClass: simpleSecurityObject userPassword: {CRYPT}x description: Account used for the Kerberos KDC dn: uid=kadmin-service,dc=example,dc=com uid: kadmin-service objectClass: account objectClass: simpleSecurityObject userPassword: {CRYPT}x description: Account used for the Kerberos Admin server EOF Enter LDAP Password: adding new entry "uid=kdc-service,dc=example,dc=com" adding new entry "uid=kadmin-service,dc=example,dc=com"Now let’s set a password for them. Note that first the tool asks for the password you want for the specified user DN, and then for the password of the
cn=adminDN:$ ldappasswd -x -D cn=admin,dc=example,dc=com -W -S uid=kdc-service,dc=example,dc=com New password: <-- password you want for uid-kdc-service Re-enter new password: Enter LDAP Password: <-- password for the dn specified with the -D optionRepeat for the
uid=kadmin-servicedn. These passwords will be needed later.You can test these with
ldapwhoami:$ ldapwhoami -x -D uid=kdc-service,dc=example,dc=com -W Enter LDAP Password: dn:uid=kdc-service,dc=example,dc=com -
Finally, update the Access Control Lists (ACL). These can be tricky, as it highly depends on what you have defined already. By default, the
slapdpackage configures your database with the following ACLs:olcAccess: {0}to attrs=userPassword by self write by anonymous auth by * none olcAccess: {1}to attrs=shadowLastChange by self write by * read olcAccess: {2}to * by * readWe need to insert new rules before the final
to * by * readone, to control access to the Kerberos related entries and attributes:$ sudo ldapmodify -Q -Y EXTERNAL -H ldapi:/// <<EOF dn: olcDatabase={1}mdb,cn=config add: olcAccess olcAccess: {2}to attrs=krbPrincipalKey by anonymous auth by dn.exact="uid=kdc-service,dc=example,dc=com" read by dn.exact="uid=kadmin-service,dc=example,dc=com" write by self write by * none - add: olcAccess olcAccess: {3}to dn.subtree="cn=krbContainer,dc=example,dc=com" by dn.exact="uid=kdc-service,dc=example,dc=com" read by dn.exact="uid=kadmin-service,dc=example,dc=com" write by * none EOF modifying entry "olcDatabase={1}mdb,cn=config" This will make the existing {2} rule become {4}. Check with sudo slapcat -b cn=config (the output below was reformatted a bit for clarity): olcAccess: {0}to attrs=userPassword by self write by anonymous auth by * none olcAccess: {1}to attrs=shadowLastChange by self write by * read olcAccess: {2}to attrs=krbPrincipalKey by anonymous auth by dn.exact="uid=kdc-service,dc=example,dc=com" read by dn.exact="uid=kadmin-service,dc=example,dc=com" write by self write by * none olcAccess: {3}to dn.subtree="cn=krbContainer,dc=example,dc=com" by dn.exact="uid=kdc-service,dc=example,dc=com" read by dn.exact="uid=kadmin-service,dc=example,dc=com" write by * none olcAccess: {4}to * by * read
Your LDAP directory is now ready to serve as a Kerberos principal database.
Primary KDC configuration (LDAP)
With OpenLDAP configured it is time to configure the KDC. In this example we are doing it in the same OpenLDAP server to take advantage of local UNIX socket communication.
-
Reconfigure the
krb5-configpackage if needed to get a good starting point with/etc/krb5.conf:sudo dpkg-reconfigure krb5-config -
Now edit
/etc/krb5.confadding thedatabase_moduleoption to theEXAMPLE.COMrealm section:[realms] EXAMPLE.COM = { kdc = kdc01.example.com kdc = kdc02.example.com admin_server = kdc01.example.com default_domain = example.com database_module = openldap_ldapconf }Then also add these new sections:
[dbdefaults] ldap_kerberos_container_dn = cn=krbContainer,dc=example,dc=com [dbmodules] openldap_ldapconf = { db_library = kldap # if either of these is false, then the ldap_kdc_dn needs to # have write access disable_last_success = true disable_lockout = true # this object needs to have read rights on # the realm container, principal container and realm sub-trees ldap_kdc_dn = "uid=kdc-service,dc=example,dc=com" # this object needs to have read and write rights on # the realm container, principal container and realm sub-trees ldap_kadmind_dn = "uid=kadmin-service,dc=example,dc=com" ldap_service_password_file = /etc/krb5kdc/service.keyfile ldap_servers = ldapi:/// ldap_conns_per_server = 5 } -
Next, use the
kdb5_ldap_utilutility to create the realm:$ sudo kdb5_ldap_util -D cn=admin,dc=example,dc=com create -subtrees dc=example,dc=com -r EXAMPLE.COM -s -H ldapi:/// Password for "cn=admin,dc=example,dc=com": Initializing database for realm 'EXAMPLE.COM' You will be prompted for the database Master Password. It is important that you NOT FORGET this password. Enter KDC database master key: Re-enter KDC database master key to verify: -
Create a stash of the password used to bind to the LDAP server. Run it once for each
ldap_kdc_dnandldap_kadmin_dn:sudo kdb5_ldap_util -D cn=admin,dc=example,dc=com stashsrvpw -f /etc/krb5kdc/service.keyfile uid=kdc-service,dc=example,dc=com sudo kdb5_ldap_util -D cn=admin,dc=example,dc=com stashsrvpw -f /etc/krb5kdc/service.keyfile uid=kadmin-service,dc=example,dc=comNote:
The/etc/krb5kdc/service.keyfilefile now contains clear text versions of the passwords used by the KDC to contact the LDAP server! -
Create a
/etc/krb5kdc/kadm5.aclfile for the admin server, if you haven’t already:*/admin@EXAMPLE.COM * -
Start the Kerberos KDC and admin server:
sudo systemctl start krb5-kdc.service krb5-admin-server.service
You can now add Kerberos principals to the LDAP database, and they will be copied to any other LDAP servers configured for replication. To add a principal using the kadmin.local utility enter:
$ sudo kadmin.local
Authenticating as principal root/admin@EXAMPLE.COM with password.
kadmin.local: addprinc ubuntu
WARNING: no policy specified for ubuntu@EXAMPLE.COM; defaulting to no policy
Enter password for principal "ubuntu@EXAMPLE.COM":
Re-enter password for principal "ubuntu@EXAMPLE.COM":
Principal "ubuntu@EXAMPLE.COM" created.
kadmin.local:
The above will create an ubuntu principal with a DN of krbPrincipalName=ubuntu@EXAMPLE.COM,cn=EXAMPLE.COM,cn=krbContainer,dc=example,dc=com.
Let’s say, however, that you already have a user in your directory, and it’s in uid=testuser1,ou=People,dc=example,dc=com. How can you add the Kerberos attributes to it? You use the -x parameter to specify the location. For the ldap_kadmin_dn to be able to write to it, we first need to update the ACLs:
$ sudo ldapmodify -Q -Y EXTERNAL -H ldapi:/// <<EOF
dn: olcDatabase={1}mdb,cn=config
add: olcAccess
olcAccess: {4}to dn.subtree=“ou=People,dc=example,dc=com”
by dn.exact=”uid=kdc-service,dc=example,dc=com” read
by dn.exact=”uid=kadmin-service,dc=example,dc=com” write
by * break
EOF
And now we can specify the new location:
$ sudo kadmin.local
Authenticating as principal root/admin@EXAMPLE.COM with password.
kadmin.local: addprinc -x dn=uid=testuser1,ou=People,dc=example,dc=com testuser1
WARNING: no policy specified for testuser1@EXAMPLE.COM; defaulting to no policy
Enter password for principal "testuser1@EXAMPLE.COM":
Re-enter password for principal "testuser1@EXAMPLE.COM":
Principal "testuser1@EXAMPLE.COM" created.
Since the specified DN already exists, kadmin.local will just add the required Kerberos attributes to this existing entry. If it didn’t exist, it would be created from scratch, with only the Kerberos attributes, just like what happened with the ubuntu example above, but in the specified location.
Note:
Theldap_kadmin_dnDN (uid=kadmin-servicein our example) does not have write access to the location specified by the-xparameter, you will get anInsufficient accesserror.
Both places are visible for kinit, since, when the realm was created with kdb5_ldap_util, the default value for the search scope and base were taken: subtree, and dc=example,dc=com.
Secondary KDC configuration (LDAP)
The setup of the secondary KDC (and its OpenLDAP replica) is very similar. Once you have the OpenLDAP replication setup, repeat these steps on the secondary:
- Install
krb5-kdc-ldap,ldap-utils. Do not installkrb5-admin-server. - Load the Kerberos schema using
schema2ldif. - Add the index for
krbPrincipalName. - Add the ACLs.
- Configure
krb5.confin the same way, initially. If you want to, and if you configured SSL properly, you can addldaps://kdc01.example.comto theldap_serverslist afterldapi:///, so that the secondary KDC can have two LDAP backends at its disposal. - DO NOT run
kdb5_ldap_util. There is no need to create the database since it’s being replicated from the primary. - Copy over the following files from the primary KDC and place them in the same location on the secondary:
/etc/krb5kdc/stash/etc/krb5kdc/service.keyfile
- Start the KDC:
sudo systemctl start krb5-kdc.service
