LDAP secrets engine overview

Manage static and dynamic LDAP credentials and integrate with services that implement the LDAP v3 protocol, including OpenLDAP, Active Directory, and IBM Resource Access Control Facility (RACF).

Feature summary

• Use OpenLDAP, RACF, and Active Directory schemas.
• Use traditional 8-character passwords and modern, longer password phrases.
• Check-out service accounts with automatic password rotation.
• Map static Vault roles to LDAP credentials.
• Use dynamic LDAP credentials and manage LDAP user accounts through LDIF.
• Manually rotate LDAP passwords and root credentials.
• Organize related credentials with hierarchical paths.
• Self-managed static roles that can manage their own passwords.
  Enterprise
• Automatically rotate root credentials on a predefined schedule.
  Enterprise
• Automatically rotate static role credentials on a predefined schedule.
  Enterprise
• Run health checks to verify LDAP connectivity and credential validity.
  Enterprise
• Unlock locked-out Active Directory accounts for static roles on demand or automatically after rotation.
  Enterprise

Service account libraries

Use the service account functionality to create a library of service accounts that users and machines can check out and use as needed. Vault automatically rotates the associated password when the client checks the service account back in.

Clients can voluntarily check in service accounts at any time and Vault automatically returns the account to the library when the lending period ("ttl") ends.

The service account check-out functionality works with all the LDAP schemas supported by the plugin.

Static roles

Vault manages LDAP user account credentials by mapping static roles to the LDAP account. Vault supports two types of static roles:

• Self-managed static roles - The role rotates its own password without requiring an administrator LDAP account with elevated permissions to manage the plugin roles.

• Root-managed static roles - Vault rotates the password. You must configure an administrator level LDAP bind account on the plugin that has permission to change other LDAP user passwords.

Rotate on read

Vault can rotate a static role credential each time it reads the credential from /{mount_path}/static-cred/{role_name} with a configurable cooldown period that prevents redundant rotations when multiple clients read the same role in quick succession. Vault manages rotate-on-read settings independently from any schedule-based rotation on the role.

• rotate_on_read (bool: false) - Rotate credentials on read when true. Configurable at the mount or role level.
• rotate_on_read_cooldown (duration: "1m") - Minimum time between rotations. Set the duration to 0 to disable the cooldown and rotate on every read.

Dynamic roles

Dynamic roles are LDAP user accounts that Vault creates, manages, and deletes on demand.

Vault creates entirely new LDAP accounts when clients request credentials for a dynamic role. Vault automatically deletes the associated LDAP user account when the credential lease expires or is revoked. Dynamic roles require an administrator level LDAP bind account to be configured on the plugin with the permissions necessary to create and delete LDAP user accounts.

Credential rotation

For static roles, Vault automatically rotates passwords based on the configured rotation fields. It enforces an optionally-set rotation policy that controls the retry count and backoff strategy. When clients request credentials for a static role, Vault includes the time before the next rotation (ttl) in the response, the timestamp of the next scheduled rotation (next_vault_rotation), and the timestamp of the last successful rotation (last_vault_rotation).

The default password configuration does not include special characters. If you do not configure a password policy on the secrets engine, the plugin only generates 64-character passwords consisting of alphanumeric characters (A-Z, a-z, 0-9).

The plugin can also rotate root credential keys configured directly within the mount. Rotating to a Vault-generated key makes the key value inaccessible to the operator and ensures only Vault can operate as a root user to manipulate dynamic and static credentials.

Account unlock

Vault clears a login-failure lockout on the directory account associated with a static role. Unlock does not enable or disable the account.

Vault unlocks an account in two ways:

• On-demand unlock: Call the /unlock endpoint to clear the lockout immediately.
• Automatic unlock: When you set auto_unlock to true, Vault unlocks the account after each successful password rotation of the static role.

Automatic unlock runs in the background and does not block or fail the rotation. Vault does not track or retry the operation. When automatic unlock fails, Vault emits an event notification, and the account remains locked until the next successful rotation triggers another unlock attempt or an operator unlocks the account manually. Clients can read newly rotated credentials while the account remains locked, but they cannot use the credentials until an unlock succeeds.

You can set auto_unlock at the mount level on the /config endpoint and override it per role on the /static-role endpoint. The role-level setting overrides the mount-level setting. When unset, the role inherits the mount-level setting.

Account unlock supports only root-managed roles that use the Active Directory schema. The openldap and racf schemas return an error. Unlock self-managed accounts directly in the directory.

Logging

Logging for manual rotation records the same information as other rotation logging with an additional reference that the rotation happened on user request.

Rotation logging

Vault Enterprise emits logs to the standard vault.log on any successful or failed rotation.

In the case of success, Vault notes:

• the rotated credential as the first parameter, rotationID.
• the anticipated time of the next rotation as expire_time.

In the case of failure, Vault sets rotationID to err and may emit additional logs depending on the configured log level.

Vault Enterprise logs rotations with a reference to the name of the Vault role and error information if the rotation failed. The logs also indicate if the rotation was part of a periodic function.

When auto_unlock is enabled, directory monitoring logs record an additional modify operation after each successful rotation. The operation is idempotent and does not change an account that is already unlocked.

Health checks

Use the health-check/exec endpoint to run a live health check against the LDAP secrets engine. Vault performs an LDAP bind and returns a structured result indicating whether the check passed or failed, along with diagnostic details if it did not. Use the health-check/last endpoint to retrieve the cached result of the most recent execution without performing a new bind.

Vault can perform the following checks:

• Root config connectivity — verifies that the stored bind credentials (binddn / bindpass) can authenticate to the configured LDAP server.
• Static role credentials — verifies that the credentials Vault has stored for a given static role are still valid in the LDAP directory.

Both checks distinguish between general bind failures and locked accounts (OpenLDAP ppolicy "Account locked" and Active Directory error code data 775).

Refer to the health check API docs for endpoint paths, request examples, and full response field descriptions.

Hierarchical paths

The LDAP secrets plugin lets you define role and set names that contain an arbitrary number of forward slashes. Names with forward slashes define hierarchical path structures.

For example, you can configure two static roles with the names org/secure and org/platform/dev.

Names with hierarchical paths let you use the plugin API to query the available roles at a specific path with arbitrary depth. Names that end with a forward slash indicate that sub-paths reside under that path.

For example, to list all static roles under the org/ path, you can call the {mount_path}/static-role/{role_name}/ endpoint with the org path segment:

$ vault list ldap/static-role/org/

Keys
----
platform/
secure

Since Vault policies are also path-based, hierarchical names also let you define policies that map 1-1 to LDAP secrets engine roles and set paths.

Static role migration to the centralized automated rotation system

The migration process runs in the background and does not prevent ordinary operation of the plugin. Vault pauses individual static role rotations until the role migrates. Once the role migrates, the normal rotation schedule resumes. See the automated rotation documentation for further information.

Known Issues

Licensing failures in Enterprise plugins

The following plugins fail with the message '* license wrapping failed: invalid module: "agentic-iam"' when paired with a Vault license with the agentic-iam feature enabled.