Use dynamic credentials with LDAP

Use dynamic LDAP credentials and manage LDAP user accounts through LDIF.

Before you start

Check your Vault permissions. You must have permission to enable and configure plugins in Vault.
You must have an LDAP plugin configured for OpenLDAP or Active Directory. If you do not already have an LDAP plugin enabled, follow the setup guide.

Step 1: Create your LDAP LDIF entries

Vault manages LDAP accounts through LDIF entries. LDIF entries are a base64-encoded version of the LDIF string that Vault parses and validates against proper LDIF syntax.

LDIF parameters (*_ldif) define account templates using the go template language.

When you craft your LDIF entries:

Check for, and remove, trailing spaces on any line, including empty lines.
Make sure each modify block has an empty line before it and closes with a single dash (-).

You can define multiple modifications for a dn entry in a single modify block.

Example LDIF file:

dn: uid=johndoe,ou=users,dc=example,dc=com
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
uid: johndoe
cn: John Doe
sn: Doe
givenName: John
mail: john.doe@example.com

Note

Windows Servers hosting Active Directory include a configuration setting that lets clients authenticate with old passwords for a specified amount of time.

Refer to the

Setting in NTLM network authentication behavior guidance on learn.microsoft.com if you want to change that behavior.

To create a user programmatically in Active Directory, you first add a user object and then modify that user to provide a password using the unicodePwd field and enable the account.

Passwords entries must:

Start with two (2) colons (::).
Be enclosed in double quotes (" ").
Be writen in UTF16LE format.
Use base64-encoding.

Once you set the password, you can enable the account with the userAccountControl field:

`userAccountControl`	Result
`512`	Enables the account
`65536`	Disable AD password expiration for the dynamic user account

You set userAccountControl flags cumulatively. For example, to enable the account and disable password expiration, set userAccountControl to 66048 :

(enable + disable password) = 512 + 65536 = 66048

If you need backward compatibility with legacy Windows NT systems, you can use sAMAccountName, which has a limit of 20 characters . Keep the character limit in mind when defining username_template, which typically looks like v_{{.DisplayName}}_{{.RoleName}}_{{random 10}}_{{unix_time}}.

We recommend customizing the username template in your role configuration to generate accounts with names less than 20 characters if you need backward compatibility.

Example LDIF file:

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
-

Note

Active Directory does not let you add dynamic users directly to groups by modifying the memberOf attribute because memberOf is the back-link half of a linked attribute pair with the member attribute of a group. You can only modify the forward attribute of a linked pair.

To add a newly-created dynamic user to a group, you must issue a modify request to the desired group and update the group membership with the new user.

Step 2: Create a Vault role configuration file

For easier maintenance and reuse, create a JSON file ldap-role.json, with the dynamic role details so Vault knows how to create an LDAP domain user account.

We strongly recommend configuring a rollback LDIF to ensure Vault removes any partialy created entities in the event of a failure. Vault automatically runs the rollback statments if credential creation fails for any reason.

{
  "creation_ldif": "@/path/to/creation.ldif",
  "deletion_ldif": "@/path/to/deletion.ldif",
  "rollback_ldif": "@/path/to/rollback.ldif",
  "default_ttl":   "1h",
  "max_ttl":       "24h"
}

Step 3: Save the Vault role

Use vault write with the /{mount_path}/static-role path and your dynamic role configuration, ldap-role.json, to create a new dynamic role entry:

$ vault write <mount_path>/role/<role_name> @ldap-role.json

For example:

$ vault write devcreds/role/developers @ldap-role.json

Make a POST call to /{mount_path}/role/{role_name} with your dynamic role configuration, ldap-role.json, to create a new dynamic role entry:

$ curl                                                \
  --request POST                                      \
  --header    "X-Vault-Token: ${VAULT_TOKEN}"         \
  --namespace "X-Vault-Namespace: ${VAULT_NAMESPACE}" \
  --data @ldap-role.json                              \
  ${VAULT_ADDR}/v1/<mount_path>/role/<role_name>

For example:

$ curl                                                \
  --request POST                                      \
  --header    "X-Vault-Token: ${VAULT_TOKEN}"         \
  --namespace "X-Vault-Namespace: ${VAULT_NAMESPACE}" \
  --data @ldap-role.json                              \
  ${VAULT_ADDR}/v1/devcreds/role/developers

Step 4: Test credential generation

Generate credentials to confirm setup:

Use vault write with the /{mount_path}/static-role path and your dynamic role configuration, ldap-role.json, to create a new dynamic role entry:

$ vault write <mount_path>/role/<role_name> @ldap-role.json

For example:

$ vault write devcreds/role/developers @ldap-role.json

Make a POST call to /{mount_path}/role/{role_name} with your dynamic role configuration, ldap-role.json, to create a new dynamic role entry:

$ curl                                                \
  --request POST                                      \
  --header    "X-Vault-Token: ${VAULT_TOKEN}"         \
  --namespace "X-Vault-Namespace: ${VAULT_NAMESPACE}" \
  --data @ldap-role.json                              \
  ${VAULT_ADDR}/v1/<mount_path>/role/<role_name>

For example:

$ curl                                                \
  --request POST                                      \
  --header    "X-Vault-Token: ${VAULT_TOKEN}"         \
  --namespace "X-Vault-Namespace: ${VAULT_NAMESPACE}" \
  --data @ldap-role.json                              \
  ${VAULT_ADDR}/v1/devcreds/role/developers

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.