secrets/ldap: updates documentation (#17481)
* secrets/ldap: updates documentation * Update website/content/docs/secrets/ldap.mdx Co-authored-by: John-Michael Faircloth <fairclothjm@users.noreply.github.com>
This commit is contained in:
Austin Gebauer
GitHub
parent
5264783e6c
commit
ae17e57e73
|
|
@ -9,12 +9,17 @@ description: >-
|
|||
|
||||
@include 'x509-sha1-deprecation.mdx'
|
||||
|
||||
The LDAP secret engine allows management of LDAP entry passwords as well as dynamic creation of credentials.
|
||||
This engine supports interacting with Active Directory which is compatible with LDAP v3.
|
||||
The LDAP secrets engine provides management of LDAP credentials as well as dynamic
|
||||
creation of credentials. It supports integration with implementations of the LDAP
|
||||
v3 protocol, including OpenLDAP, Active Directory, and IBM Resource Access Control
|
||||
Facility (RACF).
|
||||
|
||||
This plugin currently supports LDAP v3.
|
||||
The secrets engine has three primary features:
|
||||
- [Static Credentials](/docs/secrets/ldap#static-credentials)
|
||||
- [Dynamic Credentials](/docs/secrets/ldap#dynamic-credentials)
|
||||
- [Service Account Check-Out](/docs/secrets/ldap#service-account-check-out)
|
||||
|
||||
## Quick Setup
|
||||
## Setup
|
||||
|
||||
1. Enable the LDAP secret engine:
|
||||
|
||||
|
|
@ -46,71 +51,7 @@ This plugin currently supports LDAP v3.
|
|||
Note: it's not possible to retrieve the generated password once rotated by Vault.
|
||||
It's recommended a dedicated entry management account be created specifically for Vault.
|
||||
|
||||
### Password Generation
|
||||
|
||||
This engine previously allowed configuration of the length of the password that is generated
|
||||
when rotating credentials. This mechanism was deprecated in Vault 1.5 in favor of
|
||||
[password policies](/docs/concepts/password-policies). This means the `length` field should
|
||||
no longer be used. The following password policy can be used to mirror the same behavior
|
||||
that the `length` field provides:
|
||||
|
||||
```hcl
|
||||
length=<length>
|
||||
rule "charset" {
|
||||
charset = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
|
||||
}
|
||||
```
|
||||
|
||||
## Static Roles
|
||||
|
||||
### Setup
|
||||
|
||||
1. Configure a static role that maps a name in Vault to an entry in LDAP.
|
||||
Password rotation settings will be managed by this role.
|
||||
|
||||
```sh
|
||||
$ vault write ldap/static-role/hashicorp \
|
||||
dn='uid=hashicorp,ou=users,dc=hashicorp,dc=com' \
|
||||
username='hashicorp' \
|
||||
rotation_period="24h"
|
||||
```
|
||||
|
||||
2. Request credentials for the "hashicorp" role:
|
||||
|
||||
```sh
|
||||
$ vault read ldap/static-cred/hashicorp
|
||||
```
|
||||
|
||||
### LDAP Password Policy
|
||||
|
||||
The LDAP secret engine does not hash or encrypt passwords prior to modifying
|
||||
values in LDAP. This behavior can cause plaintext passwords to be stored in LDAP.
|
||||
|
||||
To avoid having plaintext passwords stored, the LDAP server should be configured
|
||||
with an LDAP password policy (ppolicy, not to be confused with a Vault password
|
||||
policy). A ppolicy can enforce rules such as hashing plaintext passwords by default.
|
||||
|
||||
The following is an example of an LDAP password policy to enforce hashing on the
|
||||
data information tree (DIT) `dc=hashicorp,dc=com`:
|
||||
|
||||
```
|
||||
dn: cn=module{0},cn=config
|
||||
changetype: modify
|
||||
add: olcModuleLoad
|
||||
olcModuleLoad: ppolicy
|
||||
|
||||
dn: olcOverlay={2}ppolicy,olcDatabase={1}mdb,cn=config
|
||||
changetype: add
|
||||
objectClass: olcPPolicyConfig
|
||||
objectClass: olcOverlayConfig
|
||||
olcOverlay: {2}ppolicy
|
||||
olcPPolicyDefault: cn=default,ou=pwpolicies,dc=hashicorp,dc=com
|
||||
olcPPolicyForwardUpdates: FALSE
|
||||
olcPPolicyHashCleartext: TRUE
|
||||
olcPPolicyUseLockout: TRUE
|
||||
```
|
||||
|
||||
### Schema
|
||||
### Schemas
|
||||
|
||||
The LDAP Secret Engine supports three different schemas:
|
||||
|
||||
|
|
@ -160,6 +101,26 @@ $ vault write ldap/config \
|
|||
schema=ad
|
||||
```
|
||||
|
||||
## Static Credentials
|
||||
|
||||
### Setup
|
||||
|
||||
1. Configure a static role that maps a name in Vault to an entry in LDAP.
|
||||
Password rotation settings will be managed by this role.
|
||||
|
||||
```sh
|
||||
$ vault write ldap/static-role/hashicorp \
|
||||
dn='uid=hashicorp,ou=users,dc=hashicorp,dc=com' \
|
||||
username='hashicorp' \
|
||||
rotation_period="24h"
|
||||
```
|
||||
|
||||
2. Request credentials for the "hashicorp" role:
|
||||
|
||||
```sh
|
||||
$ vault read ldap/static-cred/hashicorp
|
||||
```
|
||||
|
||||
### Password Rotation
|
||||
|
||||
Passwords can be managed in two ways:
|
||||
|
|
@ -302,6 +263,203 @@ member: CN={{.Username}},OU=HashiVault,DC=adtesting,DC=lab
|
|||
-
|
||||
```
|
||||
|
||||
## Service Account Check-Out
|
||||
|
||||
Service account check-out provides a library of service accounts that can be checked out
|
||||
by a person or by machines. Vault will automatically rotate the password each time a
|
||||
service account is checked in. Service accounts can be voluntarily checked in, or Vault
|
||||
will check them in when their lending period (or, "ttl", in Vault's language) ends.
|
||||
|
||||
The service account check-out functionality works with various [schemas](/api-docs/secret/ldap#schema),
|
||||
including OpenLDAP, Active Directory, and RACF. In the following usage example, the secrets
|
||||
engine is configured to manage a library of service accounts in an Active Directory instance.
|
||||
|
||||
First we'll need to enable the LDAP secrets engine and tell it how to securely connect
|
||||
to an AD server.
|
||||
|
||||
```shell-session
|
||||
$ vault secrets enable ldap
|
||||
Success! Enabled the ad secrets engine at: ldap/
|
||||
|
||||
$ vault write ldap/config \
|
||||
binddn=$USERNAME \
|
||||
bindpass=$PASSWORD \
|
||||
url=ldaps://138.91.247.105 \
|
||||
userdn='dc=example,dc=com'
|
||||
```
|
||||
|
||||
Our next step is to designate a set of service accounts for check-out.
|
||||
|
||||
```shell-session
|
||||
$ vault write ldap/library/accounting-team \
|
||||
service_account_names=fizz@example.com,buzz@example.com \
|
||||
ttl=10h \
|
||||
max_ttl=20h \
|
||||
disable_check_in_enforcement=false
|
||||
```
|
||||
|
||||
In this example, the service account names of `fizz@example.com` and `buzz@example.com` have
|
||||
already been created on the remote AD server. They've been set aside solely for Vault to handle.
|
||||
The `ttl` is how long each check-out will last before Vault checks in a service account,
|
||||
rotating its password during check-in. The `max_ttl` is the maximum amount of time it can live
|
||||
if it's renewed. These default to `24h`, and both use [duration format strings](/docs/concepts/duration-format).
|
||||
Also by default, a service account must be checked in by the same Vault entity or client token that
|
||||
checked it out. However, if this behavior causes problems, set `disable_check_in_enforcement=true`.
|
||||
|
||||
When a library of service accounts has been created, view their status at any time to see if they're
|
||||
available or checked out.
|
||||
|
||||
```shell-session
|
||||
$ vault read ldap/library/accounting-team/status
|
||||
Key Value
|
||||
--- -----
|
||||
buzz@example.com map[available:true]
|
||||
fizz@example.com map[available:true]
|
||||
```
|
||||
|
||||
To check out any service account that's available, simply execute:
|
||||
|
||||
```shell-session
|
||||
$ vault write -f ldap/library/accounting-team/check-out
|
||||
Key Value
|
||||
--- -----
|
||||
lease_id ldap/library/accounting-team/check-out/EpuS8cX7uEsDzOwW9kkKOyGW
|
||||
lease_duration 10h
|
||||
lease_renewable true
|
||||
password ?@09AZKh03hBORZPJcTDgLfntlHqxLy29tcQjPVThzuwWAx/Twx4a2ZcRQRqrZ1w
|
||||
service_account_name fizz@example.com
|
||||
```
|
||||
|
||||
If the default `ttl` for the check-out is higher than needed, set the check-out to last
|
||||
for a shorter time by using:
|
||||
|
||||
```shell-session
|
||||
$ vault write ldap/library/accounting-team/check-out ttl=30m
|
||||
Key Value
|
||||
--- -----
|
||||
lease_id ldap/library/accounting-team/check-out/gMonJ2jB6kYs6d3Vw37WFDCY
|
||||
lease_duration 30m
|
||||
lease_renewable true
|
||||
password ?@09AZerLLuJfEMbRqP+3yfQYDSq6laP48TCJRBJaJu/kDKLsq9WxL9szVAvL/E1
|
||||
service_account_name buzz@example.com
|
||||
```
|
||||
|
||||
This can be a nice way to say, "Although I _can_ have a check-out for 24 hours, if I
|
||||
haven't checked it in after 30 minutes, I forgot or I'm a dead instance, so you can just
|
||||
check it back in."
|
||||
|
||||
If no service accounts are available for check-out, Vault will return a 400 Bad Request.
|
||||
|
||||
```shell-session
|
||||
$ vault write -f ldap/library/accounting-team/check-out
|
||||
Error writing data to ldap/library/accounting-team/check-out: Error making API request.
|
||||
|
||||
URL: POST http://localhost:8200/v1/ldap/library/accounting-team/check-out
|
||||
Code: 400. Errors:
|
||||
|
||||
* No service accounts available for check-out.
|
||||
```
|
||||
|
||||
To extend a check-out, renew its lease.
|
||||
|
||||
```shell-session
|
||||
$ vault lease renew ldap/library/accounting-team/check-out/0C2wmeaDmsToVFc0zDiX9cMq
|
||||
Key Value
|
||||
--- -----
|
||||
lease_id ldap/library/accounting-team/check-out/0C2wmeaDmsToVFc0zDiX9cMq
|
||||
lease_duration 10h
|
||||
lease_renewable true
|
||||
```
|
||||
|
||||
Renewing a check-out means its current password will live longer, since passwords are rotated
|
||||
anytime a password is _checked in_ either by a caller, or by Vault because the check-out `ttl`
|
||||
ends.
|
||||
|
||||
To check a service account back in for others to use, call:
|
||||
|
||||
```shell-session
|
||||
$ vault write -f ldap/library/accounting-team/check-in
|
||||
Key Value
|
||||
--- -----
|
||||
check_ins [fizz@example.com]
|
||||
```
|
||||
|
||||
Most of the time this will just work, but if multiple service accounts are checked out by the same
|
||||
caller, Vault will need to know which one(s) to check in.
|
||||
|
||||
```shell-session
|
||||
$ vault write ldap/library/accounting-team/check-in service_account_names=fizz@example.com
|
||||
Key Value
|
||||
--- -----
|
||||
check_ins [fizz@example.com]
|
||||
```
|
||||
|
||||
To perform a check-in, Vault verifies that the caller _should_ be able to check in a given service account.
|
||||
To do this, Vault looks for either the same [entity ID](https://learn.hashicorp.com/tutorials/vault/identity)
|
||||
used to check out the service account, or the same client token.
|
||||
|
||||
If a caller is unable to check in a service account, or simply doesn't try,
|
||||
Vault will check it back in automatically when the `ttl` expires. However, if that is too long,
|
||||
service accounts can be forcibly checked in by a highly privileged user through:
|
||||
|
||||
```shell-session
|
||||
$ vault write -f ldap/library/manage/accounting-team/check-in
|
||||
Key Value
|
||||
--- -----
|
||||
check_ins [fizz@example.com]
|
||||
```
|
||||
|
||||
Or, alternatively, revoking the secret's lease has the same effect.
|
||||
|
||||
```shell-session
|
||||
$ vault lease revoke ldap/library/accounting-team/check-out/PvBVG0m7pEg2940Cb3Jw3KpJ
|
||||
All revocation operations queued successfully!
|
||||
```
|
||||
|
||||
## Password Generation
|
||||
|
||||
This engine previously allowed configuration of the length of the password that is generated
|
||||
when rotating credentials. This mechanism was deprecated in Vault 1.5 in favor of
|
||||
[password policies](/docs/concepts/password-policies). This means the `length` field should
|
||||
no longer be used. The following password policy can be used to mirror the same behavior
|
||||
that the `length` field provides:
|
||||
|
||||
```hcl
|
||||
length=<length>
|
||||
rule "charset" {
|
||||
charset = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
|
||||
}
|
||||
```
|
||||
|
||||
## LDAP Password Policy
|
||||
|
||||
The LDAP secret engine does not hash or encrypt passwords prior to modifying
|
||||
values in LDAP. This behavior can cause plaintext passwords to be stored in LDAP.
|
||||
|
||||
To avoid having plaintext passwords stored, the LDAP server should be configured
|
||||
with an LDAP password policy (ppolicy, not to be confused with a Vault password
|
||||
policy). A ppolicy can enforce rules such as hashing plaintext passwords by default.
|
||||
|
||||
The following is an example of an LDAP password policy to enforce hashing on the
|
||||
data information tree (DIT) `dc=hashicorp,dc=com`:
|
||||
|
||||
```
|
||||
dn: cn=module{0},cn=config
|
||||
changetype: modify
|
||||
add: olcModuleLoad
|
||||
olcModuleLoad: ppolicy
|
||||
|
||||
dn: olcOverlay={2}ppolicy,olcDatabase={1}mdb,cn=config
|
||||
changetype: add
|
||||
objectClass: olcPPolicyConfig
|
||||
objectClass: olcOverlayConfig
|
||||
olcOverlay: {2}ppolicy
|
||||
olcPPolicyDefault: cn=default,ou=pwpolicies,dc=hashicorp,dc=com
|
||||
olcPPolicyForwardUpdates: FALSE
|
||||
olcPPolicyHashCleartext: TRUE
|
||||
olcPPolicyUseLockout: TRUE
|
||||
```
|
||||
|
||||
## API
|
||||
|
||||
The LDAP secrets engine has a full HTTP API. Please see the [LDAP secrets engine API docs](/api-docs/secret/ldap)
|
||||
|
|
|
|||
Loading…
Reference in New Issue