kerberos/README.md

Kerberos Server

MIT Kerberos V KDC + admin server container running on Ubuntu 26.04.

Prerequisites

Kerberos is sensitive to hostname resolution. Before running this container:

• KRB5_KDC_HOST must resolve to the container from every client machine (forward DNS or /etc/hosts).
• The container's own hostname should match KRB5_KDC_HOST so that service tickets are issued for the correct principal. Set it with --hostname / the container runtime's hostname option.
• Reverse DNS (PTR records) for the KDC host is strongly recommended — some Kerberos operations fail without it.

DNS lookup of KDC addresses is disabled in the generated krb5.conf (dns_lookup_kdc = false); the value of KRB5_KDC_HOST is used directly instead.

Environment variables

Variable	Default	Description
KRB5_REALM	EXAMPLE.ORG	Kerberos realm (uppercase)
KRB5_DOMAIN	example.org	DNS domain mapped to the realm
KRB5_KDC_HOST	(required)	FQDN of this KDC, used by clients and in service ticket names
KRB5_MASTER_PASSWORD	(required on first start)	Database master key — set once, cannot be changed without destroying the database
KRB5_ADMIN_PRINCIPAL	admin	Name of the bootstrap admin principal
KRB5_ADMIN_PASSWORD	(required on first start)	Password for <admin>/admin@<REALM>

Copy env.example to ~/app-data/kerberos/kerberos.env and fill in real values before first run.

Important: KRB5_MASTER_PASSWORD and KRB5_ADMIN_PASSWORD are only required on first start. Once the realm is initialised (the database file exists in the volume), these variables are not read and can be removed from the env file for enhanced security. The master password cannot be changed without wiping the kerberos_data volume and reinitialising the realm, which invalidates all issued tickets and keytabs.

Build

./scripts/build.sh

Run

./scripts/run-container.sh

The kerberos_data volume (/var/lib/krb5kdc) holds the realm database, configuration, and keytab. All files are written once on first start. On subsequent starts the container requires no environment variables — the persisted configuration is used as-is. Sensitive variables (KRB5_MASTER_PASSWORD, KRB5_ADMIN_PASSWORD) can be removed from the env file after the realm is initialised.

Ports

Port	Protocol	Service
88	TCP/UDP	KDC (ticket granting)
464	TCP/UDP	kpasswd (password changes)
749	TCP	kadmin (remote administration)

Client configuration

Pre-authentication is required (+preauth is set by default), so clients must supply a password or keytab — anonymous TGT requests are rejected.

The KDC hostname (KRB5_KDC_HOST) must be resolvable from every client machine via DNS or a local hosts file entry.

Linux

Install the MIT Kerberos client tools:

sudo apt install krb5-user        # Debian / Ubuntu
sudo dnf install krb5-workstation # Fedora / RHEL

Create /etc/krb5.conf:

[libdefaults]
    default_realm = EXAMPLE.ORG

[realms]
    EXAMPLE.ORG = {
        kdc = kerberos.example.org
        admin_server = kerberos.example.org
    }

[domain_realm]
    .example.org = EXAMPLE.ORG
    example.org = EXAMPLE.ORG

kinit user@EXAMPLE.ORG   # obtain a ticket
klist                     # verify
kdestroy                  # release

macOS

Kerberos (Heimdal) is built into macOS — no installation required. It is interoperable with MIT KDCs.

Create /etc/krb5.conf with the same content as the Linux example above.

kinit user@EXAMPLE.ORG
klist
kdestroy

Acquired tickets are also visible in Ticket Viewer (/System/Library/CoreServices/Ticket Viewer.app).

For SSH with GSSAPI, add to ~/.ssh/config:

Host *.example.org
    GSSAPIAuthentication yes
    GSSAPIDelegateCredentials yes

Windows (standalone, not domain-joined)

Install MIT Kerberos for Windows (KfW) from web.mit.edu/kerberos/dist. The built-in Windows Kerberos provider (SSPI) is designed for Active Directory domain membership and is not suitable for standalone use against a custom KDC.

Create the configuration file at %ProgramData%\MIT\Kerberos5\krb5.ini (system-wide) or set the KRB5_CONFIG environment variable to point to a file of your choice:

[libdefaults]
    default_realm = EXAMPLE.ORG

[realms]
    EXAMPLE.ORG = {
        kdc = kerberos.example.org
        admin_server = kerberos.example.org
    }

[domain_realm]
    .example.org = EXAMPLE.ORG
    example.org = EXAMPLE.ORG

Use the KfW Network Identity Manager GUI or the bundled command-line tools from a Command Prompt:

kinit user@EXAMPLE.ORG
klist
kdestroy

Managing principals

Exec into the running container, then use kadmin.local (no password required):

container exec -it kerberos bash

# List all principals
kadmin.local -q "listprincs"

# Add a user principal
kadmin.local -q "addprinc username@REALM"

# Add a service principal and extract a keytab
kadmin.local -q "addprinc -randkey ldap/ldap.example.org@REALM"
kadmin.local -q "ktadd -k /tmp/ldap.keytab ldap/ldap.example.org@REALM"

OpenLDAP SASL/GSSAPI integration

1. Create the LDAP service principal and extract a keytab:

   kadmin.local -q "addprinc -randkey ldap/ldap.example.org@REALM"
   kadmin.local -q "ktadd -k /tmp/ldap.keytab ldap/ldap.example.org@REALM"
   

2. Copy the keytab into the OpenLDAP container at /etc/ldap/ldap.keytab.
3. Set KRB5_KTNAME=/etc/ldap/ldap.keytab in the OpenLDAP container environment.
4. Install libsasl2-modules-gssapi-mit in the OpenLDAP image and enable the GSSAPI SASL mechanism.