0a6e7ab94b
* mod: update plugin versions for 1.7.0 * command/agent: fix TestCFEndToEnd test |
||
---|---|---|
.. | ||
.gitignore | ||
backend.go | ||
cli.go | ||
go.mod | ||
go.sum | ||
LICENSE | ||
Makefile | ||
path_config.go | ||
path_config_ldap.go | ||
path_groups.go | ||
path_login.go | ||
README.md |
Vault Plugin: Kerberos Auth Backend
This Plugin is in Beta
This plugin is currently being incorporated into Vault and documentation is in the process of being written. Beta usage is welcome. Please report any issues you encounter. Thank you!
Details
This is a standalone backend plugin for use with Hashicorp Vault. This plugin allows for users to authenticate with Vault via Kerberos/SPNEGO.
Usage
Authentication
You can authenticate by posting a valid SPNEGO Negotiate header to /v1/auth/kerberos/login
.
try:
import kerberos
except:
import winkerberos as kerberos
import requests
service = "HTTP@vault.domain"
rc, vc = kerberos.authGSSClientInit(service=service, mech_oid=kerberos.GSS_MECH_OID_SPNEGO)
kerberos.authGSSClientStep(vc, "")
kerberos_token = kerberos.authGSSClientResponse(vc)
r = requests.post("https://vault.domain:8200/v1/auth/kerberos/login",
headers={'authorization': 'Negotiate ' + kerberos_token})
print('Vault token:', r.json()['auth']['client_token'])
Configuration
- Install and register the plugin.
Put the plugin binary (vault-plugin-auth-kerberos
) into a location of your choice. This directory
will be specified as the plugin_directory
in the Vault config used to start the server.
...
plugin_directory = "path/to/plugin/directory"
...
$ vault write sys/plugins/catalog/auth/kerberos sha_256="$(shasum -a 256 'vault-plugin-auth-kerberos' | cut -d ' ' -f1)" command="vault-plugin-auth-kerberos -client-cert server.crt -client-key server.key"
- Enable the Kerberos auth method:
$ vault auth enable -passthrough-request-headers=Authorization -allowed-response-headers=www-authenticate kerberos
Success! Enabled kerberos auth method at: kerberos/
- Use the /config endpoint to configure Kerberos.
Create a keytab for the kerberos plugin:
$ ktutil
ktutil: addent -password -p your_service_account@REALM.COM -e aes256-cts -k 1
Password for your_service_account@REALM.COM:
ktutil: list -e
slot KVNO Principal
---- ---- ---------------------------------------------------------------------
1 1 your_service_account@REALM.COM (aes256-cts-hmac-sha1-96)
ktutil: wkt vault.keytab
The KVNO (-k 1
) should match the KVNO of the service account. An error will show in the vault logs if this is incorrect.
Different encryption types can also be added to the keytab, for example -e rc4-hmac
with additional addent
commands.
Then base64 encode it:
base64 vault.keytab > vault.keytab.base64
vault write auth/kerberos/config keytab=@vault.keytab.base64 service_account="your_service_account"
- Add a SPNs (Service Principal Names) to your KDC for your service and service account. This should map the vault service to the account it is running as:
# for Windows/Active Directory
setspn.exe -U -S HTTP/vault.domain:8200 your_service_account
setspn.exe -U -S HTTP/vault.domain your_service_account
- Configure LDAP backend to look up Vault policies. Configuration for LDAP is identical to the LDAP auth method, but writing to to the Kerberos endpoint:
vault write auth/kerberos/config/ldap @vault-config/auth/ldap/config
vault write auth/kerberos/groups/example-role @vault-config/auth/ldap/groups/example-role
In non-kerberos mode, the LDAP bind and lookup works via the user that is currently trying to authenticate. If you're running LDAP together with Kerberos you might want to set a binddn/bindpass in the ldap config.
Developing
To run a development environment through Docker, use:
make dev-env
This will:
- Build the current local plugin code
- Start Vault in a Docker container
- Start a local Samba container to function as the domain server
- Start a local joined container that can be used for login testing
- Output a number of variables for you to export in your working terminal
Note: Press CTRL+C in your make dev-env
window when you'd like to stop and tear down your
dev environment.
To begin testing in a separate window, after exporting the variables given in make dev-env
:
VAULT_PLUGIN_SHA=$(openssl dgst -sha256 pkg/linux_amd64/vault-plugin-auth-kerberos|cut -d ' ' -f2)
vault write sys/plugins/catalog/auth/kerberos sha_256=${VAULT_PLUGIN_SHA} command="vault-plugin-auth-kerberos"
vault auth enable \
-path=kerberos \
-passthrough-request-headers=Authorization \
-allowed-response-headers=www-authenticate \
vault-plugin-auth-kerberos
vault write auth/kerberos/config \
keytab=@vault_svc.keytab.base64 \
service_account="vault_svc"
vault write auth/kerberos/config/ldap \
binddn=${DOMAIN_VAULT_ACCOUNT}@${REALM_NAME} \
bindpass=${DOMAIN_VAULT_PASS} \
groupattr=sAMAccountName \
groupdn="${DOMAIN_DN}" \
groupfilter="(&(objectClass=group)(member:1.2.840.113556.1.4.1941:={{.UserDN}}))" \
insecure_tls=true \
starttls=true \
userdn="CN=Users,${DOMAIN_DN}" \
userattr=sAMAccountName \
upndomain=${REALM_NAME} \
url=ldaps://${SAMBA_CONTAINER:0:12}.${DNS_NAME}
To authenticate, first drop into a Docker container, then its Python shell:
docker exec -it $DOMAIN_JOINED_CONTAINER /bin/bash
python
Revisit the VAULT_CONTAINER_PREFIX outputted earlier, as you'll need it below:
prefix = '<insert VAULT_CONTAINER_PREFIX here>'
import kerberos
import requests
host = prefix + ".matrix.lan:8200"
service = "HTTP@{}".format(host)
rc, vc = kerberos.authGSSClientInit(service=service, mech_oid=kerberos.GSS_MECH_OID_SPNEGO)
kerberos.authGSSClientStep(vc, "")
kerberos_token = kerberos.authGSSClientResponse(vc)
r = requests.post("http://{}/v1/auth/kerberos/login".format(host),
headers={'Authorization': 'Negotiate ' + kerberos_token})
print('Vault token:', r.json()['auth']['client_token'])
Tests
If you are developing this plugin and want to verify it is still functioning (and you haven't broken anything else), we recommend running the tests.
To run the tests, invoke make test
:
$ make test
You can also specify a TESTARGS
variable to filter tests like so:
$ make test TESTARGS='--run=TestConfig'
Contributors
- Clone the repo
- Make changes on a branch
- Test changes
- Submit a Pull Request to GitHub
Maintained with ❤️ by Hashicorp.
With thanks to the original creators of this plugin:
- wintoncode
- @ah-
- @sambott
- @roederja2
- @jcmturner
- @kristian-lesko