Vault Kerberos Authentication Demo

Caveat

While this repository was developed by an employee of HashiCorp, Inc. during the course of their work, it is not an official product of HashiCorp, nor is it officially supported.

Background

This repository contains a Vagrant setup to demonstrate the Vault Kerberos Authentication Method introduced in Vault 1.4.

It contains three VMs:

1. A Kerberos Key Distribution Center (KDC)
2. An OpenLDAP server (LDAP is required for directory information by the auth plugin)
3. A Vault server

On startup, everything is running, and your Vault server is initialized and unsealed. There's a vagrant user with appropriate credentials and LDAP directory entry already.

Running the demo

1. vagrant up - this takes about five minutes on my laptop
2. vagrant ssh vault - you run the demo here
3. ./run-demo - prints out and then runs the commands necessary to:
   1. Mount the auth method
   2. View the Vault server's keytab (pre-provisioned)
   3. Encode it
   4. Configure the Kerberos authentication method
   5. Configure the LDAP settings in the Kerberos authentication method
   6. Map the LDAP group dev to the dev policy in Vault
   7. View the vagrant user's credentials
   8. Authenticate

Bonus demo

The vault login command only supports authenticating via a keytab, which is usual for services and machines, but is a bit unusual for users, who would typically authenticate to Kerberos using a passphrase and then have cached credentials. The method above simply gives the vagrant user a keytab to make the demo work.

This is, at first glance, a limitation of the Golang Kerberos libraries - how one accesses the credentials cache is highly dependent on your implemenation of Kerberos (MIT, Heimdal, Active Directory), and the format is not standardized. Most programming languages for which there are Kerberos libraries handle this by simply linking against the Kerberos distribution's libraries, but the Golang one is pure Go.

However, the Vault Kerberos authentication mechanism is simply passing a Authorization: Negotiate header obtained by SPNEGO, so if you've got the pile of Kerberos/GSSAPI/SPNEGO goo in your programming language, and it can access the user's credentials cache, you can authenticate as a typical Kerberos user would expect. This demo contains examplar Python code to do so from the Vault Kerberos Authentication Plugin repository.

Running the bonus demo

1. Make sure you're still connected to the vault VM
2. See that the vagrant user has no cached credentials
3. Authenticate as the vagrant user with the (pre-provisioned) user keytab
4. View the now cached credentials
5. Look at the Python code
6. Run the code and use jq to pretty-print the returned Vault output
7. The returned json is stashed in cat /home/vagrant/.ccache-auth.out so you can look at it later

Environment

When you vagrant up, several things are provisioned for you. All of the stashed credentials mentioned below are in the vagrant user's home directory on the vault VM.

1. A KDC for the realm EXAMPLE.LOCAL - MIT Kerberos in this example
2. A Kerberos administrative user admin/[email protected] with the password stashed in .admin.admin.pwd
3. A vagrant user in Kerberos, with vagrant.keytab as their keytab
4. A vault/vault.example.local user in Kerberos, with vault/keytab as its keytab
5. An OpenLDAP server with a DN of dc=example,dc=local
6. A vagrant and a vault user in LDAP, with corresponding LDAP passwords in vagrant.ldap.password and vault.ldap.password (this demo uses simple bind and does not do SASL)
7. An unsealed Vault with the unseal key in .vault.unseal_key and the Vault root user token in .vault.root_token
8. The environment variables VAULT_ADDR, VAULT_UNSEAL_KEY set with what you'd expect them to be. VAULT_ROOT_TOKEN is set to the Vault root token; when you first login VAULT_TOKEN is set to the same value, but this allows you to easily switch back and forth between Vault tokens

LDAP Weirdness

There's an outstanding feature request in the Vault Kerberos authentication plugin - hashicorp/vault-plugin-auth-kerberos/#44

• to resolve an issue where the plugin mandates a setting that essentially forces it into thinking you are using Active Directory as your LDAP server, and that you have an attribute userPrincipalName set to the user's Kerberos principal name. That's not the case unless you're using Active Directory or Samba. To get around that, this demo fakes such an entry in the user entries.

Useful commands

1. ldapsearch -x -b ou=Users,dc=example,dc=local uid=vagrant - Examine the vagrant user LDAP entry
2. ldapsearch -x -b ou=Groups,dc=example,dc=local cn=devs - Examine the devs group LDAP entry
3. kadmin -p admin/admin -w $(cat ~/.admin.admin.pwd) - Connect to the Kerberos administrative server
   1. getprinc vagrant - examine the vagrant user's entry in the KDC
   2. getprinc vault/vault.example.local - do the same for the vault user

References

1. Vault Kerberos Auth Plugin Documentation
2. The Wikipedia entry for Kerberos
3. RFC 4120: The Kerberos Network Authentication Service(v5)
4. Designing an Authentication System: a Dialogue in Four Scenes - still one of the best ways of understanding the design of Kerberos