Skip to content

Instantly share code, notes, and snippets.

@aaugustin

aaugustin/kerberos.md

Last active April 10, 2023 01:06
Show Gist options
  • Save aaugustin/10715655 to your computer and use it in GitHub Desktop.
Save aaugustin/10715655 to your computer and use it in GitHub Desktop.
Download ZIP
Kerberos
Raw
kerberos.md

Kerberos setup

This guide explains how to set up Kerberos authentication for:

  • SSH access to a server,
  • HTTP access to a service.

It assumes you're running Active Directory and Debian servers.

All instructions will use the following placeholders:

  • COMPANY.COM: Windows domain
  • company.com: network domain
  • server and server.company.com: DNS of the server
  • server: username of the account for the server
  • http://service/ and http://service.company.com/: URLs of the service
  • service: username of the account for the service

Client OS setup

Windows

No setup required, provided the computer is in the Windows domain.

Kerberos doesn't work on Windows computers that aren't in a domain.

OS X

The most user-friendly solution relies on the Ticket Viewer application:

  • Open the Keychain Access application. It's located in Applications > Utilities.
  • In the Keychain Access menu, select Ticket Viewer.
  • Add an identity: [email protected] / your password.
  • Set this identity as default.
  • When your ticket expires, click ↻ to obtain a new one.
  • Most likely, you want to keep Ticket Viewer in the dock.

The geeky way involves the Terminal:

If you're using MacPorts or a similar package manager, make sure you invoke the system binaries /usr/bin/kinit and /usr/bin/klist. MacPorts' binaries in /opt/local/bin/kinit and /opt/local/bin/klist don't share the system ticket cache.

Linux

  • Install Kerberos utilities e.g. sudo apt-get install krb5-user on Debian.
  • When you're prompted for the Kerberos realm, enter COMPANY.COM.
  • Run kinit firstname.lastname and enter your password.
  • (Optional) Check that you have a valid ticket with klist
  • (Recommended) Run a ticket renewal task eg. watch -n 3600 "kinit -R"

Client browser setup

The following instructions should give access to any properly configured internal website with or without specifying the domain name. On some less common OS - browser combinations, you may need to use the fully qualified domain name.

Firefox

This setup is required on any operating system.

  • Enter about:config in the address bar.
  • Read the warning and acknowledge it.
  • Enter negotiate in the search field.
  • Set network.negotiate-auth.allow-non-fqdn to true.
  • Set network.negotiate-auth.trusted-uris to .company.com
  • If you intend to use service a that relies on Kerberos delegation to authenticate to other networks services on your behalf (you probably don't!), set network.negotiate-auth.delegation-uris to .company.com.

Internet Explorer

No setup is required.

Chrome

No setup is required on Windows.

On OS X or Linux, start Chrome with the following command-line options:

  • --auth-server-whitelist=.company.com
  • If you need delegation: --auth-negotiate-delegate-whitelist=.company.com

You may also achieve this by configuring a policy.

Safari

No setup is required.

Client SSH setup

Linux

Add the following lines to ~/.ssh/config:

Host *.company.com
GSSAPIAuthentication yes
GSSAPIDelegateCredentials yes

The first line allows Kerberos authentication to servers on the corporate network. The last line enables forwarding the authentication. That works like agent forwarding. It's optional.

OS X

The setup is identical to Linux.

If you're using MacPorts or a similar package manager, you must either use /usr/bin/ssh or acquire a Kerberos ticket with /opt/local/bin/kinit.

Server OS setup

You need an admininstrative Active Directory user account. All commands must be executed as root on the server.

Install Kerberos utilities with apt-get install krb5-user. When you're prompted for the Kerberos realm, enter COMPANY.COM.

Install msktutil. If you're running jessie (testing at the time of writing), all you need is apt-get install msktutil. If you're running wheezy (stable at the time of writing), you have to download a release, fix a broken dependency declaration (click "view source" before copy-pasting the script), install the package with dpkg -i msktutil.*.deb and add its dependencies with apt-get -f install.

man msktutil is a good resource, you should read it at this point. Depending on your requirements, you may be able to perform the next steps with fewer commands.

Server SSH setup

Check your DNS setup. Your server's FQDN server.company.com must resolve to its IP (A record) and vice-versa (PTR record).

Run kinit <your username> and enter your password. This confirms that Kerberos works and authenticates you for the next step.

Run msktutil --create --verbose (shorter version: msktutil -c). This is going to create a computer account in Active Directory for the server and generate a keytab in /etc/krb5.keytab. Running in verbose mode tells you exactly what msktutil does.

Edit /etc/default/msktutil and set AUTOUPDATE_ENABLED="true". This enables daily execution of msktutil --auto-update, which prevents the account from expiring as long as the server is alive and updates the keytab when necessary.

Edit /etc/ssh/sshd_config and enable the following options:

KerberosAuthentication yes
GSSAPIAuthentication yes
GSSAPICleanupCredentials yes

Restart the SSH daemon with service ssh restart.

At this point, assuming your workstation is set up properly (see above), you have a user account on the server, and you're always using the same username, you should be able to log in to the server simply with ssh server.

Server HTTP setup

Apache provides off-the-shelf support for Kerberos.

(If you're using nginx, look at spnego-http-auth-nginx-module.)

Check your DNS setup. Your server's FQDN server.company.com must resolve to its IP (A record) and vice-versa (PTR record). If you're using a different name for the service, service.company.com must be a CNAME pointing to server.company.com.

Install the Kerberos module. When prompted, set the Kerberos domain to COMPANY.COM.

# apt-get install libapache2-mod-auth-kerb

If you're using a different name for the service, run:

# msktutil --update --verbose                                       \
           --computer-name service --hostname service.company.com   \
           --keytab /etc/apache2/service.company.com.keytab         \
           --service HTTP/server.company.com                        \
           --service HTTP/service.company.com                       \
           --service HTTP/service

If you're using the server name to access the service, run

# msktutil --update --verbose --computer-name service               \
           --keytab /etc/apache2/service.company.com.keytab         \
           --service HTTP

This is going to create a computer account in Active Directory for the service and generate a keytab in /etc/apache2/service.company.com.keytab. Running in verbose mode tells you exactly what msktutil does.

Make the keytab file readable by Apache:

# chown root:www-data /etc/apache2/service.company.com.keytab
# chmod 640 /etc/apache2/service.company.com.keytab

In the relevant virtual host configuration, add:

<Location />
    AuthName "use your corporate login to access this service"
    AuthType Kerberos
    KrbServiceName HTTP/[email protected]
    Krb5KeyTab /etc/apache2/service.company.com.keytab
    KrbMethodK5Passwd Off
    KrbLocalUserMapping On
    Require valid-user
</Location>

For reference, here's a version including the defaults we're relying upon:

<Location />
    AuthName "use your corporate login to access this service"
    AuthType Kerberos

    # KrbAuthRealms COMPANY.COM
    # KrbSaveCredentials Off
    # KrbVerifyKDC On
    KrbServiceName HTTP/[email protected]
    # KrbAuthoritative On
    # KrbDelegateBasic Off

    Krb5KeyTab /etc/apache2/service.company.com.keytab
    # KrbMethodNegotiate On
    KrbMethodK5Passwd Off
    KrbLocalUserMapping On

    Require valid-user
</Location>

Remove KrbMethodK5Passwd Off if you want the browser to ask for user credentials when SSO fails. This helps users who are running Windows but aren't in the domain. Warning: the user credentials will be sent in clear! Do this only on secure networks or HTTPS-only websites!

Remove KrbLocalUserMapping On if you want usernames in the form [email protected] rather than just firstname.lastname.

Finally restart Apache.

# service apache2 restart

At this point, assuming your workstation is set up properly (see above) and the application supports remote authentication, you should be automatically logged in.

Resources

SSH

Apache

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment