When using GSSAPI/Kerberos authentication with SSH, you might encounter errors like:

bash
$ ssh user@server.example.com
debug1: Offering GSSAPI proposal: gssapi-with-mic.krb5
debug1: SSH2_MSG_KEXINIT sent
debug1: GSSAPI authentication failed

Or in server logs:

bash
sshd[12345]: gssapi error: Miscellaneous failure (see text)
sshd[12345]: GSSAPI authentication failed for user: Permission denied

GSSAPI (Generic Security Services Application Programming Interface) enables Kerberos single sign-on authentication. Let's diagnose and fix these errors.

Understand GSSAPI SSH Authentication

  1. 1.GSSAPI SSH authentication:
  2. 2.Client obtains Kerberos ticket from KDC
  3. 3.Client offers GSSAPI authentication to SSH server
  4. 4.Server validates ticket against its own Kerberos principal
  5. 5.If valid, authentication succeeds without password

Requirements: - Kerberos infrastructure (KDC) - Service principal for SSH server (host/server.example.com) - Client has valid Kerberos ticket - Both sides configured for GSSAPI

Check Client Kerberos Ticket

First, verify you have a valid ticket:

bash
klist

Output should show:

``` Ticket cache: FILE:/tmp/krb5cc_1000 Default principal: user@EXAMPLE.COM

Valid starting Expires Service principal 04/03/26 10:00:00 04/03/26 20:00:00 krbtgt/EXAMPLE.COM@EXAMPLE.COM ```

If no ticket or expired:

bash
kinit user@EXAMPLE.COM

Enter your Kerberos password. Then verify:

bash
klist

Check SSH Client GSSAPI Configuration

In ~/.ssh/config or /etc/ssh/ssh_config:

bash
grep -i gssapi ~/.ssh/config

Enable GSSAPI:

bash
Host *.example.com
    GSSAPIAuthentication yes
    GSSAPIDelegateCredentials yes

The GSSAPIDelegateCredentials yes forwards your ticket to the server.

Check Server GSSAPI Configuration

On the server, check SSHD config:

bash
sudo grep -i gssapi /etc/ssh/sshd_config

Should show:

bash
GSSAPIAuthentication yes
GSSAPICleanupCredentials yes

If missing or disabled:

bash
sudo sed -i 's/^GSSAPIAuthentication.*/GSSAPIAuthentication yes/' /etc/ssh/sshd_config
echo "GSSAPICleanupCredentials yes" | sudo tee -a /etc/ssh/sshd_config
sudo systemctl restart sshd

Verify Server Service Principal

The SSH server needs a Kerberos service principal. Check:

bash
# On KDC or using admin tools
klist -k /etc/krb5.keytab

Should show:

bash
Keytab name: FILE:/etc/krb5.keytab
KVNO Principal
---- ----------
   1 host/server.example.com@EXAMPLE.COM

If the principal doesn't exist, create it:

bash
# On KDC
kadmin.local -q "addprinc -randkey host/server.example.com@EXAMPLE.COM"
kadmin.local -q "ktadd host/server.example.com@EXAMPLE.COM"

Then copy the keytab to the server:

bash
scp keytab server:/etc/krb5.keytab

Fix Keytab Permissions

On the server:

bash
ls -la /etc/krb5.keytab

Should be readable by sshd:

bash
sudo chown root:root /etc/krb5.keytab
sudo chmod 600 /etc/krb5.keytab

Some systems need sshd to read the keytab:

bash
sudo chown root:sshd /etc/krb5.keytab
sudo chmod 640 /etc/krb5.keytab

Check Kerberos Configuration

Both client and server need proper /etc/krb5.conf:

bash
cat /etc/krb5.conf

Should include:

``` [libdefaults] default_realm = EXAMPLE.COM dns_lookup_kdc = true

[realms] EXAMPLE.COM = { kdc = kdc.example.com admin_server = kdc.example.com }

[domain_realm] .example.com = EXAMPLE.COM example.com = EXAMPLE.COM ```

Test GSSAPI Authentication

Run SSH with verbose output:

bash
ssh -vvv user@server.example.com 2>&1 | grep -i gssapi

Look for:

bash
debug1: Offering GSSAPI proposal: gssapi-with-mic.krb5
debug1: Trying GSSAPI authentication...
debug1: GSSAPI authentication request successful

If it shows "failed", check the reason.

Common GSSAPI Errors

"No keytab entry found"

The server lacks the service principal keytab:

bash
# Solution: Add principal and create keytab
kadmin -q "addprinc -randkey host/server.example.com"
kadmin -q "ktadd host/server.example.com"

"Ticket expired"

Your Kerberos ticket expired:

bash
kinit user@EXAMPLE.COM

"Server not found in Kerberos database"

Hostname mismatch. The principal must match the server's hostname:

```bash # Check actual hostname hostname -f

# Principal must be host/actual.hostname@REALM ```

If server's hostname is different:

bash
kadmin -q "addprinc -randkey host/actual.hostname.example.com@EXAMPLE.COM"

"Clock skew too great"

Kerberos requires synchronized clocks:

```bash # Check time difference date ssh server 'date'

# Sync clocks sudo systemctl restart ntp ```

Or manually sync:

bash
sudo date -s "$(ssh kdc 'date')"

Check Credential Cache

SSH needs to find your credential cache:

bash
echo $KRB5CCNAME

Should show a path like:

bash
FILE:/tmp/krb5cc_1000

If unset but you have a ticket:

bash
export KRB5CCNAME=FILE:/tmp/krb5cc_$(id -u)

Enable GSSAPI Key Exchange

For single sign-on during key exchange:

bash
sudo grep GSSAPIKeyExchange /etc/ssh/sshd_config

Enable it:

bash
echo "GSSAPIKeyExchange yes" | sudo tee -a /etc/ssh/sshd_config
sudo systemctl restart sshd

Client side:

bash
Host *.example.com
    GSSAPIKeyExchange yes

Check Server Principal Mapping

Some configurations need principal-to-user mapping:

bash
sudo grep -i authfile /etc/ssh/sshd_config

Or check AuthorizedPrincipalsFile:

bash
AuthorizedPrincipalsFile /etc/ssh/auth_principals/%u

Create principals file:

bash
echo "user@EXAMPLE.COM" | sudo tee /etc/ssh/auth_principals/user

Use Kerberos Username Mapping

If your Kerberos principal differs from local username:

bash
sudo grep -i krb5 /etc/sssd/sssd.conf

Configure mapping:

bash
[domain/example.com]
    krb5_validate = true
    ldap_krb5_init_kdc = true

Or use .k5login:

bash
echo "kerberos_principal@EXAMPLE.COM" > ~/.k5login

Troubleshoot with Kerberos Logs

Check KDC logs:

bash
# On KDC
sudo tail -f /var/log/krb5kdc.log

Look for authentication attempts and failures.

Check SSH server logs:

bash
sudo journalctl -u sshd -f

Test Raw Kerberos

Test Kerberos independently of SSH:

bash
kinit user@EXAMPLE.COM
kvno host/server.example.com@EXAMPLE.COM

If kvno fails, the service principal is missing or misconfigured.

Resolution Checklist

  1. 1.Verify Kerberos ticket: klist
  2. 2.Obtain fresh ticket: kinit
  3. 3.Enable GSSAPI in SSH client config
  4. 4.Enable GSSAPI in SSHD config
  5. 5.Verify server has service principal: klist -k /etc/krb5.keytab
  6. 6.Fix keytab permissions
  7. 7.Check /etc/krb5.conf configuration
  8. 8.Synchronize clocks
  9. 9.Set KRB5CCNAME environment variable
  10. 10.Test with verbose SSH: ssh -vvv

GSSAPI authentication errors are typically Kerberos infrastructure issues. Start by verifying your ticket, then check the server's service principal and keytab configuration.