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: <optional>)` - 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. Default is `ldap://127.0.0.1`.
- `length` `(int: 64)` - The length of generated password strings.  Note: some schemas may require shorter password lengths (such as `racf`).
- `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.

### Sample Payload

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

### Sample POST Request

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

### Sample GET Request

```sh
$ 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

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

### Sample GET Request

```sh
$ 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

```sh
$ 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

```sh
$ 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

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