netatalk.io

Kerberos

Enabling SSO with Kerberos

Netatalk Kerberos on Linux

This section describes how to configure a Linux Netatalk server for AFP single sign-on with Kerberos. The examples use Active Directory as the Kerberos realm, but the same Netatalk configuration applies to any Kerberos KDC as long as the server has a matching service principal in a readable keytab.

The examples below use:

• Kerberos realm: EXAMPLE.COM
• AD DNS domain: example.com
• Netatalk server FQDN: fileserver.example.com
• Kerberos service name: afpserver
• Service principal: afpserver/[email protected]
• Keytab path: /etc/krb5.keytab or /etc/netatalk/afp.keytab

Replace these values with your own realm, domain, and server name.

Prerequisites

Before configuring Netatalk, make sure the Linux host has:

• A stable fully qualified DNS name.
• Forward and reverse DNS that resolve correctly.
• Working time synchronization with the domain or KDC.
• Netatalk built with Kerberos V / GSSAPI support, so uams_gss.so is installed.
• Local or NSS-resolved Unix users that match the Kerberos login names.

The last point is important: after Kerberos authentication succeeds, Netatalk still needs to map the authenticated principal to a Unix account. For example, [email protected] must resolve to a usable local or directory-backed Unix user such as alice.

If you use SSSD with Active Directory, many installations need this in /etc/sssd/sssd.conf:

[domain/example.com]
use_fully_qualified_names = False
fallback_homedir = /home/%u

Then restart SSSD:

sudo systemctl restart sssd
getent passwd alice

Join the Linux Server to Active Directory

One common Linux setup uses realmd, adcli, and SSSD.

On Debian or Ubuntu:

sudo apt install realmd adcli sssd sssd-tools krb5-user samba-common-bin

On Fedora, RHEL, or compatible systems:

sudo dnf install realmd adcli sssd sssd-tools krb5-workstation samba-common-tools

Discover and join the domain:

realm discover EXAMPLE.COM
sudo realm join -U Administrator EXAMPLE.COM
realm list

Verify that Kerberos and NSS resolution work:

kinit [email protected]
klist
getent passwd alice

Create the AFP Service Principal and Keytab

Netatalk’s Kerberos UAM needs a service principal in a keytab. The service name must match the k5 service option in afp.conf, and the hostname must match the fqdn option.

Option 1: Use adcli

On a domain-joined Linux server, adcli can add an additional service principal to the computer account and update the host keytab:

sudo adcli update \
  --domain=EXAMPLE.COM \
  --login-user=Administrator \
  --service-name=afpserver

Check that the principal was added:

sudo klist -k /etc/krb5.keytab | grep afpserver

You should see an entry similar to:

afpserver/[email protected]

Option 2: Use Samba net ads

If the host is joined to AD with Samba tooling, you can add the service principal to the system keytab with:

sudo net ads keytab add afpserver -U Administrator
sudo klist -k /etc/krb5.keytab | grep afpserver

Option 3: Use a Dedicated Netatalk Keytab

You may prefer to keep Netatalk’s key in its own file:

sudo mkdir -p /etc/netatalk
sudo cp /etc/krb5.keytab /etc/netatalk/afp.keytab
sudo chown root:root /etc/netatalk/afp.keytab
sudo chmod 600 /etc/netatalk/afp.keytab

If you use a dedicated file, make sure it contains the AFP service principal:

sudo klist -k /etc/netatalk/afp.keytab | grep afpserver

Test the Keytab

Before starting Netatalk, verify that the service principal can acquire a ticket from the keytab:

sudo kinit -k \
  -t /etc/krb5.keytab \
  afpserver/[email protected]
sudo klist
sudo kdestroy

If you use /etc/netatalk/afp.keytab, substitute that path in the command.

Also verify that a user can obtain a service ticket for the AFP server:

kinit [email protected]
kvno afpserver/[email protected]
klist

Configure Netatalk

Edit afp.conf and enable the Kerberos UAM:

[Global]
fqdn = fileserver.example.com
k5 keytab = /etc/krb5.keytab
k5 service = afpserver
k5 realm = EXAMPLE.COM
uam list = uams_dhx2.so uams_gss.so

[Homes]
basedir regex = /home

If you use a dedicated keytab, set:

k5 keytab = /etc/netatalk/afp.keytab

The fqdn, k5 service, and k5 realm options make Netatalk look for this exact principal in the keytab:

afpserver/[email protected]

If these options are omitted, Netatalk may fall back to the first entry in the keytab. That can work, but an explicit configuration is easier to audit and troubleshoot.

Restart Netatalk after changing the configuration:

sudo systemctl restart netatalk

Check the logs for the service principal that Netatalk selected:

journalctl -u netatalk -b

You should see a log line similar to:

Using AFP Kerberos service principal name: afpserver/[email protected]

Connect from a Mac

The Mac must have a Kerberos ticket in the same realm. In an AD environment this usually means the Mac is bound to the domain or otherwise configured to obtain Kerberos tickets.

On the Mac, verify the user ticket:

klist

Then connect to Netatalk using the same DNS name as the service principal:

afp://fileserver.example.com

Using an IP address or a different DNS alias can cause Kerberos to request a different service principal, which will not match the keytab.

Troubleshooting

Netatalk does not advertise Kerberos

Check that uams_gss.so is installed and listed in uam list:

uam list = uams_dhx2.so uams_gss.so

If Netatalk was built without Kerberos support, the GSS UAM will not be available.

Netatalk cannot find the principal in the keytab

List the keytab:

sudo klist -k /etc/krb5.keytab

Make sure the keytab contains exactly the principal implied by afp.conf:

k5 service/fqdn@k5 realm

For example:

afpserver/[email protected]

Kerberos works, but login still fails

Make sure the Kerberos user maps to a Unix account:

getent passwd alice

Netatalk strips the realm from the Kerberos principal and then checks the local user account. If AD users appear as [email protected], adjust the NSS/SSSD configuration or create matching local users.

The Mac asks for a password instead of using SSO

Check these common causes:

• The Mac has no Kerberos ticket: run klist on the Mac.
• The Mac connected with an alias or IP address instead of the FQDN.
• DNS forward or reverse lookup is wrong.
• The Linux server and KDC clocks differ by more than the Kerberos skew limit.
• The service principal in AD does not match the Netatalk fqdn and k5 service values.

Increase Kerberos UAM logging

For temporary troubleshooting, raise Netatalk logging:

[Global]
log level = default:info,uams:debug,afpd:debug

Restart Netatalk, reproduce the login, and inspect the logs:

sudo systemctl restart netatalk
journalctl -u netatalk -b

SSO with Active Directory on Windows

Below are the basic steps needed for SSO with Active Directory.

Using ktpass on Windows

First you must generate a Kerberos service principal for the Netatalk AFP server in AD. This is done with the CLI tool “ktpass” on Windows. The basic syntax is:

ktpass -princ afpserver/fqdn@REALM -mapuser mapuser@domain +rndPass -out afpserver.keytab

• fqdn: fqdn of your Netatalk server
• REALM: Kerberos realm name of AD domain
• mapuser@domain: name of new user who’s password is set to never expire

Full example:

ktpass -princ afpserver/[email protected] -mapuser [email protected] +rndPass -out afpserver.keytab

Configure Netatalk

• Copy the keytab to your Netatalk server and set the afp.conf ‘k5 keytab’ option to the path where you stored it.
• Enable the GSS UAM (add uams_gss.so to ‘uam list’ in afp.conf – must be compiled of course)

Example:

[Global]
...
k5 keytab = /etc/krb5/afp.keytab
uam list = uams_dhx2.so uams_guest.so uams_gss.so

Footnotes

Generated from the Netatalk GitHub Wiki

Last updated 2026-07-18