--- 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: )` - 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" )` - 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. ### 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: )` - 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 ```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 ```