New Vault OSS Now Includes Multi-factor Authentication! Learn more
  • Overview
    • Automated PKI Infrastructure
    • Data Encryption & Tokenization
    • Database Credential Rotation
    • Dynamic Secrets
    • Identity-based Access
    • Key Management
    • Kubernetes Secrets
    • Secrets Management
  • Enterprise
  • Tutorials
  • Docs
  • API
  • Community
GitHubTry Cloud
Download
    • v1.10.x (latest)
    • v1.9.x
    • v1.8.x
    • v1.7.x
    • v1.6.x
    • v1.5.x
    • v1.4.x
  • What is Vault?
  • Use Cases
    • CLI Quick Start
    • HCP Quick Start
    • Developer Quick Start

  • Browser Support
  • Installing Vault
    • Overview
    • Architecture
    • High Availability
    • Integrated Storage
    • Security Model
    • Telemetry
    • Token Authentication
    • Key Rotation
    • Replication
    • Limits and Maximums
    • Overview
    • 'Dev' Server
    • Seal/Unseal
    • Namespace API Lock
    • Lease, Renew, and Revoke
    • Authentication
    • Tokens
    • Identity
    • OIDC Provider
    • Response Wrapping
    • Policies
    • Password Policies
    • Username Templating
    • High Availability
    • Storage
      • Overview
      • Autopilot
    • PGP, GnuPG, and Keybase
    • Recovery Mode
    • Resource Quotas
      • Overview
      • FAQ
    • Transform
    • Mount Migration
    • Overview
      • Overview
      • TCP
    • replication
      • Overview
      • AliCloud KMS
      • AWS KMS
      • Azure Key Vault
      • GCP Cloud KMS
      • OCI KMS
      • HSM PKCS11 ENT
      • Vault Transit
    • sentinel
      • Overview
      • Consul
      • Kubernetes
      • Overview
      • Aerospike
      • Alicloud OSS
      • Azure
      • Cassandra
      • CockroachDB
      • Consul
      • CouchDB
      • DynamoDB
      • Etcd
      • Filesystem
      • FoundationDB
      • Google Cloud Spanner
      • Google Cloud Storage
      • In-Memory
      • Manta
      • MSSQL
      • MySQL
      • OCI Object Storage
      • PostgreSQL
      • Integrated Storage (Raft)
      • S3
      • Swift
      • Zookeeper
    • telemetry
    • ui
    • Log Completed Requests
    • Entropy Augmentation ENT
    • kms_library ENT
    • Overview
    • agent
      • Overview
      • disable
      • enable
      • list
      • Overview
      • disable
      • enable
      • help
      • list
      • move
      • tune
    • debug
    • delete
      • Overview
      • delete
      • destroy
      • enable-versioning
      • get
      • list
      • metadata
      • patch
      • put
      • rollback
      • undelete
      • Overview
      • lookup
      • renew
      • revoke
      • Overview
      • get
      • inspect
    • list
    • login
    • monitor
    • namespace
      • Overview
      • diagnose
      • generate-root
      • init
      • key-status
      • members
      • migrate
      • raft
      • rekey
      • rotate
      • seal
      • step-down
      • unseal
      • usage
    • path-help
      • Overview
      • deregister
      • info
      • list
      • register
      • reload
      • Overview
      • delete
      • fmt
      • list
      • read
      • write
    • read
      • Overview
      • disable
      • enable
      • list
      • move
      • tune
    • server
    • ssh
    • status
      • Overview
      • capabilities
      • create
      • lookup
      • renew
      • revoke
    • unwrap
    • version
    • version-history
    • write
    • Token Helpers
    • Overview
      • Overview
        • Overview
        • AliCloud
        • AppRole
        • AWS
        • Azure
        • Cert
        • CF
        • GCP
        • JWT
        • Kerberos
        • Kubernetes
        • Overview
        • File
      • Overview
        • Overview
        • Kubernetes
    • Templates
    • Windows service

    • Overview
    • Active Directory
    • AliCloud
    • AWS
    • Azure
    • Consul
    • Cubbyhole
      • Overview
      • Cassandra
      • Couchbase
      • Elasticsearch
      • HanaDB
      • IBM Db2
      • InfluxDB
      • MongoDB
      • MongoDB Atlas
      • MSSQL
      • MySQL/MariaDB
      • Oracle
      • PostgreSQL
      • Redshift
      • Snowflake
      • Custom
    • Google Cloud
    • Google Cloud KMS
      • Overview
      • Azure Key Vault
      • AWS KMS
      • GCP Cloud KMS
    • KMIP ENTERPRISE
      • Overview
      • K/V Version 1
      • K/V Version 2
      • Overview
      • Identity Tokens
      • OIDC Identity Provider
    • MongoDB Atlas
    • Nomad
    • OpenLDAP
    • PKI (Certificates)
    • RabbitMQ
      • Overview
      • Signed Certificates
      • SSH OTP
      • Dynamic Key
    • Terraform Cloud
    • TOTP
      • Overview
      • FF3-1 Tweak Usage
      • Tokenization Transform ENTERPRISE
    • Transit
    • Venafi (Certificates)
    • Overview
    • AppRole
    • AliCloud
    • AWS
    • Azure
    • Cloud Foundry
    • GitHub
    • Google Cloud
      • Overview
      • OIDC Providers
    • Kerberos
    • Kubernetes
    • LDAP
      • Overview
      • FAQ
    • Oracle Cloud Infrastructure
    • Okta
    • RADIUS
    • TLS Certificates
    • Tokens
    • Username & Password

    • App ID DEPRECATED
    • MFA LEGACY / UNSUPPORTED
    • Overview
    • File
    • Syslog
    • Socket
    • Overview
    • Plugin Architecture
    • Plugin Development
    • Plugin Management
    • Plugin Portal
  • Vault Integration Program
  • Troubleshoot

    • Overview
      • Overview
      • Agent Injector vs. Vault CSI Provider
        • Overview
        • Running Vault
        • Enterprise Licensing
        • Running Vault on OpenShift
        • Configuration
          • Overview
          • Development
          • Standalone with Load Balanced UI
          • Standalone with TLS
          • Standalone with Audit Storage
          • External Vault
          • Using Kubernetes Auth Method
          • HA Cluster with Consul
          • HA Cluster with Raft
          • HA Enterprise Cluster with Raft
          • HA Enterprise DR Clusters with Raft
          • HA Enterprise Performance Clusters with Raft
          • Vault Agent Injector TLS Configuration
          • Vault Agent Injector TLS with Cert-Manager
        • Overview
        • Annotations
        • Installation
        • Examples
        • Overview
        • Installation
        • Configurations
        • Examples
      • Overview
      • Vault Lambda Extension
      • Running Vault
      • Overview
      • Installation
      • Configuration
      • Troubleshooting
      • Overview
      • Installation
      • Troubleshooting

    • Overview
    • Upgrade Plugins
    • Upgrade to 1.10.x
    • Upgrade to 1.9.x
    • Upgrade to 1.8.x
    • Upgrade to 1.7.x
    • Upgrade to 1.6.3
    • Upgrade to 1.6.2
    • Upgrade to 1.6.1
    • Upgrade to 1.6.0
    • Upgrade to 1.5.3
    • Upgrade to 1.5.2
    • Upgrade to 1.5.1
    • Upgrade to 1.5.0
    • Upgrade to 1.4.6
    • Upgrade to 1.4.5
    • Upgrade to 1.4.4
    • Upgrade to 1.4.1
    • Upgrade to 1.4.0
    • Upgrade to 1.3.10
    • Upgrade to 1.3.9
    • Upgrade to 1.3.8
    • Upgrade to 1.3.5
    • Upgrade to 1.3.4
    • Upgrade to 1.3.3
    • Upgrade to 1.3.2
    • Upgrade to 1.3.0
    • Upgrade to 1.2.7
    • Upgrade to 1.2.6
    • Upgrade to 1.2.5
    • Upgrade to 1.2.4
    • Upgrade to 1.2.1
    • Upgrade to 1.2.0
    • Upgrade to 1.1.2
    • Upgrade to 1.1.1
    • Upgrade to 1.1.0
    • Upgrade to 1.0.0
    • Upgrade to 0.11.6
    • Upgrade to 0.11.2
    • Upgrade to 0.11.0
    • Upgrade to 0.10.4
    • Upgrade to 0.10.2
    • Upgrade to 0.10.0
    • Upgrade to 0.9.6
    • Upgrade to 0.9.3
    • Upgrade to 0.9.2
    • Upgrade to 0.9.1
    • Upgrade to 0.9.0
    • Upgrade to 0.8.0
    • Upgrade to 0.7.0
    • Upgrade to 0.6.4
    • Upgrade to 0.6.3
    • Upgrade to 0.6.2
    • Upgrade to 0.6.1
    • Upgrade to 0.6.0
    • Upgrade to 0.5.1
    • Upgrade to 0.5.0

    • Overview
    • 1.10.0
    • 1.9.0
    • 1.8.0
    • 1.7.0
    • 1.6.0
    • 1.5.0

    • Overview
    • FAQ

    • Overview
    • Feature Deprecation Notice and Plans
    • License
    • Client Count
    • Login MFA
    • Server Side Consistent Token

  • Glossary

    • Overview
      • Overview
      • Autoloading
      • FAQ
    • Replication
      • Overview
      • Behavioral Changes
      • Security
    • Automated Integrated Storage Snapshots
    • Lease Count Quotas
    • Entropy Augmentation
    • Seal Wrap / FIPS 140-2
    • Namespaces
    • Performance Standbys
    • Eventual Consistency
    • Control Groups
    • Managed Keys
      • Overview
      • Duo MFA
      • Okta MFA
      • PingID MFA
      • TOTP MFA
      • Overview
      • Examples
      • Properties
    • HCP Vault
Type '/' to Search

»Kerberos Auth Method

The kerberos auth method provides an automated mechanism to retrieve a Vault token for Kerberos entities.

Kerberos is a network authentication protocol invented by MIT in the 1980s. Its name is inspired by Cerberus, the three-headed hound of Hades from Greek mythology. The three heads refer to Kerberos' three entities - an authentication server, a ticket granting server, and a principals database. Kerberos underlies authentication in Active Directory, and its purpose is to distribute a network's authentication workload.

Vault's Kerberos auth method was originally written by the folks at Winton, to whom we owe a special thanks for both originally building the plugin, and for collaborating to bring it into HashiCorp's maintenance.

»Prerequisites

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.

  • MicroNugget: How Kerberos Works in Windows Active Directory
  • MIT's Kerberos Documentation
  • Kerberos: The Definitive Guide

Regardless of how you gain your knowledge, before using this auth method, ensure you are comfortable with Kerberos' high-level architecture, and ensure you've gone through the exercise of:

  • Creating a valid krb5.conf file
  • Creating a valid keytab file
  • Authenticating to your domain server with your keytab file using kinit

With that knowledge in hand, and with an environment that's already tested and confirmed working, you will be ready to use Kerberos with Vault.

»Configuration

  • Enable Kerberos authentication in Vault:
$ vault auth enable \
    -passthrough-request-headers=Authorization \
    -allowed-response-headers=www-authenticate \
    kerberos
$ vault auth enable \
    -passthrough-request-headers=Authorization \
    -allowed-response-headers=www-authenticate \
    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
$ 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
$ base64 vault.keytab > vault.keytab.base64
  • Configure the Kerberos auth method with the keytab and entry name that will be used to verify inbound login requests:
$ vault write auth/kerberos/config \
    keytab=@vault.keytab.base64 \
    service_account="vault_svc"
$ vault write auth/kerberos/config \
    keytab=@vault.keytab.base64 \
    service_account="vault_svc"
  • Configure the Kerberos auth method to communicate with LDAP using the service account configured above. This is a sample LDAP configuration. Yours will vary. Ensure you've first tested your configuration from the Vault server using a tool like ldapsearch.
$ vault write auth/kerberos/config/ldap \
    binddn=vault_svc@MATRIX.LAN \
    bindpass=$VAULT_SVC_PASSWORD \
    groupattr=sAMAccountName \
    groupdn="DC=MATRIX,DC=LAN" \
    groupfilter="(&(objectClass=group)(member:1.2.840.113556.1.4.1941:={{.UserDN}}))" \
    userdn="CN=Users,DC=MATRIX,DC=LAN" \
    userattr=sAMAccountName \
    upndomain=MATRIX.LAN \
    url=ldaps://somewhere.foo
$ vault write auth/kerberos/config/ldap \
    binddn=vault_svc@MATRIX.LAN \
    bindpass=$VAULT_SVC_PASSWORD \
    groupattr=sAMAccountName \
    groupdn="DC=MATRIX,DC=LAN" \
    groupfilter="(&(objectClass=group)(member:1.2.840.113556.1.4.1941:={{.UserDN}}))" \
    userdn="CN=Users,DC=MATRIX,DC=LAN" \
    userattr=sAMAccountName \
    upndomain=MATRIX.LAN \
    url=ldaps://somewhere.foo

The LDAP above relies upon the same code as the LDAP auth method. See its documentation for further discussion of available parameters.

  • Configure the Vault policies that should be granted to those who successfully authenticate based on their LDAP group membership. Since this is identical to the LDAP auth method, see Group Membership Resolution and LDAP Group -> Policy Mapping for further discussion.
$ vault write auth/kerberos/groups/engineering-team \
    policies=engineers
$ vault write auth/kerberos/groups/engineering-team \
    policies=engineers

The above group grants the "engineers" policy to those who authenticate via Kerberos and are found to be members of the "engineering-team" LDAP group.

»Authentication

From a client machine with a valid krb5.conf and keytab, perform a command like the following:

$ vault login -method=kerberos \
    username=grace \
    service=HTTP/my-service \
    realm=MATRIX.LAN \
    keytab_path=/etc/krb5/krb5.keytab  \
    krb5conf_path=/etc/krb5.conf \
    disable_fast_negotiation=false
$ vault login -method=kerberos \
    username=grace \
    service=HTTP/my-service \
    realm=MATRIX.LAN \
    keytab_path=/etc/krb5/krb5.keytab  \
    krb5conf_path=/etc/krb5.conf \
    disable_fast_negotiation=false
  • krb5conf_path is the path to a valid krb5.conf file describing how to communicate with the Kerberos environment.
  • keytab_path is the path to the keytab in which the entry lives for the entity authenticating to Vault. Keytab files should be protected from other users on a shared server using appropriate file permissions.
  • username is the username for the entry within the keytab to use for logging into Kerberos. This username must match a service account in LDAP.
  • service is the service principal name to use in obtaining a service ticket for gaining a SPNEGO token. This service must exist in LDAP.
  • realm is the name of the Kerberos realm. This realm must match the UPNDomain configured on the LDAP connection. This check is case-sensitive.
  • disable_fast_negotiation is for disabling the Kerberos auth method's default of using FAST negotiation. FAST is a pre-authentication framework for Kerberos. It includes a mechanism for tunneling pre-authentication exchanges using armoured KDC messages. FAST provides increased resistance to passive password guessing attacks. Some common Kerberos implementations do not support FAST negotiation.

»Troubleshooting

»Identify the Malfunctioning Piece

Once the malfunctioning piece of the journey is identified, you can focus your debugging efforts in the most useful direction.

  1. Use ldapsearch while logged into your machine hosting Vault to ensure your LDAP configuration is functional.
  2. Authenticate to your domain server using kinit, your keytab, and your krb5.conf. Do this with both Vault's keytab, and any client keytab being used for logging in. This ensures your Kerberos network is working.
  3. While logged into your client machine, verify you can reach Vault through the following command: $ curl $VAULT_ADDR/v1/sys/health.

»Build Clear Steps to Reproduce the Problem

If possible, make it easy for someone else to reproduce the problem who is outside of your company. For instance, if you expect that you should be able to login using a command like:

$ vault login -method=kerberos \
    username=my-name \
    service=HTTP/my-service \
    realm=EXAMPLE.COM \
    keytab_path=/etc/krb5/krb5.keytab  \
    krb5conf_path=/etc/krb5.conf
$ vault login -method=kerberos \
    username=my-name \
    service=HTTP/my-service \
    realm=EXAMPLE.COM \
    keytab_path=/etc/krb5/krb5.keytab  \
    krb5conf_path=/etc/krb5.conf

Then make sure you're ready to share the error output of that command, the contents of the krb5.conf file, and the entries listed in the keytab file.

After you've stripped the issue down to its simplest form, if you still encounter difficulty resolving it, it will be much easier to gain assistance by posting your reproduction to the Vault Forum or by providing it to HashiCorp Support (if applicable.)

»Additional Troubleshooting Resources

  • Troubleshooting Vault
  • The plugin's code

The Vault Kerberos library has a working integration test environment that can be referenced as an example of a full Kerberos and LDAP environment. It runs through Docker and can be started through either one of the following commands:

$ make integration
$ make dev-env
$ make integration
$ make dev-env

These commands run variations of a script that spins up a full environment, adds users, and executes a login from a client.

»API

The Kerberos auth method has a full HTTP API. Please see the Kerberos auth method API for more details.

github logoEdit this page
DocsAPILearnCommunityPrivacySecurityPress KitConsent Manager