How-to authenticate to Vault using Kerberos via Active Directory

Steps

The information contained in this article has been verified as up-to-date on the date of the original publication of the article.  HashiCorp endeavors to keep this information up-to-date and correct, but it makes no representations or warranties of any kind, express or implied, about the ongoing completeness, accuracy, reliability, or suitability of the information provided.

All information contained in this article is for general information purposes only.  Any reliance you place on such information as it applies to your use of your HashiCorp product is therefore strictly at your own risk.

Introduction

Per the note on the Kerberos auth method document, the Kerberos authentication method is a complex configuration method that requires a good understanding of Kerberos 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.nicecorp.org
• 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: While a short name (e.g., HTTP/vault) can technically be used, it requires the client to explicitly request that exact, non-standard name. For all production and robust environments, we strongly recommend using the Fully-Qualified Domain Name (FQDN), which is the industry standard and aligns with how most Kerberos clients resolve service tickets. Set the SPN using the recommended FQDN (HTTP/vault.nicecorp.org)
   • setspn -U -S HTTP/vault.nicecorp.org 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 Accounts:
   • ktpass /princ HTTP/vault.nicecorp.org@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 *
     • Note: For the kerberos service account keytab, the principal (/princ) must match the FQDN SPN registered in Active Directory.
     • 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.nicecorp.org 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.nicecorp.org 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.nicecorp.org, using the Fully-Qualified Domain Name (FQDN) assigned to the Kerberos service account (matching the SPN set in Active Directory).
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