open-vault/website/pages/docs/secrets/openldap/index.mdx

---
layout: docs
page_title: OpenLDAP - Secrets Engine
sidebar_title: OpenLDAP
description: >-
  The OpenLDAP secret engine manages OpenLDAP entry passwords.
---

# OpenLDAP Secrets Engine

The OpenLDAP secret engine allows management of LDAP entry passwords. At this time
only existing LDAP entries are supported by this plugin.

This plugin currently supports LDAP v3.

## Quick Setup

1. Enable the OpenLDAP secret engine:

    ```sh
    $ vault secrets enable openldap
    ```

    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 OpenLDAP
    to generate passwords:

    ```sh
    $ vault write openldap/config \
        binddn=$USERNAME \
        bindpass=$PASSWORD \
        url=ldaps://138.91.247.105
    ```

    Note: it's recommended a dedicated entry management account be created specfically for Vault.

3. Rotate the root password so only Vault knows the credentials:

    ```sh
    $ vault write -f openldap/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 specfically for Vault.

3. Configure a static role that maps a name in Vault to an entry in OpenLDAP.
    Password rotation settings will be managed by this role.

    ```sh
    $ vault write openldap/static-role/hashicorp \
        dn='uid=hashicorp,ou=users,dc=hashicorp,dc=com' \
        username='hashicorp' \
        rotation_period="24h"
    ```

4. Request credentials for the "hashicorp" role:

    ```sh
    $ vault read openldap/static-role/hashicorp
    ```

## LDAP Password Policy

The OpenLDAP 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 OpenLDAP Secret Engine supports three different schemas: `openldap` (default),
`racf` and `ad`.

### OpenLDAP

By default the OpenLDAP Secret Engine assumes the entry password is stored in `userPassword`.
The following object classes provide `userPassword`:

* `organization`
* `organizationalUnit`
* `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 openldap/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 openldap/config \
	binddn=$USERNAME \
	bindpass=$PASSWORD \
	url=ldaps://138.91.247.105 \
	schema=ad
```

## Password Generation

This engine previously allowed configuration of the length of the password that is generated
when rotating credentials. This mechanism has been deprecated 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"
}
```

## Password Rotation

Passwords can be managed in two ways:

* automatic time based rotation, and
* 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.

## API

The OpenLDAP secrets engine has a full HTTP API. Please see the [OpenLDAP secrets engine API docs](/api-docs/secret/openldap)
for more details.