Skip to content

Commit

Permalink
backport of commit 495bf0a (#17483)
Browse files Browse the repository at this point in the history 
Co-authored-by: Austin Gebauer <[email protected]>
  • Loading branch information
@hc-github-team-secure-vault-core @austingebauer
hc-github-team-secure-vault-core and austingebauer authored Oct 10, 2022
1 parent cb6652b commit 2068a5f
Showing 1 changed file with 227 additions and 69 deletions.
296 changes: 227 additions & 69 deletions website/content/docs/secrets/ldap.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down Expand Up @@ -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:

Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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 \
[email protected],[email protected] \
ttl=10h \
max_ttl=20h \
disable_check_in_enforcement=false
```

In this example, the service account names of `[email protected]` and `[email protected]` 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
--- -----
[email protected] map[available:true]
[email protected] 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 [email protected]
```

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 [email protected]
```

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 [[email protected]]
```

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 [email protected]
Key Value
--- -----
check_ins [[email protected]]
```

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 [[email protected]]
```

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)
Expand Down

0 comments on commit 2068a5f

Please sign in to comment.