vault/website/pages/api-docs/secret/openldap/index.mdx

---
layout: api
page_title: OpenLDAP - Secrets Engines - HTTP API
sidebar_title: OpenLDAP
description: This is the API documentation for the Vault OpenLDAP secrets engine.
---

# OpenLDAP Secrets Engine (API)

This is the API documentation for the Vault OpenLDAP secrets engine. For general
information about the usage and operation of
the OpenLDAP secrets engine, please see [these docs](/docs/secrets/openldap).

This documentation assumes the OpenLDAP secrets engine is enabled at the `/openldap` path
in Vault. Since it is possible to mount secrets engines at any path, please
update your API calls accordingly.

## Configuration Management

| Method   | Path               |
| :------- | :----------------- |
| `POST`   | `/openldap/config` |
| `GET`    | `/openldap/config` |
| `DELETE` | `/openldap/config` |

This endpoint configures the OpenLDAP secret engine to managed user entries.

Note: the OpenLDAP entry used by `config` should have the necessary privileges
to search and change entry passwords in OpenLDAP.

### Parameters

- `binddn` `(string: <required>)` - Distinguished name (DN) of object to bind for managing user entries.
  Example: `cn=vault,ou=Users,dc=hashicorp,dc=com`
- `bindpass` `(string: <required>)` - Password to use along with `binddn` for managing user entries.
- `url` `(string: "ldap://127.0.0.1")` - The LDAP server to connect to. Examples: `ldaps://ldap.myorg.com`,
  `ldaps://ldap.myorg.com:636`. This can also be a comma-delineated list of URLs, e.g. `ldaps://ldap.myorg.com,
  ldaps://ldap.myorg.com:636`, in which case the servers will be tried in-order if there are errors during the
  connection process.`.
- `password_policy` `(string: <optional>)` - The name of the [password policy](/docs/concepts/password-policies)
  to use to generate passwords. Note that this accepts the name of the policy, not the policy itself.
- `schema` `(string: "openldap")` - The OpenLDAP schema to use when storing entry passwords.
  Valid schemas include:`openldap` and `racf`.
- `request_timeout` `(integer: 90, string: "90s" <optional>)` - Timeout, in seconds, for the connection when
  making requests against the server before returning back an error.
- `starttls` `(bool: <optional>)` - If true, issues a `StartTLS` command after establishing an unencrypted connection.
- `insecure_tls` - `(bool: <optional>)` - If true, skips LDAP server SSL certificate verification - insecure,
  use with caution!
- `certificate` - `(string: <optional>)` - CA certificate to use when verifying LDAP server certificate, must be
  x509 PEM encoded.
- `client_tls_cert` - `(string: <optional>)` - Client certificate to provide to the LDAP server, must be x509
  PEM encoded.
- `client_tls_key` - `(string: <optional>)` - Client key to provide to the LDAP server, must be x509 PEM encoded.

**Deprecated Parameters**:

- `length` `(int: 64)` - The length of generated password strings. Note: some schemas may require shorter
  password lengths (such as `racf`). Mutually exclusive with `password_policy`

**Note about password generation**:

`length` and `password_policy` cannot both be set in the configuration. The `POST` endpoint will reject the
configuration if both are specified.

- If neither are set, this will default to a reasonable default password generation algorithm (the same algorithm as
prior to the introduction of password policies).
- If `length` is set, the same algorithm is used, but with the length specified instead of the default length.
- If `password_policy` is set, the password will be generated from the associated
[password policy](/docs/concepts/password-policies). The policy is not exercised prior to saving the configuration.
The policy will need to exist prior to passwords needing to be generated by this engine, but does not need to exist
prior to saving the configuration.

See [OpenLDAP docs](/docs/secrets/openldap) for additional information.

### Sample Payload

```json
{
  "binddn": "cn=vault,ou=Users,dc=hashicorp,dc=com",
  "bindpass": "pa$$w0rd",
  "url": "ldaps://127.0.0.11"
}
```

### Sample POST Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/openldap/config
```

### Sample GET Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request GET \
    https://127.0.0.1:8200/v1/openldap/config
```

### Sample Response

```json
{
  "data": {
    "binddn": "cn=admin,dc=hashicorp,dc=com",
    "case_sensitive_names": false,
    "certificate": "",
    "insecure_tls": false,
    "length": 64,
    "schema": "openldap",
    "starttls": false,
    "tls_max_version": "tls12",
    "tls_min_version": "tls12",
    "url": "ldap://127.0.0.1"
  }
}
```

## Static Role Management

The `static-role` endpoint configures Vault to manage the passwords of individual OpenLDAP entries.

### Parameters

- `dn` `(string: <required>)` - Distinguished name (DN) of entry Vault should manage. Example: `cn=bob,ou=Users,dc=hashicorp,dc=com`
- `rotation_period` `(string: <required>)` - How often Vault should rotate the password of the user entry, in seconds. The minimum rotation period is 5 seconds. Example: "5s", "1h".
- `username` `(string: <required>)` - The name of the user to be used when logging in. This is useful when `dn` isn't used for login purposes (such as SSH). Example: "bob".

Distinguished name (DN) of entry Vault should manage. Example: `cn=bob,ou=Users,dc=hashicorp,dc=com`

| Method   | Path                               |
| :------- | :--------------------------------- |
| `GET`    | `/openldap/static-role`            |
| `GET`    | `/openldap/static-role/:role_name` |
| `POST`   | `/openldap/static-role/:role_name` |
| `DELETE` | `/openldap/static-role/:role_name` |

### Sample Payload

```json
{
  "dn": "cn=hashicorp,ou=Users,dc=hashicorp,dc=com",
  "rotation_period": "24h",
  "username": "hashicorp"
}
```

### Sample POST Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/openldap/static-role/hashicorp
```

### Sample GET Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request GET \
    http://127.0.0.1:8200/v1/openldap/static-role/hashicorp
```

### Sample GET Response

```json
{
  "data": {
    "dn": "uid=hashicorp,ou=Users,dc=hashicorp,dc=com",
    "last_vault_rotation": "2020-02-19T11:31:53.7812-05:00",
    "rotation_period": 86400,
    "username": "hashicorp"
  }
}
```

### Sample LIST Response

```json
["hashicorp", "bob"]
```

## Static Role Passwords

The `static-cred` endpoint offers the credential information for a given static-role.

| Method | Path                               |
| :----- | :--------------------------------- |
| `GET`  | `/openldap/static-cred/:role_name` |

### Sample Get Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request GET \
    http://127.0.0.1:8200/v1/openldap/static-cred/hashicorp
```

### Sample Get Response

```json
{
  "dn": "uid=hashicorp,ou=Users,dc=hashicorp,dc=com",
  "last_vault_rotation": "2020-02-19T11:31:53.7812-05:00",
  "password": "LTNfyn7pS7XEZIxEYQ2sEAWic02PEP7zSvIs0xMqIjaU0ORzLhKOKVmYLxL1Xkyv",
  "rotation_period": 86400,
  "ttl": 86072,
  "username": "hashicorp"
}
```

## Rotate Root Password

The `rotate-root` endpoint offers password rotation for the `binddn` entry used to manage OpenLDAP. This generated password will only be known to Vault and will not be retrievable once rotated.

| Method | Path                    |
| :----- | :---------------------- |
| `POST` | `/openldap/rotate-root` |

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    http://127.0.0.1:8200/v1/openldap/rotate-root
```

## Manually Rotate Static Role Password

The `rotate-role` endpoint offers manual rotation of static roles.

| Method | Path                               |
| :----- | :--------------------------------- |
| `POST` | `/openldap/rotate-role/:role_name` |

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    http://127.0.0.1:8200/v1/openldap/rotate-role/:role_name
```