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.

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

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 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, racf and ad.
• 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. 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 for additional information.

Sample Payload

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

Sample POST Request

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

Sample GET Request

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

Sample Response

{
  "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

Sample Payload

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

Sample POST Request

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

Sample GET Request

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

Sample GET Response

{
  "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

["hashicorp", "bob"]

Static Role Passwords

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

Sample Get Request

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

Sample Get Response

{
  "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.

Sample Request

$ 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.

Sample Request

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