309 lines
11 KiB
Plaintext
309 lines
11 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: LDAP - Secrets Engine
|
|
description: >-
|
|
The LDAP secret engine manages LDAP entry passwords.
|
|
---
|
|
|
|
# LDAP Secrets Engine
|
|
|
|
@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.
|
|
|
|
This plugin currently supports LDAP v3.
|
|
|
|
## Quick Setup
|
|
|
|
1. Enable the LDAP secret engine:
|
|
|
|
```sh
|
|
$ vault secrets enable ldap
|
|
```
|
|
|
|
By default, the secrets engine will mount at the name of the engine. To
|
|
enable the secrets engine at a different path, use the `-path` argument.
|
|
|
|
2. Configure the credentials that Vault uses to communicate with LDAP
|
|
to generate passwords:
|
|
|
|
```sh
|
|
$ vault write ldap/config \
|
|
binddn=$USERNAME \
|
|
bindpass=$PASSWORD \
|
|
url=ldaps://138.91.247.105
|
|
```
|
|
|
|
Note: it's recommended a dedicated entry management account be created specifically for Vault.
|
|
|
|
3. Rotate the root password so only Vault knows the credentials:
|
|
|
|
```sh
|
|
$ vault write -f ldap/rotate-root
|
|
```
|
|
|
|
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
|
|
|
|
The LDAP Secret Engine supports three different schemas:
|
|
|
|
- `openldap` (default)
|
|
- `racf`
|
|
- `ad`
|
|
|
|
#### OpenLDAP
|
|
|
|
By default, the LDAP Secret Engine assumes the entry password is stored in `userPassword`.
|
|
There are many object classes that provide `userPassword` including for example:
|
|
|
|
- `organization`
|
|
- `organizationalUnit`
|
|
- `organizationalRole`
|
|
- `inetOrgPerson`
|
|
- `person`
|
|
- `posixAccount`
|
|
|
|
#### Resource Access Control Facility (RACF)
|
|
|
|
For managing IBM's Resource Access Control Facility (RACF) security system, the secret
|
|
engine must be configured to use the schema `racf`.
|
|
|
|
Generated passwords must be 8 characters or less to support RACF. The length of the
|
|
password can be configured using a [password policy](/docs/concepts/password-policies):
|
|
|
|
```bash
|
|
$ vault write ldap/config \
|
|
binddn=$USERNAME \
|
|
bindpass=$PASSWORD \
|
|
url=ldaps://138.91.247.105 \
|
|
schema=racf \
|
|
password_policy=racf_password_policy
|
|
```
|
|
|
|
#### Active Directory (AD)
|
|
|
|
For managing Active Directory instances, the secret engine must be configured to use the
|
|
schema `ad`.
|
|
|
|
```bash
|
|
$ vault write ldap/config \
|
|
binddn=$USERNAME \
|
|
bindpass=$PASSWORD \
|
|
url=ldaps://138.91.247.105 \
|
|
schema=ad
|
|
```
|
|
|
|
### Password Rotation
|
|
|
|
Passwords can be managed in two ways:
|
|
|
|
- automatic time based rotation
|
|
- manual rotation
|
|
|
|
### Auto Password Rotation
|
|
|
|
Passwords will automatically be rotated based on the `rotation_period` configured
|
|
in the static role (minimum of 5 seconds). When requesting credentials for a static
|
|
role, the response will include the time before the next rotation (`ttl`).
|
|
|
|
Auto-rotation is currently only supported for static roles. The `binddn` account used
|
|
by Vault should be rotated using the `rotate-root` endpoint to generate a password
|
|
only Vault will know.
|
|
|
|
### Manual Rotation
|
|
|
|
Static roles can be manually rotated using the `rotate-role` endpoint. When manually
|
|
rotated the rotation period will start over.
|
|
|
|
### Deleting Static Roles
|
|
|
|
Passwords are not rotated upon deletion of a static role. The password should be manually
|
|
rotated prior to deleting the role or revoking access to the static role.
|
|
|
|
## Dynamic Credentials
|
|
|
|
### Setup
|
|
|
|
Dynamic credentials can be configured by calling the `/role/:role_name` endpoint:
|
|
|
|
```bash
|
|
$ vault write ldap/role/dynamic-role \
|
|
creation_ldif=@/path/to/creation.ldif \
|
|
deletion_ldif=@/path/to/deletion.ldif \
|
|
rollback_ldif=@/path/to/rollback.ldif \
|
|
default_ttl=1h \
|
|
max_ttl=24h
|
|
```
|
|
|
|
-> Note: The `rollback_ldif` argument is optional, but recommended. The statements within `rollback_ldif` will be
|
|
executed if the creation fails for any reason. This ensures any entities are removed in the event of a failure.
|
|
|
|
To generate credentials:
|
|
|
|
```bash
|
|
$ vault read ldap/creds/dynamic-role
|
|
Key Value
|
|
--- -----
|
|
lease_id ldap/creds/dynamic-role/HFgd6uKaDomVMvJpYbn9q4q5
|
|
lease_duration 1h
|
|
lease_renewable true
|
|
distinguished_names [cn=v_token_dynamic-role_FfH2i1c4dO_1611952635,ou=users,dc=learn,dc=example]
|
|
password xWMjkIFMerYttEbzfnBVZvhRQGmhpAA0yeTya8fdmDB3LXDzGrjNEPV2bCPE9CW6
|
|
username v_token_testrole_FfH2i1c4dO_1611952635
|
|
```
|
|
|
|
The `distinguished_names` field is an array of DNs that are created from the `creation_ldif` statements. If more than
|
|
one LDIF entry is included, the DN from each statement will be included in this field. Each entry in this field
|
|
corresponds to a single LDIF statement. No de-duplication occurs and order is maintained.
|
|
|
|
### LDIF Entries
|
|
|
|
User account management is provided through LDIF entries. The LDIF entries may be a base64-encoded version of the
|
|
LDIF string. The string will be parsed and validated to ensure that it adheres to LDIF syntax. A good reference
|
|
for proper LDIF syntax can be found [here](https://ldap.com/ldif-the-ldap-data-interchange-format/).
|
|
|
|
Some important things to remember when crafting your LDIF entries:
|
|
|
|
- There should not be any trailing spaces on any line, including empty lines
|
|
- Each `modify` block needs to be preceded with an empty line
|
|
- Multiple modifications for a `dn` can be defined in a single `modify` block. Each modification needs to close
|
|
with a single dash (`-`)
|
|
|
|
### Active Directory (AD)
|
|
|
|
For Active Directory, there are a few additional details that are important to remember:
|
|
|
|
To create a user programmatically in AD, you first `add` a user object and then `modify` that user to provide a
|
|
password and enable the account.
|
|
|
|
- Passwords in AD are set using the `unicodePwd` field. This must be proceeded by two (2) colons (`::`).
|
|
- When setting a password programmatically in AD, the following criteria must be met:
|
|
|
|
- The password must be enclosed in double quotes (`" "`)
|
|
- The password must be in [`UTF16LE` format](https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-adts/6e803168-f140-4d23-b2d3-c3a8ab5917d2)
|
|
- The password must be `base64`-encoded
|
|
- Additional details can be found [here](https://docs.microsoft.com/en-us/troubleshoot/windows-server/identity/set-user-password-with-ldifde)
|
|
|
|
- Once a user's password has been set, it can be enabled. AD uses the `userAccountControl` field for this purpose:
|
|
- To enable the account, set `userAccountControl` to `512`
|
|
- You will likely also want to disable AD's password expiration for this dynamic user account. The
|
|
`userAccountControl` value for this is: `65536`
|
|
- `userAccountControl` flags are cumulative, so to set both of the above two flags, add up the two values
|
|
(`512 + 65536 = 66048`): set `userAccountControl` to `66048`
|
|
- See [here](https://docs.microsoft.com/en-us/troubleshoot/windows-server/identity/useraccountcontrol-manipulate-account-properties#property-flag-descriptions)
|
|
for details on `userAccountControl` flags
|
|
|
|
`sAMAccountName` is a common field when working with AD users. It is used to provide compatibility with legacy
|
|
Windows NT systems and has a limit of 20 characters. Keep this in mind when defining your `username_template`.
|
|
See [here](https://docs.microsoft.com/en-us/windows/win32/adschema/a-samaccountname) for additional details.
|
|
|
|
With regard to adding dynamic users to groups, AD doesn't let you directly modify a user's `memberOf` attribute.
|
|
The `member` attribute of a group and `memberOf` attribute of a user are
|
|
[linked attributes](https://docs.microsoft.com/en-us/windows/win32/ad/linked-attributes). Linked attributes are
|
|
forward link/back link pairs, with the forward link able to be modified. In the case of AD group membership, the
|
|
group's `member` attribute is the forward link. In order to add a newly-created dynamic user to a group, we also
|
|
need to issue a `modify` request to the desired group and update the group membership with the new user.
|
|
|
|
#### Active Directory LDIF Example
|
|
|
|
The various `*_ldif` parameters are templates that use the [go template](https://golang.org/pkg/text/template/)
|
|
language. A complete LDIF example for creating an Active Directory user account is provided here for reference:
|
|
|
|
```ldif
|
|
dn: CN={{.Username}},OU=HashiVault,DC=adtesting,DC=lab
|
|
changetype: add
|
|
objectClass: top
|
|
objectClass: person
|
|
objectClass: organizationalPerson
|
|
objectClass: user
|
|
userPrincipalName: {{.Username}}@adtesting.lab
|
|
sAMAccountName: {{.Username}}
|
|
|
|
dn: CN={{.Username}},OU=HashiVault,DC=adtesting,DC=lab
|
|
changetype: modify
|
|
replace: unicodePwd
|
|
unicodePwd::{{ printf "%q" .Password | utf16le | base64 }}
|
|
-
|
|
replace: userAccountControl
|
|
userAccountControl: 66048
|
|
-
|
|
|
|
dn: CN=test-group,OU=HashiVault,DC=adtesting,DC=lab
|
|
changetype: modify
|
|
add: member
|
|
member: CN={{.Username}},OU=HashiVault,DC=adtesting,DC=lab
|
|
-
|
|
```
|
|
|
|
## API
|
|
|
|
The LDAP secrets engine has a full HTTP API. Please see the [LDAP secrets engine API docs](/api-docs/secret/ldap)
|
|
for more details.
|