This is the API documentation for the Vault Kerberos auth method plugin. To
learn more about the usage and operation, see the
Vault Kerberos auth method.
This documentation assumes the Kerberos auth method is mounted at the
auth/kerberos path in Vault. Since it is possible to enable auth methods at
any location, please update your API calls accordingly.
The Kerberos auth method validates both Kerberos and LDAP authorization,
so both configurations are required.
This endpoint configures the keytab and service account to be used by Vault
for verifying inbound SPNEGO tokens.
Method
Path
POST
/auth/kerberos/config
keytab(string: <required>) – A base 64 representation of the contents
of the Kerberos keytab that will be used for verifying inbound SPNEGO tokens.
It should contain an entry matching the service account given. This can be
created through the following command: $ base64 vault.keytab > vault.keytab.base64.
service_account(string: <required>) – The service account associated
with both the keytab entry and an LDAP service account created for Vault. Ex.:
"vault_svc".
url(string: <required>) – The LDAP server to connect to. Examples:
ldap://ldap.myorg.com, ldaps://ldap.myorg.com:636. Multiple URLs can be
specified with commas, e.g. ldap://ldap.myorg.com,ldap://ldap2.myorg.com;
these will be tried in-order.
case_sensitive_names(bool: false) – If set, user and group names
assigned to policies within the backend will be case sensitive. Otherwise,
names will be normalized to lower case. Case will still be preserved when
sending the username to the LDAP server at login time; this is only for
matching local user/group definitions.
starttls(bool: false) – If true, issues a StartTLS command after
establishing an unencrypted connection.
tls_min_version(string: tls12) – Minimum TLS version to use. Accepted
values are tls10, tls11, tls12 or tls13.
tls_max_version(string: tls12) – Maximum TLS version to use. Accepted
values are tls10, tls11, tls12 or tls13.
insecure_tls(bool: false) – If true, skips LDAP server SSL certificate
verification - insecure, use with caution!
certificate(string: "") – CA certificate to use when verifying LDAP server
certificate, must be x509 PEM encoded.
binddn(string: "") – Distinguished name of object to bind when performing
user search. Example: cn=vault,ou=Users,dc=example,dc=com
bindpass(string: "") – Password to use along with binddn when performing
user search.
userdn(string: "") – Base DN under which to perform user search. Example:
ou=Users,dc=example,dc=com
userattr(string: "") – Attribute on user attribute object matching the
username passed when authenticating. Examples: sAMAccountName, cn, uid
discoverdn(bool: false) – Use anonymous bind to discover the bind DN of a
user.
deny_null_bind(bool: true) – This option prevents users from bypassing
authentication when providing an empty password.
upndomain(string: "") – The userPrincipalDomain used to construct the UPN
string for the authenticating user. The constructed UPN will appear as
[username]@UPNDomain. Example: example.com, which will cause vault to bind
as username@example.com.
groupfilter(string: "") – Go template used when constructing the group
membership query. The template can access the following context variables:
[UserDN, Username]. The default is
(|(memberUid={{.Username}})(member={{.UserDN}})(uniqueMember={{.UserDN}})),
which is compatible with several common directory schemas. To support
nested group resolution for Active Directory, instead use the following
query: (&(objectClass=group)(member:1.2.840.113556.1.4.1941:={{.UserDN}})).
groupdn(string: "") – LDAP search base to use for group membership
search. This can be the root containing either groups or users. Example:
ou=Groups,dc=example,dc=com
groupattr(string: "") – LDAP attribute to follow on objects returned by
groupfilter in order to enumerate user group membership. Examples: for
groupfilter queries returning group objects, use: cn. For queries
returning user objects, use: memberOf. The default is cn.
token_ttl(integer: 0 or string: "") - The incremental lifetime for
generated tokens. This current value of this will be referenced at renewal
time.
token_max_ttl(integer: 0 or string: "") - The maximum lifetime for
generated tokens. This current value of this will be referenced at renewal
time.
token_policies(array: [] or comma-delimited string: "") - List of
policies to encode onto generated tokens. Depending on the auth method, this
list may be supplemented by user/group/other values.
token_bound_cidrs(array: [] or comma-delimited string: "") - List of
CIDR blocks; if set, specifies blocks of IP addresses which can authenticate
successfully, and ties the resulting token to these blocks as well.
token_explicit_max_ttl(integer: 0 or string: "") - If set, will encode
an explicit max
TTL
onto the token. This is a hard cap even if token_ttl and token_max_ttl
would otherwise allow a renewal.
token_no_default_policy(bool: false) - If set, the default policy will
not be set on generated tokens; otherwise it will be added to the policies set
in token_policies.
token_num_uses(integer: 0) - The maximum number of times a generated
token may be used (within its lifetime); 0 means unlimited.
If you require the token to have the ability to create child tokens,
you will need to set this value to 0.
token_period(integer: 0 or string: "") - The
period,
if any, to set on the token.
token_type(string: "") - The type of token that should be generated. Can
be service, batch, or default to use the mount's tuned default (which
unless changed will be service tokens). For token store roles, there are two
additional possibilities: default-service and default-batch which specify
the type to return unless the client requests a different type at generation
time.
This endpoint allows you to log in with a valid Kerberos SPNEGO
token. This token is obtained by the client, marshalled, and
converted to base 64 using standard encoding.
Example SPNEGO token (newlines added for readability):
