Set up the LDAP secrets plugin

Enable and configure an instance of the ldap plugin to use with OpenLDAP or Active Directory.

Before you start

Check your Vault permissions. You must have permission to enable and configure plugins in Vault.
Create an LDAP account for Vault. We highly recommend creating a dedicated entry management account for Vault.

Step 1: Enable the LDAP secrets plugin

Use vault secrets enable to establish a new instance of the ldap plugin. By default, Vault uses the plugin name as the mount path. To configure a custom mount path, use the -path flag:

$ vault secrets enable -path <mount_path> ldap

For example:

$ vault secrets enable -path devcreds ldap

Make a POST call to /sys/mounts/{mount_path}:

$ curl                                                \
  --request POST                                      \
  --header    "X-Vault-Token: ${VAULT_TOKEN}"         \
  --namespace "X-Vault-Namespace: ${VAULT_NAMESPACE}" \
  --data '{"type": "ldap"}'                           \
  ${VAULT_ADDR}/v1/sys/mounts/<plugin_mount_path>

For example:

$ curl                                                \
  --request POST                                      \
  --header    "X-Vault-Token: ${VAULT_TOKEN}"         \
  --namespace "X-Vault-Namespace: ${VAULT_NAMESPACE}" \
  --data '{"type": "ldap"}'                           \
  ${VAULT_ADDR}/v1/sys/mounts/devcreds

/sys/mounts/{mount_path} does not return data on success.

Open the Enable a Secrets Engine page:
1. Open the GUI for your Vault instance.
2. Log in under the namespace for the plugin or select the namespace from the selector at the bottom of the left-hand menu and re-authenticate.
3. Select Secrets Engines from the left-hand menu.
4. Click Enable new engine + on the Secrets Engines page.

Select the "LDAP" plugin.
Enter a unique path for the plugin and set your basic plugin settings.

Step 2: Create a plugin configuration file

For easier maintenance and reuse, create a JSON file with your preferred configuration details.

Use the schema enum openldap to create a basic configuration file called ldap.json:

{
  "schema":          "openldap",
  "binddn":          "<ldap_username>",
  "bindpass":        "<ldap_password>",
  "url":             "<ldap_server_uri>",
  "credential_type": "<password | phrase>"
}

For example:

{
  "schema":          "openldap",
  "binddn":          "cn=admin,dc=abc,dc=com",
  "bindpass":        "iamabadpassword",
  "url":             "ldaps://138.91.247.105",
  "credential_type": "password"
}

By default, the LDAP secrets plugin assumes you have stored the entry password in userPassword. But you can also provide provide userPassword using other object classes such as:

Use the schema enum ad to create a basic configuration file called ldap.json:

{
  "schema":           "ad",
  "binddn":          "<ldap_username>",
  "bindpass":        "<ldap_password>",
  "url":             "<ldap_server_uri>",
  "credential_type": "<password | phrase>"
}

For example:

{
  "schema":          "ad",
  "binddn":          "cn=admin,dc=abc,dc=com",
  "bindpass":        "iamabadpassword",
  "url":             "ldaps://138.91.247.105",
  "credential_type": "password"
}

Step 3: Configure the LDAP plugin

Apply your configuration details so Vault can communicate with your LDAP server.

Use vault write with the {mount_path}/config path to apply your ldap.json configuration file:

$ vault write <mount_path>/config @ldap.json

For example:

$ vault write devcreds/config @ldap.json

Make a POST call to /{mount_path}/config to apply your configuration file, ldap-config.json:

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

For example:

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

If you have the plugin landing page open, click Configure {plugin_type} >. Otherwise:
1. Open the GUI for your Vault instance.
2. Log in under the namespace for the plugin or select the namespace from the selector at the bottom of the left-hand menu and re-authenticate.
3. Select Secrets Engines from the left-hand menu.
4. Click the plugin mount you want to configure.
5. Click Configure {plugin_type} >.

Select your LDAP schema.
Update the rotation details according to your configuration file.
Click Save.

Step 4: Rotate the root password

Once you connect Vault and your LDAP server, rotate the root password for the binddn account so that only Vault knows the credentials.

Use vault write with the /{mount_path}/rotate-root path to rotate the root credential:

$ vault write -f <mount_path>/rotate-root

For example:

$ vault write -f devcreds/rotate-root

Make a POST call to /{mount_path}/rotate-root to rotate the root credential:

$ curl                                                \
  --request POST                                      \
  --header    "X-Vault-Token: ${VAULT_TOKEN}"         \
  --namespace "X-Vault-Namespace: ${VAULT_NAMESPACE}" \
  ${VAULT_ADDR}/v1/sys/<mount_path>/rotate-root

For example:

$ curl                                                \
  --request POST                                      \
  --header    "X-Vault-Token: ${VAULT_TOKEN}"         \
  --namespace "X-Vault-Namespace: ${VAULT_NAMESPACE}" \
  ${VAULT_ADDR}/v1/sys/devcreds/rotate-root

Note

Once you rotate the root credential you cannot retrieve the newly generated password.