--- 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: )` - Distinguished name (DN) of object to bind for managing user entries. Example: `cn=vault,ou=Users,dc=hashicorp,dc=com` - `bindpass` `(string: )` - 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: )` - 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" )` - Timeout, in seconds, for the connection when making requests against the server before returning back an error. - `starttls` `(bool: )` - If true, issues a `StartTLS` command after establishing an unencrypted connection. - `insecure_tls` - `(bool: )` - If true, skips LDAP server SSL certificate verification - insecure, use with caution! - `certificate` - `(string: )` - CA certificate to use when verifying LDAP server certificate, must be x509 PEM encoded. - `client_tls_cert` - `(string: )` - Client certificate to provide to the LDAP server, must be x509 PEM encoded. - `client_tls_key` - `(string: )` - 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: )` - Distinguished name (DN) of entry Vault should manage. Example: `cn=bob,ou=Users,dc=hashicorp,dc=com` - `rotation_period` `(string: )` - 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: )` - 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 ```