mirrors/vault
1
0
Fork 0
mirror of https://github.com/hashicorp/vault.git synced 2026-05-05 12:26:34 +02:00
Code Issues Projects Releases Wiki Activity

Kerberos docs (#7993)

Browse Source
This commit is contained in:
Becca Petrin 2019-12-11 11:16:36 -08:00 committed by GitHub
parent 921f5efed4
commit f259edcceb
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 634 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

407
website/source/api/auth/kerberos/index.html.md.erb Normal file
View File

@ -0,0 +1,407 @@
---
layout: "api"
page_title: "Kerberos - Auth Methods - HTTP API"
sidebar_title: "Kerberos"
sidebar_current: "api-http-auth-kerberos"
description: |-
This is the API documentation for the Vault Kerberos auth method plugin.
---
# Kerberos Auth Method (API)
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.html).
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"`.
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/kerberos/config
```
### Sample Payload
```json
{
"keytab": "BQIAAAA6AAEACk1BVFJJWC5MQU4ACXZhdWx0X3N2YwAAAAFdzZSjAgAXABDwhEyRR9nRqkpP8KTn2A83AAAAAg==",
"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
```
$ 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": {
"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` or `tls12`.
- `tls_max_version` `(string: tls12)` – Maximum TLS version to use. Accepted
values are `tls10`, `tls11` or `tls12`.
- `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`.
<%= partial "partials/tokenfields" %>
### 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
```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
```
$ 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
```
$ 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
```
$ 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
```
$ 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
```
## 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
```
$ curl \
--header "Authorization: Negotiate YIIFSw...sWw" \
--request POST \
http://127.0.0.1:8200/v1/auth/kerberos/login
```

225
website/source/docs/auth/kerberos.html.md Normal file
View File

@ -0,0 +1,225 @@
---
layout: "docs"
page_title: "Kerberos - Auth Methods"
sidebar_title: "Kerberos"
sidebar_current: "docs-auth-kerberos"
description: |-
The Kerberos auth method allows automated authentication of Kerberos entities.
---
# Kerberos Auth Method
The `kerberos` auth method provides an automated mechanism to retrieve
a Vault token for Kerberos entities.
[Kerberos](https://web.mit.edu/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](https://github.com/wintoncode), 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](https://www.vaultproject.io/docs/auth/ldap.html) and
[Azure](https://www.vaultproject.io/docs/auth/azure.html) 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](https://www.youtube.com/watch?v=kp5d8Yv3-0c)
- [MIT's Kerberos Documentation](https://web.mit.edu/kerberos/)
- [Kerberos: The Definitive Guide](https://www.amazon.com/Kerberos-Definitive-Guide-ebook-dp-B004P1J81C/dp/B004P1J81C/ref=mt_kindle?_encoding=UTF8&me=&qid=1573685442)
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:
```text
$ vault auth enable \
-passthrough-request-headers=Authorization \
-allowed-response-headers=www-authenticate \
kerberos
```
* Create a `keytab` for the Kerberos plugin:
```text
$ 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:
```text
$ 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:
```text
$ 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`.
```text
$ 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](https://www.vaultproject.io/docs/auth/ldap.html)
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](https://www.vaultproject.io/docs/auth/ldap.html#group-membership-resolution)
and [LDAP Group -> Policy Mapping](https://www.vaultproject.io/docs/auth/ldap.html#ldap-group-gt-policy-mapping)
for further discussion.
```text
$ 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:
```text
$ vault login -method=kerberos \
username=grace \
service=HTTP/my-service \
realm=MATRIX.LAN \
keytab_path=/etc/krb5/krb5.keytab \
krb5conf_path=/etc/krb5.conf
```
- `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.
- `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.
## 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:
```text
$ 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](https://docs.oracle.com/cd/E19683-01/806-4078/6jd6cjs1q/index.html)
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](https://discuss.hashicorp.com/c/vault)
or by providing it to [HashiCorp Support](https://www.hashicorp.com/support.html)
(if applicable.)
### Additional Troubleshooting Resources
- [Troubleshooting Vault](https://learn.hashicorp.com/vault/operations/troubleshooting-vault)
- [The plugin's code](https://github.com/hashicorp/vault-plugin-auth-kerberos)
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:
```text
$ make integration
$ make dev-env
```
These commands run variations of [a script](https://github.com/hashicorp/vault-plugin-auth-kerberos/blob/master/scripts/integration_env.sh)
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](/api/auth/kerberos/index.html) for more
details.

1
website/source/layouts/api.erb
View File

@ -76,6 +76,7 @@
{ category: 'github' },
{ category: 'gcp' },
{ category: 'jwt' },
{ category: 'kerberos' },
{ category: 'kubernetes' },
{ category: 'ldap' },
{ category: 'oci' },

1
website/source/layouts/docs.erb
View File

@ -288,6 +288,7 @@
'cf',
'gcp',
'jwt',
'kerberos',
'kubernetes',
'github',
'ldap',