411 lines
13 KiB
Plaintext
411 lines
13 KiB
Plaintext
---
|
||
layout: api
|
||
page_title: Kerberos - Auth Methods - HTTP API
|
||
description: This is the API documentation for the Vault Kerberos auth method plugin.
|
||
---
|
||
|
||
# Kerberos Auth Method (API)
|
||
|
||
@include 'x509-sha1-deprecation.mdx'
|
||
|
||
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](/docs/auth/kerberos).
|
||
|
||
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.
|
||
|
||
## Configure Vault Kerberos
|
||
|
||
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"`.
|
||
- `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`, Vault
|
||
will strip the service principal name to just be `foo@example.com`.
|
||
- `add_group_aliases` - When set to true, Vault will add any LDAP groups found for
|
||
the user as group aliases.
|
||
|
||
### Sample Request
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request POST \
|
||
--data @payload.json \
|
||
http://127.0.0.1:8200/v1/auth/kerberos/config
|
||
```
|
||
|
||
### Sample Payload
|
||
|
||
```json
|
||
{
|
||
"add_group_aliases": false,
|
||
"keytab": "BQIAAAA6AAEACk1BVFJJWC5MQU4ACXZhdWx0X3N2YwAAAAFdzZSjAgAXABDwhEyRR9nRqkpP8KTn2A83AAAAAg==",
|
||
"remove_instance_name": false,
|
||
"service_account": "vault_svc"
|
||
}
|
||
```
|
||
|
||
## Read Vault 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
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
http://127.0.0.1:8200/v1/auth/kerberos/config
|
||
```
|
||
|
||
### Sample Response
|
||
|
||
```json
|
||
{
|
||
"auth": null,
|
||
"warnings": null,
|
||
"wrap_info": null,
|
||
"data": {
|
||
"add_group_aliases": false,
|
||
"remove_instance_name": false,
|
||
"service_account": "vault_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=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`.
|
||
|
||
@include 'tokenfields.mdx'
|
||
|
||
### Sample Request
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request POST \
|
||
--data @payload.json \
|
||
http://127.0.0.1:8200/v1/auth/kerberos/config/ldap
|
||
```
|
||
|
||
### Sample Payload
|
||
|
||
```json
|
||
{
|
||
"binddn": "cn=vault,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
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
http://127.0.0.1:8200/v1/auth/kerberos/config/ldap
|
||
```
|
||
|
||
### Sample Response
|
||
|
||
```json
|
||
{
|
||
"auth": null,
|
||
"warnings": null,
|
||
"wrap_info": null,
|
||
"data": {
|
||
"binddn": "cn=vault,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` |
|
||
|
||
### Sample Request
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request LIST \
|
||
http://127.0.0.1:8200/v1/auth/kerberos/groups
|
||
```
|
||
|
||
### Sample Response
|
||
|
||
```json
|
||
{
|
||
"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
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
http://127.0.0.1:8200/v1/auth/kerberos/groups/admins
|
||
```
|
||
|
||
### Sample Response
|
||
|
||
```json
|
||
{
|
||
"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
|
||
|
||
```json
|
||
{
|
||
"policies": "admin,default"
|
||
}
|
||
```
|
||
|
||
### Sample Request
|
||
|
||
```shell-session
|
||
$ 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
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request DELETE \
|
||
http://127.0.0.1:8200/v1/auth/kerberos/groups/admins
|
||
```
|
||
|
||
## Login with Kerberos
|
||
|
||
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
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--header "Authorization: Negotiate YIIFSw...sWw" \
|
||
--request POST \
|
||
http://127.0.0.1:8200/v1/auth/kerberos/login
|
||
```
|