Kerberos auth method (API)

warning

Note: This engine can use external X.509 certificates as part of TLS or signature validation. Verifying signatures against X.509 certificates that use SHA-1 is deprecated and is no longer usable without a workaround. See the deprecation FAQ for more information.

This is the API documentation for the OpenBao Kerberos auth method plugin. To learn more about the usage and operation, see the OpenBao Kerberos auth method.

This documentation assumes the Kerberos auth method is mounted at the auth/kerberos path in OpenBao. 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.

Configure OpenBao Kerberos

This endpoint configures the keytab and service account to be used by OpenBao 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 openbao.keytab > openbao.keytab.base64.
service_account (string: <required>) – The service account associated with both the keytab entry and an LDAP service account created for OpenBao. Ex.: "openbao_svc".
remove_instance_name - Removes any instance names from a Kerberos service principal name when parsing the keytab file. For example when this is set to true, if a keytab has the service principal name foo/localhost@example.com, OpenBao will strip the service principal name to just be foo@example.com.
add_group_aliases - When set to true, OpenBao will add any LDAP groups found for the user as group aliases.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/auth/kerberos/config

Sample payload

{
  "add_group_aliases": false,
  "keytab": "BQIAAAA6AAEACk1BVFJJWC5MQU4ACXZhdWx0X3N2YwAAAAFdzZSjAgAXABDwhEyRR9nRqkpP8KTn2A83AAAAAg==",
  "remove_instance_name": false,
  "service_account": "openbao_svc"
}

Read OpenBao Kerberos

This endpoint retrieves the service account for the Kerberos auth method. The keytab is not returned because it is sensitive information.

Method	Path
`GET`	`/auth/kerberos/config`

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/auth/kerberos/config

Sample response

{
  "auth": null,
  "warnings": null,
  "wrap_info": null,
  "data": {
    "add_group_aliases": false,
    "remove_instance_name": false,
    "service_account": "openbao_svc"
  },
  "lease_duration": 0,
  "renewable": false,
  "lease_id": ""
}

Configure Kerberos LDAP

This endpoint configures LDAP in the Kerberos auth method.

Method	Path
`POST`	`/auth/kerberos/config/ldap`

Parameters

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=openbao,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 openbao 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 token policies to encode onto generated tokens. Depending on the auth method, this list may be supplemented by user/group/other values.
policies (array: [] or comma-delimited string: "") - DEPRECATED: Please use the token_policies parameter instead. List of token 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_strictly_bind_ip (bool: false) - If set, the token will be restricted to the source IP address making the initial login request. This conflicts with token_bound_cidrs.
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 maximum allowed period value when a periodic token is requested from this role.
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.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/auth/kerberos/config/ldap

Sample payload

{
  "binddn": "cn=openbao,ou=Users,dc=example,dc=com",
  "deny_null_bind": true,
  "discoverdn": false,
  "groupattr": "cn",
  "groupdn": "ou=Groups,dc=example,dc=com",
  "groupfilter": "(\u0026(objectClass=group)(member:1.2.840.113556.1.4.1941:={{.UserDN}}))",
  "insecure_tls": false,
  "starttls": false,
  "tls_max_version": "tls12",
  "tls_min_version": "tls12",
  "url": "ldaps://ldap.myorg.com:636",
  "userattr": "samaccountname",
  "userdn": "ou=Users,dc=example,dc=com"
}

Read Kerberos LDAP configuration

This endpoint retrieves the LDAP configuration for the Kerberos auth method.

Method	Path
`GET`	`/auth/kerberos/config/ldap`

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/auth/kerberos/config/ldap

Sample response

{
  "auth": null,
  "warnings": null,
  "wrap_info": null,
  "data": {
    "binddn": "cn=openbao,ou=Users,dc=example,dc=com",
    "bindpass": "",
    "certificate": "",
    "deny_null_bind": true,
    "discoverdn": false,
    "groupattr": "cn",
    "groupdn": "ou=Groups,dc=example,dc=com",
    "groupfilter": "(\u0026(objectClass=group)(member:1.2.840.113556.1.4.1941:={{.UserDN}}))",
    "insecure_tls": false,
    "starttls": false,
    "tls_max_version": "tls12",
    "tls_min_version": "tls12",
    "upndomain": "",
    "url": "ldaps://ldap.myorg.com:636",
    "userattr": "samaccountname",
    "userdn": "ou=Users,dc=example,dc=com"
  },
  "lease_duration": 0,
  "renewable": false,
  "lease_id": ""
}

List Kerberos LDAP groups

This endpoint returns a list of existing LDAP groups in the Kerberos auth method.

Method	Path
`LIST`	`/auth/kerberos/groups`

Parameters

after (string: "") - Optional entry to begin listing after for pagination; not required to exist.
limit (int: 0) - Optional number of entries to return; defaults to all entries.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/auth/kerberos/groups

Sample response

{
  "auth": null,
  "warnings": null,
  "wrap_info": null,
  "data": {
    "keys": ["scientists", "engineers"]
  },
  "lease_duration": 0,
  "renewable": false,
  "lease_id": ""
}

Read Kerberos LDAP group

This endpoint returns the policies associated with a Kerberos LDAP group.

Method	Path
`GET`	`/auth/kerberos/groups/:name`

Parameters

name (string: <required>) – The name of the LDAP group.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/auth/kerberos/groups/admins

Sample response

{
  "data": {
    "policies": ["admin", "default"]
  },
  "renewable": false,
  "lease_id": "",
  "lease_duration": 0,
  "warnings": null
}

Create/Update Kerberos LDAP group

This endpoint creates or updates LDAP group policies.

Method	Path
`POST`	`/auth/kerberos/groups/:name`

Parameters

name (string: <required>) – The name of the LDAP group.
policies (string: "") – Comma-separated list of policies associated to the group.

Sample payload

{
  "policies": "admin,default"
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/auth/kerberos/groups/admins

Delete Kerberos LDAP group

This endpoint deletes the LDAP group and policy association.

Method	Path
`DELETE`	`/auth/kerberos/groups/:name`

Parameters

name (string: <required>) – The name of the LDAP group.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/auth/kerberos/groups/admins

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):

YIIFSwYGKwYBBQUCoIIFPzCCBTugDTALBgkqhkiG9xIBAgKiggUoBIIFJGCCBSAGCSq
GSIb3EgECAgEAboIFDzCCBQugAwIBBaEDAgEOogcDBQAgAAAAo4IEB2GCBAMwggP/oA
MCAQWhDBsKTUFUUklYLkxBTqIvMC2gAwIBA6EmMCQbBEhUVFAbHDdlZmNjZTg4MGVkM
y5tYXRyaXgubGFuOjgyMDCjggO3MIIDs6ADAgEXoQMCAQKiggOlBIIDoXky+VDSMXqT
Z8XqUiIfzX3+t1ROgO49WYQPoqW1EJLA6vOVtsLITTuDUw8WaLIexki07up3wiO7bKn
unPFN3Y6VaKZfGoubVBFnLwrxqiEqytk19fiuc0bUJD5fNX+BUeHjePPmE73kRcuchC
L5+WkbY0X37cH5uKwCWI6TxpuEc74+mvmGOdAOdisC31MO6EBnOpTlxvKOXzShVk5Xa
rkkHjTJyjoUslgm8JVdj/uB/+x16k0bFVOuWybfeCkn4FY7OeIxypxDJgk6uHU+5jpy
XsdXK4w5GG+TK5BI6LXW8ZH6NOhcTZnRyt1/S4Wihd6HKhL8lH6H+wPWAnN4Ym8jiSg
7O0nIkp9su1l/umJWnLnyUdsC9ekKmCYS9MLrmaUREnKMFfrYOF283gWVmfuSWd832Q
9PIE93vUVTfetw1OwbJXEbG7ex3BotXPJ8yaDUAz4Zv0a6zQlj6JutE7LF3JvuuQeot
QnwPhrZTrmv7ZbmGO3GmkzbMzIwcTXCCKX8ocOo8GLmtEigAPK23FOW2Y0p1meYjF0U
xPzU6MPxfQWiXTWflqabXug7uZh8u76rzSEEceosPxoBqMm6hSmGc85+0bzy/E7AGJM
5ELa2Ny2KpyniPiYCap44GsFZbGM1FwJeh1bG3dJungIn7po4X2wlg00wZVlbHsBzhP
Hys0oxVzOQfrvx88G0fH80+vyzQiQAq4ZqmZqkO0zFSsdqG8ReJvpY0eGzN6/lGwcRl
eav7Vum/s5MalXhYUdOjB4K3A5yQArHbbLfeZlhb7d4vttzPNkmaZ9ZNTyW1GSuqDtd
+YJ0g70aN82KQMWiK3cbJcx/1jcmaN5gjSDm0xk19G2eb8VlRpwLFAazOlpPGozPl0Y
PD45h3Yv3AA5aMVXvEi+NvSYR3z9VXxk6A8wFJxV5NZxV2hYwmxt0S+TYXFeudXzT+W
ySoykcsxIU6rUevmJlEqZDyD3VcdnUOE9pxrIY/cqpdBBwatorF+jIK/ytcTBjvoM6c
LL4g4n/isWMu8Xs6lSMxZzrC3Ewv9VYMzOEFxaHUXlyIC8GCN6t9DHZNzT91TC0u5Rj
XuLqXENczg33dACvr+yhvin/0QNBQG+EXz/E4NiBBWqtTFa0BiTVTwyrKL5OyiLcIVe
v4l8l9vyj/ABwDacr9ZGjhFbOShCTuFFWBPNnBwPqiRBV4y1gPP4abYBmeboLrUiqwZ
81UrP2L8rCTEtYu9q3GmW/pIHqMIHnoAMCAReigd8EgdxwBViqyCyL0+J/k2bw0upNL
h+4wzJcFBFC/wxX2aMvvIYdQv5nWwdNLMII3l/zQ0+eRdzpKfg1ZRT6x0D5278eQLto
9r1CqKNW515u4kD5+pE8VOwZJMVe3FmduaH2gnTLAcoYXkBUE24hcr0ExSY6kTTBWPj
U5dsmUsj3+qrN9JruEADqw99t/EWnN3iTsHh1rOQOd9jIJ1wCIkgvnLB8Rad+q5jguG
8qQh1WDObTlNOnezDtiuLtRb03QDo8Q4Sm72IIcLDlffVvl7WAog5TpC8qM97+Wmv0C
sWw

Method	Path
`POST`	`/auth/kerberos/login`

Sample request

$ curl \
    --header "Authorization: Negotiate YIIFSw...sWw" \
    --request POST \
    http://127.0.0.1:8200/v1/auth/kerberos/login

Configure OpenBao Kerberos​

Sample request​

Sample payload​

Read OpenBao Kerberos​

Sample request​

Sample response​

Configure Kerberos LDAP​

Parameters​

Sample request​

Sample payload​

Read Kerberos LDAP configuration​

Sample request​

Sample response​

List Kerberos LDAP groups​

Parameters​

Sample request​

Sample response​

Read Kerberos LDAP group​

Parameters​

Sample request​

Sample response​

Create/Update Kerberos LDAP group​

Parameters​

Sample payload​

Sample request​

Delete Kerberos LDAP group​

Parameters​

Sample request​

Login with Kerberos​

Sample request​

Configure OpenBao Kerberos

Sample request

Sample payload

Read OpenBao Kerberos

Sample request

Sample response

Configure Kerberos LDAP

Parameters

Sample request

Sample payload

Read Kerberos LDAP configuration

Sample request

Sample response

List Kerberos LDAP groups

Parameters

Sample request

Sample response

Read Kerberos LDAP group

Parameters

Sample request

Sample response

Create/Update Kerberos LDAP group

Parameters

Sample payload

Sample request

Delete Kerberos LDAP group

Parameters

Sample request

Login with Kerberos

Sample request