How-to authenticate to Vault using Kerberos via Active Directory

Avatar
Rowan Smith
  • Updated

Introduction

Per the note on https://developer.hashicorp.com/vault/docs/auth/kerberos the Kerberos authentication method is a complex configuration method which requires a good understanding of Kerberos in order to implement successfully:

Kerberos is a very hands-on auth method. Other auth methods like LDAP and Azure only require a cursory amount of knowledge for configuration and use. Kerberos, on the other hand, is best used by people already familiar with it. We recommend that you use simpler authentication methods if your use case is achievable through them. If not, we recommend that before approaching Kerberos, you become familiar with its fundamentals.

If you are looking to implement the Kerberos authentication method within Vault this document aims to assist by providing a walkthrough of a simple working configuration.

Expected Outcome

Successful authentication to Vault using the Kerberos authentication method with Active Directory as the backend Kerberos server.

Prerequisites

  1.  Admin access to the Active Directory Domain Controller in order to perform account configuration.
  2. Three user accounts in Active Directory (one to function as the kerberos service account, one to function as the LDAP service account, one account to perform logins with as a human user would).

Configuration Details

  • Name of kerberos service account: kerberos
  • Name of human user account: raylan
  • Name of LDAP service account: ldap
  • Encryption method used: aes256-cts-hmac-sha1-96 (AES256-SHA1 in Microsoft terminology)
  • Name of kerberos service: HTTP/vault
  • Name of Active Directory domain: nicecorp.org
  • Pay careful attention in this document to where values such as the Active Directory domain is capitalised, as Kerberos is specific with regards to case sensitivity.

Procedure

Commands to run in Powershell:

  1. Validate all accounts do not have an SPN defined already:

    • setspn -L kerberos
    • setspn -L raylan
    • setspn -L ldap
  2. Only the kerberos service account should have an SPN defined - use setspn -D to remove any additional SPN's.
  3. Set the SPN for the kerberos service account to HTTP/vault:
    • setspn -U -S HTTP/vault kerberos
  4. As we are using AES256 encryption instead of the weaker default RC4-HMAC-NT we must instruct Active Directory to allow AES256 for each user account:
    • Set-ADUser -Identity kerberos -KerberosEncryptionType AES256
    • Set-ADUser -Identity raylan -KerberosEncryptionType AES256
    • The above commands populate the msDS-SupportedEncryptionTypes attribute in Active Directory. A mapping of the available encryption types to attribute value is available at the footer of this page [1].
  5. Retrieve the msDS-KeyVersionNumber attribute value for the kerberos and raylan accounts:
    • Get-ADUser kerberos -property msDS-KeyVersionNumber
    • Get-ADUser raylan -property msDS-KeyVersionNumber
      • This is used as the value for the -kvno parameter in the next commands.
      • Each time the password for either account is changed a new keytab must be generated as the msDS-KeyVersionNumber attribute will be updated in AD, rendering the old keytab invalid.
  6. Create keytabs for the kerberos and raylan accounts:
    • ktpass /princ kerberos@NICECORP.ORG /ptype krb5_nt_principal /crypto AES256-SHA1 /out kerberos.keytab -kvno 3 /pass *
    • ktpass /princ raylan@NICECORP.ORG /ptype krb5_nt_principal /crypto AES256-SHA1 /out raylan.keytab -kvno 30 /pass *
      • Ensure the relevant kvno values are used for each account, per the previous step.
      • You will be prompted to enter the current correct password for each account.
  7. Convert the kerberos.keytab file to base64 and save it as b64.kerberos.keytab.
  8. [Optional] If using an OS which includes the ktutil utility the contents of the keytab can be validated using the command below: 
    • $ ktutil --keytab=kerberos.keytab list --keys --timestamp
kerberos.keytab:
  
Vno Type Principal Date Key Aliases

3 aes256-cts-hmac-sha1-96 kerberos@NICECORP.ORG 1970-01-01 a8e11dd2603c59dbd1a996736349ien751efb0a5fc3387870b0bb06b1e46ee58

Commands to configure Vault:

  1. Enable the Kerberos authentication method, ensuring the additional headers are enabled:
    • vault auth enable -passthrough-request-headers=Authorization -allowed-response-headers=www-authenticate kerberos
      • The presence of these configuration parameters can be validated, per below:
      • $ vault read sys/auth/kerberos/tune                                
Key                            Value
---                            -----
allowed_response_headers       [www-authenticate]
default_lease_ttl              768h
description                    n/a
force_no_cache                 false
max_lease_ttl                  768h
passthrough_request_headers    [Authorization]
token_type                     default-service
  2. Write the service account and the base64 keytab for the kerberos service account to Vault:
    • vault write auth/kerberos/config keytab=@b64.kerberos.keytab service_account=kerberos
  3. Write the LDAP configuration to the Kerberos authentication mount:
    • vault write auth/kerberos/config/ldap binddn="ldap@NICECORP.ORG" bindpass="password" groupattr=sAMAccountName groupdn="OU=Groups,OU=vault-1,DC=nicecorp,DC=org" groupfilter="(&(objectClass=group)(member:1.2.840.113556.1.4.1941:={{.UserDN}}))" userdn="OU=Users,OU=vault-1,DC=nicecorp,DC=org" userattr="sAMAccountName" url="ldap://wsrv-1.nicecorp.org" upndomain="NICECORP.ORG"
      • This is a sample configuration which does not validate group searching functionality or how any other Active Directory environment is configured.
      • This is where the third account (ldap) is used.
      • The valid password for the ldap account must be supplied in the above command.
      • The account used here must have permissions to perform user and group searches across the paths specified in userdn and groupdn.

Additional Configuration:

A valid krb5.conf configuration file is required, an example of which is included below:

[libdefaults]
default_realm = NICECORP.ORG
dns_lookup_realm = false
dns_lookup_kdc = true
  ticket_lifetime = 24h
  renew_lifetime = 7d
  forwardable = true
  rdns = false
preferred_preauth_types = 18
[realms]
NICECORP.ORG = {
  kdc = wsrv-1.nicecorp.org
  admin_server = wsrv-1.nicecorp.org
  master_kdc = wsrv-1.nicecorp.org
  default_domain = wsrv-1.nicecorp.org
}

Notes on the above:

  1. default_realm corresponds to the realm of Kerberos, typically the same as the Active Directory domain name capitalised.
  2. kdc, admin_server, master_kdc, default_domain values should reflect the DNS address of an Active Directory Domain Controller.
  3. preferred_preauth_types corresponds to the encryption type used when creating the keytab(s). This must match. See [2] below for an overview of options. This guide uses AES256-SHA1.

Authenticate to Vault:

So far we have completed the following:

  1. Configured AD to allow AES256 authentication.
  2. Created keytabs for two accounts.
  3. Enabled and configured the Kerberos auth method in Vault.
  4. Created krb5.conf

We now have the required components in place to test authentication to Vault. An example login result and command is included below:

$ vault login -method=kerberos username=raylan service=HTTP/vault realm=NICECORP.ORG keytab_path=raylan.keytab krb5conf_path=krb5.conf disable_fast_negotiation=true

Success! You are now authenticated. The token information displayed below
is already stored in the token helper. You do NOT need to run "vault login"
again. Future Vault requests will automatically use this token.

Key                  Value
---                  -----
token                hvs.CAESINstorJ1WLUkmxyzxyzxyz
token_accessor       fderCJrP4KJ282zysxHHGVxz
token_duration       768h
token_renewable      false
token_policies       ["default"]
identity_policies    []
policies             ["default"]
token_meta_domain    NICECORP.ORG
token_meta_user      raylan

Now for a breakdown of the login command:

vault login -method=kerberos username=raylan service=HTTP/vault realm=NICECORP.ORG keytab_path=raylan.keytab krb5conf_path=krb5.conf disable_fast_negotiation=true

  1. username is specified as raylan, as we are now logging in as a real user.
  2. service is specified as HTTP/vault, per the SPN assigned to the kerberos service account.
  3. realm is specified as NICECORP.ORG, the Active Directory domain name capitalised.
  4. keytab_path uses the keytab we created for the raylan user.
  5. krb5conf_path uses the krb5.conf created in the previous step.
  6. disable_fast_negotiation is set to true due to Active Directory limitations.

It is worth noting all of the steps conducted above for the user "raylan" must be conducted for each user who needs to authenticate via Kerberos.

Troubleshooting Notes

Below are some general pointers with respect to utilising the Kerberos authentication method in Vault:

  • The setspn commands should be applied only against the account being used as kerberos service account
  • The kvno value that is used in the ktpass command to generate a keytab should match the msDS-KeyVersionNumber attribute from AD
  • If the end user you login to Vault with updates their password, a new keytab must be generated (as the msDS-KeyVersionNumber will increment as a result of the password change)
  • You can use the ktutil --keytab=raylan.keytab list --keys --timestamp command to inspect a keytab's kvno, encryption type, principal etc. Note this utility is not included in Windows, and there does not appear to be an equivalent in Windows.
  • The encryption type chosen when using ktpass.exe during the keytab generation process directly corresponds to the value for preferred_preauth_types in krb5.conf per https://datatracker.ietf.org/doc/html/rfc3961#section-8
  • When defining the domain related values in krb5.conf (default_realm, [realms]) the domain name should generally be capitalised, even if your domain name isn't. Unsure if it is? Check the distinguishedName attribute of any user in AD, look at the DC=nicecorp,DC=org value.
  • Matching the case across systems matters - if your UPN is raylan@nicecorp.org, make sure the case of the username value used in vault login matches.
  • Verify with ldapsearch and the user that you use as binddn for the LDAP config that you can list users in AD.
  • Clocks of the Active Directory server and the client should be in sync.

Additional Information

  1. Microsoft article detailing Kerberos supported encryption types attribute mapping: https://techcommunity.microsoft.com/t5/core-infrastructure-and-security/decrypting-the-selection-of-supported-kerberos-encryption-types/ba-p/1628797

  2. List of Kerberos encryption types: http://pig.made-it.com/kerberos-etypes.html

Articles in this section

See more

Related articles