Configure SASL GSSAPI and Kerberos Authentication in 389 Directory Server

Directory Server can authenticate LDAP clients with Kerberos tickets through SASL GSSAPI. Users obtain a ticket from the Kerberos realm, the LDAP client requests a service ticket for ldap/FQDN@REALM, and Directory Server validates that ticket with its service keytab. A SASL identity map then converts the Kerberos principal, such as [email protected], into an LDAP DN before ACIs authorize the mapped user.

This guide covers the service principal, instance keytab, KRB5_KTNAME, SASL identity mapping, fallback and priority, client testing, load-balancer hostname rules, and troubleshooting. It assumes an operational Kerberos realm already exists.

Before you start:

• Manage users and groups — test user uid=user1 under ou=people,dc=example,dc=com
• TLS, STARTTLS, and LDAPS — GSSAPI can authenticate over plain LDAP, but plain LDAP is protected only when the client and server negotiate a SASL security layer. Use LDAPS or STARTTLS when transport encryption must be guaranteed independently of SASL client settings.
• dsconf commands — SASL mapping configuration
• Get Effective Rights — verify ACI authorization after authentication

Tested on: Rocky Linux 10.2; 389 Directory Server 3.2.0.

The lab uses instance ldap1 on ldap1.example.com with Kerberos realm EXAMPLE.COM, LDAP user uid=user1,ou=people,dc=example,dc=com, and Kerberos principal [email protected]. Instance ldap2 on ldap2.example.com uses the same realm with its own service principal and keytab when you test a second listener.

For every Directory Manager administrative command in this guide, I'll use LDAPS and trust the server CA. Export the CA file before you run dsconf or ldapsearch with a simple bind:

export LDAPTLS_CACERT=/root/example-ca-chain.pem

If the instance still uses the self-signed CA from dscreate, use that CA file instead:

export LDAPTLS_CACERT=/etc/dirsrv/ssca/ca.crt

GSSAPI client tests may remain on ldap:// after you confirm that a SASL security layer was negotiated, as discussed later in this guide.

How SASL GSSAPI authentication works

User obtains Kerberos TGT with kinit
        |
        v
LDAP client requests ldap/ldap1.example.com service ticket
        |
        v
Directory Server reads its LDAP service keytab
        |
        v
GSSAPI validates the Kerberos ticket
        |
        v
SASL map converts [email protected] to an LDAP DN
        |
        v
ACIs authorize the mapped LDAP user

Kerberos proves who the client is. SASL mapping decides which directory entry that principal represents. ACIs decide what that entry may do afterward.

Prepare DNS, hostnames, and time synchronization

Verify forward and reverse DNS, consistent FQDN usage in LDAP URIs, realm configuration in /etc/krb5.conf, and time synchronization between the KDC, Directory Server, and clients. Kerberos service principals depend on the hostname the client uses, and clock skew can prevent ticket validation. Check clock state with timedatectl before you test tickets.

Check name resolution for the LDAP hostname:

getent hosts ldap1.example.com

Sample output:

192.168.56.108  ldap1.example.com ldap1

Confirm that the system clock is synchronized:

timedatectl status

Sample output:

System clock synchronized: yes
              NTP service: active

Install the Kerberos SASL components

On a RHEL-family system, install the Kerberos client tools and the Cyrus SASL GSSAPI plug-in with the dnf command on every host that runs Directory Server or LDAP GSSAPI clients.

dnf install krb5-workstation cyrus-sasl-gssapi

Package names differ on Debian (krb5-user, libsasl2-modules-gssapi-mit) and SUSE (krb5-client, cyrus-sasl-gssapi). Install the equivalent packages on your distribution before you continue.

After you install the server-side SASL plug-in on a running Directory Server host, restart the instance before you test the root DSE:

dsctl ldap1 restart

Distinguish available mechanisms from accepted mechanisms.

List every mechanism the SASL library on this host can advertise:

dsconf ldap1 sasl get-available-mechs

Then list only the mechanisms this Directory Server instance currently accepts on binds:

dsconf ldap1 sasl get-mechs

Confirm that clients see GSSAPI in the root DSE with a base-scope ldapsearch command:

ldapsearch -LLL -x -H ldap://ldap1.example.com:389 -b "" -s base supportedSASLMechanisms

Sample output:

supportedSASLMechanisms: GSSAPI
supportedSASLMechanisms: GSS-SPNEGO

GSSAPI must appear in the root DSE before clients can attempt a Kerberos bind. That output confirms the server advertises the mechanism.

Create the LDAP service principal

I'll create a host-based service principal for the exact LDAP URI hostname:

ldap/[email protected]

On the KDC host, create the principal with MIT Kerberos:

kadmin.local -q "addprinc -randkey ldap/[email protected]"

Sample output:

Principal "ldap/[email protected]" created.

• ldap is the service name clients request.
• The hostname must match the name clients use in ldap://ldap1.example.com.
• The realm is normally uppercase.
• DNS aliases and load balancers may require additional principals in the same keytab.

For the second lab instance on the same host, I'll create a separate principal:

kadmin.local -q "addprinc -randkey ldap/[email protected]"

Create the Directory Server keytab

kadmin.local normally runs on the KDC. When the KDC and Directory Server are separate hosts, the Directory Server instance directory will not exist on the KDC. MIT recommends storing keytabs locally on the application server, restricting access, and never transferring them over an unencrypted channel.

Use one of these supported patterns.

Pattern A: Run remote kadmin on the Directory Server host

Authenticate with an authorized Kerberos administrator and write the keytab directly to its final location on the Directory Server host:

kadmin -p admin/[email protected] -q \
    "ktadd -k /etc/dirsrv/slapd-ldap1/ldap.keytab \
    ldap/[email protected]"

Protect the keytab so only the Directory Server user can read it.

I'll change ownership of the keytab to the dirsrv user and group with the chown command:

chown dirsrv:dirsrv /etc/dirsrv/slapd-ldap1/ldap.keytab

I'll set mode 600 on the keytab so only the owner can read it; see the chmod command for octal modes:

chmod 600 /etc/dirsrv/slapd-ldap1/ldap.keytab

After copying or moving the keytab, I'll restore the SELinux file context with restorecon. Path labels and restorecon are covered in Ansible SELinux file contexts:

restorecon -v /etc/dirsrv/slapd-ldap1/ldap.keytab

Pattern B: Export on the KDC and transfer securely

On the KDC, set a restrictive umask 077 before exporting the keytab so the new file is not group- or world-readable:

umask 077 kadmin.local -q "ktadd -k /root/ldap1.keytab ldap/[email protected]"

I'll copy the exported keytab from the KDC to the Directory Server host with the scp command or rsync command, then install it in the instance path:

install -o dirsrv -g dirsrv -m 600 /root/ldap1.keytab /etc/dirsrv/slapd-ldap1/ldap.keytab

I'll restore the SELinux file context on the installed keytab:

restorecon -v /etc/dirsrv/slapd-ldap1/ldap.keytab

Verify:

ls -lZ /etc/dirsrv/slapd-ldap1/ldap.keytab

Securely remove the temporary KDC and transfer copies after verification.

On the tested Rocky Linux platform, correct UNIX ownership alone does not guarantee that ns-slapd can read a file copied from another location. The restorecon step matters.

When the KDC and Directory Server run on the same host, kadmin.local can write directly to /etc/dirsrv/slapd-ldap1/ldap.keytab as in Pattern A, then apply the same ownership, mode, and SELinux steps.

List the keytab contents without exposing key material:

klist -k -e /etc/dirsrv/slapd-ldap1/ldap.keytab

Sample output:

Keytab name: FILE:/etc/dirsrv/slapd-ldap1/ldap.keytab
KVNO Principal
---- --------------------------------------------------------------------------
   2 ldap/[email protected] (aes256-cts-hmac-sha384-192)
   2 ldap/[email protected] (aes128-cts-hmac-sha256-128)

Use a dedicated Directory Server keytab rather than sharing the host /etc/krb5.keytab.

Repeat for ldap2 with /etc/dirsrv/slapd-ldap2/ldap.keytab and ldap/[email protected] when you test the non-default listener.

Configure Directory Server to use the keytab

RHDS 13 documentation uses /etc/sysconfig/slapd-INSTANCE. Some 389 DS packages instead load /etc/sysconfig/dirsrv-INSTANCE. Check the installed systemd unit and edit the environment file it actually references.

Verification:

systemctl cat dirsrv@ldap1 | grep -i EnvironmentFile

Sample output on the tested Rocky Linux build:

EnvironmentFile=-/etc/sysconfig/dirsrv
EnvironmentFile=-/etc/sysconfig/dirsrv-%i

Create or edit the path returned by that command, then add:

KRB5_KTNAME=/etc/dirsrv/slapd-ldap1/ldap.keytab

Restart the instance:

dsctl ldap1 restart

Optionally confirm that the running process received it:

pid=$(systemctl show --property MainPID --value dirsrv@ldap1)

tr '\0' '\n' < "/proc/$pid/environ" | grep '^KRB5_KTNAME='

Expected output:

KRB5_KTNAME=/etc/dirsrv/slapd-ldap1/ldap.keytab

The running process should show the same KRB5_KTNAME value. The service should start without Kerberos or keytab permission errors in /var/log/dirsrv/slapd-ldap1/errors.

Verify the Kerberos service ticket

I'll obtain a user ticket:

kinit [email protected]

Inspect the credential cache:

klist

Sample output:

Default principal: [email protected]

Valid starting       Expires              Service principal
07/16/2026 09:30:47  07/17/2026 09:30:47  krbtgt/[email protected]

Request the LDAP service ticket:

kvno ldap/[email protected]

Sample output:

ldap/[email protected]: kvno = 2

Run klist again and confirm that the LDAP service ticket is present. That step separates Kerberos service-principal problems from Directory Server identity-mapping problems.

Understand SASL identity mapping

GSSAPI authentication may present:

[email protected]

Directory Server must map that identity to exactly one LDAP DN:

uid=user1,ou=people,dc=example,dc=com

A mapping must return exactly one LDAP entry. Zero or multiple matches cause the SASL bind to fail.

Review the default SASL mappings

List the existing mappings:

dsconf -D "cn=Directory Manager" -y /root/dm.pw ldaps://ldap1.example.com:636 sasl list

Sample output:

Kerberos uid mapping
rfc 2829 dn syntax
rfc 2829 u syntax
uid mapping

Inspect the default Kerberos UID mapping:

dsconf -D "cn=Directory Manager" -y /root/dm.pw ldaps://ldap1.example.com:636 sasl get "Kerberos uid mapping"

Sample output:

dn: cn=Kerberos uid mapping,cn=mapping,cn=sasl,cn=config
cn: Kerberos uid mapping
nsSaslMapBaseDNTemplate: dc=\2,dc=\3
nsSaslMapFilterTemplate: (uid=\1)
nsSaslMapRegexString: \(.*\)@\(.*\)\.\(.*\)

For realm EXAMPLE.COM, the default Kerberos UID mapping derives dc=EXAMPLE,dc=COM from the dotted realm and searches for (uid=user1). In the lab suffix dc=example,dc=com, that already maps [email protected] to uid=user1,ou=people,dc=example,dc=com when the user entry exists.

Test GSSAPI authentication with the default mapping

The main lab path uses the built-in Kerberos UID mapping, so I'll drive the client from a clean ticket cache.

Discard any existing ticket cache so the next test starts from a known state:

kdestroy

Request a fresh TGT for the lab user against the EXAMPLE.COM realm:

kinit [email protected]

Confirm the cache now holds a valid TGT with the expected principal and expiry:

klist

With a ticket in place, check the mapped LDAP identity that Directory Server returns over GSSAPI using ldapwhoami:

ldapwhoami -H ldap://ldap1.example.com:389 -Y GSSAPI

Sample output:

SASL/GSSAPI authentication started
SASL username: [email protected]
SASL SSF: 256
SASL data security layer installed.
dn:uid=user1,ou=people,dc=example,dc=com

A successful ldapwhoami here confirms that GSSAPI and the default Kerberos UID mapping work. It does not prove that a later custom mapping was selected.

I'll search using the Kerberos ticket without an LDAP bind DN or password:

ldapsearch -H ldap://ldap1.example.com:389 -Y GSSAPI -b "dc=example,dc=com" "(uid=user1)" dn cn

Sample output:

dn: uid=user1,ou=people,dc=example,dc=com
cn: User One

The search result lists the user entry. That confirms the Kerberos-mapped identity can read directory data after authentication.

On ldap2, GSSAPI is advertised but authentication fails until the instance has directory data and a matching SASL map for the principals you test. A service ticket alone is not enough when no LDAP entry matches the mapping filter.

Optional: Create a realm-specific SASL mapping

I'll create a custom mapping only when you need one. Common reasons include:

• The LDAP suffix does not correspond to the Kerberos realm.
• Users are stored under a specific subtree.
• The principal format differs from the default user principal.
• The default filter is too broad.
• Multiple realms require different mappings.

Before you rely on priority, I'll enable fallback:

dsconf -D "cn=Directory Manager" \
    -y /root/dm.pw \
    ldaps://ldap1.example.com:636 \
    config replace \
    nsslapd-sasl-mapping-fallback=on

Sample output:

Successfully replaced value(s) for 'nsslapd-sasl-mapping-fallback': 'on'

Priority 1 is highest. Priority 100 is lowest and the default. With fallback enabled, Directory Server checks additional matching mappings when the first match does not resolve to exactly one LDAP identity. The custom map and default Kerberos UID mapping still overlap for [email protected]; verify that the combined mapping set produces exactly one LDAP identity.

Create a realm-specific, anchored user-principal expression with a constrained username character set:

dsconf -D "cn=Directory Manager" -y /root/dm.pw ldaps://ldap1.example.com:636 \
    sasl create --cn "EXAMPLE.COM Kerberos users" \
    --nsSaslMapRegexString '^\([[:alnum:]_.-][[:alnum:]_.-]*\)@EXAMPLE\.COM$' \
    --nsSaslMapBaseDNTemplate "ou=people,dc=example,dc=com" \
    --nsSaslMapFilterTemplate "(uid=\1)" \
    --nsSaslMapPriority 10

Sample output:

Successfully created EXAMPLE.COM Kerberos users

Adapt the character class only when your actual Kerberos usernames require additional characters.

Modern upstream 389 DS documents SASL map, fallback, and priority changes as dynamically applied without a required restart. A restart is harmless as a compatibility step, but is not universally required.

Run dsconf INSTANCE sasl create --help on your installed build before you script mapping creation. Regex escaping and attribute names must match your Directory Server version.

Test the mapping filter manually

Before you debug GSSAPI with a custom map, confirm that the generated LDAP search returns exactly one entry:

ldapsearch -x -H ldaps://ldap1.example.com:636 -D "cn=Directory Manager" -y /root/dm.pw -b "ou=people,dc=example,dc=com" "(uid=user1)" dn

Sample output:

dn: uid=user1,ou=people,dc=example,dc=com

# numEntries: 1

Test additional users to ensure every Kerberos principal maps to one LDAP entry, duplicate uid values do not create ambiguity, and principals from other realms do not match unintentionally.

Add negative tests for the custom regex. None of these should resolve through the user-principal map:

user1@EXAMPLEXCOM
ldap/[email protected]
[email protected]

Test authorization as the mapped user

After authentication succeeds, verify that ACIs still govern the mapped identity. GSSAPI does not grant Directory Manager rights automatically.

Use Get Effective Rights when you need a detailed permission check. Confirm that allowed ldapsearch and ldapmodify operations succeed for the mapped user and that denied operations still fail.

Understand GSSAPI integrity, confidentiality, and SSF

GSSAPI authentication and GSSAPI message protection are related but not identical. A successful GSSAPI bind on plain LDAP does not automatically guarantee that every byte of LDAP traffic is encrypted. Client security properties can permit:

• Authentication without a SASL data-security layer.
• Integrity protection only.
• Integrity and confidentiality.

OpenLDAP supports minssf, maxssf, GSSAPI_SIGN, and GSSAPI_ENCRYPT; its documented defaults do not guarantee that every client requires encryption.

SASL SSF: 256 reports the negotiated security-strength factor. The separate SASL data security layer installed message confirms that a SASL protection layer was installed. Do not assume that every GSSAPI client requests confidentiality merely because authentication succeeded.

Record during testing:

• The selected SASL mechanism
• Whether a security layer was negotiated
• The resulting SASL SSF
• Whether the connection meets any global nsslapd-minssf requirement

For a plain-LDAP test that requires a meaningful security layer:

ldapwhoami -Q -H ldap://ldap1.example.com:389 -Y GSSAPI -O minssf=128

For applications whose SASL protection behavior is uncertain, use STARTTLS or LDAPS as well:

ldapwhoami -Q -ZZ -H ldap://ldap1.example.com:389 -Y GSSAPI

Global minimum-SSF enforcement belongs in require secure LDAP connections.

Configure SASL mapping fallback and priorities

By default, Directory Server applies the first matching SASL mapping. If that mapping fails to produce an entry, later mappings are not normally tried unless fallback is enabled.

Enable fallback only when multiple valid mapping formats are required:

dsconf -D "cn=Directory Manager" -y /root/dm.pw ldaps://ldap1.example.com:636 config replace  nsslapd-sasl-mapping-fallback=on

Assign priorities so realm-specific mappings run before broad generic mappings. Priority values range from 1, the highest priority, to 100, the lowest. Priority is meaningful only when fallback is enabled. Even with fallback enabled, the final result must still resolve to exactly one LDAP identity.

Support DNS aliases and load balancers

Clients generally request ldap/FQDN@REALM for the LDAP service hostname, but SASL and Kerberos client canonicalization can change the hostname used in the service principal.

Client connects to:
ldap.example.com

Required principal:
ldap/[email protected]

When clients can connect through both a load balancer and directly to a server, include every required principal in the keytab.

Test each supported name by requesting a service ticket for the principal clients will use:

kvno ldap/[email protected]

Repeat the check for the direct backend hostname when clients can bypass the load balancer:

kvno ldap/[email protected]

Red Hat documents that GSSAPI behind a load balancer requires a service principal for the load-balancer DNS name, and direct server access requires additional host-specific principals. See the RHDS 13 install guide for full_machine_name and strict_host_checking when the instance was created behind a load balancer.

Generate the load-balancer service key once and distribute the same protected keytab material to every backend that must accept ldap/loadbalancer.example.com@REALM. Do not independently run normal ktadd for the same principal on each backend, because each run randomizes the principal keys and increases the KVNO, invalidating earlier keytabs.

When extracting an already-created principal with kadmin.local:

kadmin.local -q "ktadd -norandkey -k /root/loadbalancer-ldap.keytab ldap/[email protected]"

-norandkey is available only in kadmin.local, not remote kadmin.

Compare the service-ticket KVNO with the keytab entry the instance will read:

kvno ldap/[email protected]

List the principals and KVNOs stored in the instance keytab:

klist -k /etc/dirsrv/slapd-ldap1/ldap.keytab

The active ticket KVNO must be represented in the keytab on every backend.

Confirm the actual service principal with a trace when diagnosing an alias or load-balancer name:

KRB5_TRACE=/dev/stderr ldapwhoami -N -Q -H ldap://ldap1.example.com:389 -Y GSSAPI

Then confirm which principal landed in the credential cache:

klist

Confirm that the cache contains:

ldap/[email protected]

OpenLDAP's -N option disables reverse-DNS SASL host canonicalization. SASL_NOCANON yes provides the corresponding client configuration.

Review logs

Inspect Directory Server logs:

/var/log/dirsrv/slapd-ldap1/errors
/var/log/dirsrv/slapd-ldap1/access

Kerberos log destinations depend on the [logging] section of krb5.conf and can use files, syslog, or the journal:

grep -A10 '^\[logging\]' /etc/krb5.conf

Common KDC-side files include /var/log/krb5kdc.log and /var/log/kadmind.log, but Red Hat explicitly notes that their configured locations can differ. /var/log/krb5libs.log is associated with older RHEL configurations and may not exist on Rocky Linux 10.

Also check service journals with journalctl. Start with the KDC unit:

journalctl -u krb5kdc

Then review the kadmin service if principal administration errors are suspected:

journalctl -u kadmin

For client and library diagnostics:

KRB5_TRACE=/dev/stderr ldapwhoami -N -Q -H ldap://ldap1.example.com:389 -Y GSSAPI

Look for:

• GSSAPI mechanism initialization
• Keytab loading errors
• Unknown service principal
• Ticket validation failure
• SASL mapping filter details
• No matching LDAP entry
• Multiple matching entries
• ACI denial after successful authentication

Troubleshoot SASL GSSAPI authentication

Roll back safely

Before changing mappings, record the existing entries and fallback value.

List every SASL mapping Directory Server currently uses:

dsconf -D "cn=Directory Manager" -y /root/dm.pw ldaps://ldap1.example.com:636 sasl list

Capture whether fallback to the next matching map is enabled:

dsconf -D "cn=Directory Manager" \
    -y /root/dm.pw \
    ldaps://ldap1.example.com:636 \
    config get |
    grep -i nsslapd-sasl-mapping-fallback

Delete only the custom mapping:

echo 'Yes I am sure' | dsconf -D "cn=Directory Manager" \
    -y /root/dm.pw \
    ldaps://ldap1.example.com:636 \
    sasl delete \
    "EXAMPLE.COM Kerberos users"

Expected output:

Successfully deleted EXAMPLE.COM Kerberos users

Restore fallback when it was originally disabled:

dsconf -D "cn=Directory Manager" \
    -y /root/dm.pw \
    ldaps://ldap1.example.com:636 \
    config replace \
    nsslapd-sasl-mapping-fallback=off

Retest GSSAPI and password authentication. Do not delete default SASL mappings merely because you are testing a custom mapping.

For complete GSSAPI removal:

1. Confirm no clients or replication agreements use GSSAPI.
2. Remove KRB5_KTNAME from the loaded instance environment file.
3. Restart the instance.
4. Confirm GSSAPI clients are no longer expected.
5. Securely remove or archive the keytab according to your key-management policy.

What's Next

• Certificate management — service certificates alongside the keytab
• Client certificate authentication — certificate binds for non-Kerberos clients
• FIPS mode — verify GSSAPI compatibility on restricted hosts

References

• 389 Directory Server — How to use Kerberos with 389 Directory Server
• 389 Directory Server — SASL Mapping Fallback and Prioritization Design
• OpenLDAP — ldapsearch and ldap.conf
• MIT Kerberos — kadmin
• Red Hat Directory Server 13 — Securing Red Hat Directory Server
• Red Hat Directory Server 13 — Installing with Kerberos authentication behind a load balancer
• Red Hat Directory Server 13 — Configuration and schema reference
• MIT Kerberos — Administering keytabs

Summary

1. Verify DNS, Kerberos configuration, and time synchronization.
2. Create ldap/FQDN@REALM for every LDAP hostname clients use.
3. Install the principal in a protected instance keytab and set KRB5_KTNAME.
4. Test the built-in Kerberos UID mapping before you add overlapping custom maps.
5. Use LDAPS for Directory Manager administrative commands.
6. Verify with kinit, kvno, ldapwhoami, and ldapsearch -Y GSSAPI.
7. Confirm normal ACI authorization for the mapped user.
8. Add alias or load-balancer principals where required, and distribute one keytab for shared load-balancer principals.