OpenLDAP secrets engine (API)
Note: This engine can use external X.509 certificates as part of TLS or signature validation. Verifying signatures against X.509 certificates that use SHA-1 is deprecated and will no longer be usable without a workaround starting in Vault 1.12. See the deprecation FAQ for more information.
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
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 withbinddn
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 LDAP schema to use when storing entry passwords. Valid schemas includeopenldap
,ad
, andracf
.userdn
(string: <optional>)
- The base DN under which to perform user search in library management and static roles. For example,ou=Users,dc=hashicorp,dc=com
.userattr
(string: <optional>)
– The attribute field name used to perform user search in library management and static roles. Defaults tocn
for theopenldap
schema,userPrincipalName
for thead
schema, andracfid
for theracf
schema.upndomain
(string:optional
) - The domain (userPrincipalDomain) used to construct a UPN string for authentication. The constructed UPN will appear as[binddn]@[upndomain]
. For example, ifupndomain=example.com
andbinddn=admin
, the UPN stringadmin@example.com
will be used to log in to Active Directory.connection_timeout
(integer: 30 or string: "30s")
- Timeout, in seconds, when attempting to connect to the LDAP server before trying the next URL in the configuration.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 aStartTLS
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 asracf
). Mutually exclusive withpassword_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
Sample POST request
Sample GET request
Sample response
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
Static roles
The static-role
endpoint configures Vault to manage the passwords of existing 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. Accepts time suffixed strings ("1h") or an integer number of seconds. The available units are:ns
,us
(orµs
),ms
,s
,m
,h
. The minimum rotation period is 5 seconds.
Example: "3600", "5s", "1h".username
(string: <required>)
- The name of the user to be used when logging in. This is useful whendn
isn't used for login purposes (such as SSH).
Example: "bob"
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
Sample POST request
Sample GET request
Sample GET response
Sample LIST response
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
Sample get response
Manually rotate static role password
The rotate-role
endpoint rotates the password of an existing static role.
Method | Path |
---|---|
POST | /openldap/rotate-role/:role_name |
Sample request
Dynamic roles
Create or update a dynamic role configuration. This provides instructions to Vault on how to create an OpenLDAP domain user account.
Create/Delete dynamic role configuration
Parameters
Method | Path |
---|---|
POST | /openldap/role/:role_name |
DELETE | /openldap/role/:role_name |
The POST
endpoint allows for partial updates of existing roles. If a role exists and a POST
request is made
against it, only the keys specified in the request will be updated. To delete a value, specify the key with an
empty string as the value. Example: vault write openldap/role/myrole default_ttl=""
role_name
(string, required)
- The name of the dynamic role.
creation_ldif
(string, required)
- A templatized LDIF string used to create a user account. This may contain
multiple LDIF entries. The creation_ldif
can also be used to add the user account to an existing group.
All LDIF entries are performed in order. If Vault encounters an error while executing the creation_ldif
it will
stop at the first error and not execute any remaining LDIF entries. If an error occurs and rollback_ldif
is
specified, the LDIF entries in rollback_ldif
will be executed. See rollback_ldif
for more details. This field
may optionally be provided as a base64 encoded string.
deletion_ldif
(string, required)
- A templatized LDIF string used to delete the user account once its TTL has
expired. This may contain multiple LDIF entries. All LDIF entries are performed in order. If Vault encounters an
error while executing an entry in the deletion_ldif
it will attempt to continue executing any remaining entries.
This field may optionally be provided as a base64 encoded string.
rollback_ldif
(string, not required but recommended)
- A templatized LDIF string used to attempt to rollback
any changes in the event that execution of the creation_ldif
results in an error. This may contain multiple LDIF
entries. All LDIF entries are performed in order. If Vault encounters an error while executing an entry in the
rollback_ldif
it will attempt to continue executing any remaining entries. This field may optionally be provided
as a base64 encoded string.
username_template
(string)
- A template used to generate a dynamic username. This will be used to fill in the
.Username
field within the creation_ldif
string.
Default Username Template
Example Usernames:
Example | |
---|---|
DisplayName | token |
RoleName | myrolename |
Username | v_token_myrolename_uszt1n4cyh_1614294836 |
Example | |
---|---|
DisplayName | amuchlonger_dispname |
RoleName | role-name-with-dashes |
Username | v_amuchlonger_dispname_role-name-with-dashes_s0t9xb0jsa_1614294836 |
default_ttl
(string/int)
- Specifies the TTL for the leases associated with this role. Accepts time suffixed
strings ("1h") or an integer number of seconds. Defaults to system/engine default TTL time. The
available units are: ns
, us
(or µs
), ms
, s
, m
, h
.
max_ttl
(string/int)
- Specifies the maximum TTL for the leases associated with this role. Accepts time suffixed
strings ("1h") or an integer number of seconds. Defaults to system/mount default TTL time; this value is allowed to
be less than the mount max TTL (or, if not set, the system max TTL), but it is not allowed to be longer. The
available units are: ns
, us
(or µs
), ms
, s
, m
, h
.
The creation_ldif
, deletion_ldif
, rollback_ldif
, and username_template
fields are all templated fields. See
Username Templating for details on how to use templating. Also see
Templates for specifics on what data is available for each template.
Sample payload
Sample LDIF files:
creation.ldif
:
deletion.ldif
& rollback.ldif
:
Full Payload:
Note: The LDIF statements may optionally be base64 encoded. If they are base64 encoded when creating/updating the
role configuration, the decoded version will be returned from the GET
endpoint.
Sample POST request
Read dynamic role configuration
Method | Path |
---|---|
GET | /openldap/role/:role_name |
Retrieves a dynamic role's configuration.
Parameters
None
Response
200 OK
Templates
LDIF and username templates use the Go template syntax to construct the LDIF/username that will be executed against the server. This is done because certain values (such as the username and password within an LDIF statement) are not known at configuration time. Additionally, the template gives a lot of flexibility to the operator to construct the LDIF and username.
Templated fields are delimited by {{
and }}
. To reference a field (such as the generated Username
), a period is
placed in front of the field name. Example: {{.Username}}
. Spaces can be included between {{
and }}
. For instance:
{{.Username|lowercase}}
is the same as {{ .Username | lowercase }}
.
If a field needs to be modified (such as SHA256 hashing, base64 encoding, etc.) the value can be sent to one of the
built-in functions. This uses a "pipe" syntax: {{.Username | base64}}
. Values may be "piped"
to multiple functions: {{.Username | lowercase | base64}}
LDIF template fields
The following parameters are available within the LDIF templates:
.Username
- The name of the generated user (optionally from username_template
).
Default pattern: v_<display name>_<role name>_<10 random chars>_<unix timestamp>
.Password
- The generated password (optionally from
password policies)
.RoleName
- The name of the role that credentials are being generated for.
.DisplayName
- The display name associated with the authentication token used to make the credentials request.
.IssueTime
- The time that the lease was created. This time may be slightly earlier than the associated lease due to
where this value is calculated compared with where Vault calculates details of the lease.
Format: 2006-01-02T15:04:05Z07:00 (RFC3339)
.IssueTimeSeconds
- The unix time the lease was created. This time may
be slightly earlier than the associated lease due to where this value is calculated compared with where Vault
calculates details of the lease.
Format: Integer indicating the number of seconds elapsed since January 1, 1970.
.ExpirationTime
- The time that the lease is set to expire. This time may be slightly earlier than the associated
lease due to where this value is calculated compared with where Vault calculates details of the lease.
Format: 2006-01-02T15:04:05Z07:00 (RFC3339)
.ExpirationTimeSeconds
- The unix time the lease is set to expire. This
time may be slightly earlier than the associated lease due to where this value is calculated compared with where Vault
calculates details of the lease.
Format: Integer indicating the number of seconds elapsed since January 1, 1970.
Username template fields
The following parameters are available within the username template:
Important note: If any of the following fields include dashes or underscores, they will not be removed/changed unless explicitly done so within the username template. For instance:
If RoleName
is test-role
and the username_template
is v_{{.RoleName}}_{{unix_time}}
, the result of this template
may be: v_test-role_1234567890
. Note the -
(dash) in the test-role
. If the LDAP system Vault is managing
restricts usernames/DNs to not allow for dashes (or other characters), the template must explicitly modify/remove those
characters. In this example, the template can be changed to v_{{.RoleName | replace "-" "_"}}
to replace
the dashes with underscores. See Template Functions for more functions available.
.RoleName
- The name of the role the credentials are being generated from.
.DisplayName
- The display name associated with the user making the request against Value.
Template functions
Both the LDIF templates and the username template use the Go template language
so all functions and capabilities from that language are
supported including functions such as printf
.
In addition to the functions available through the template language, the following custom functions are also available:
random
- Generates a random string from lowercase letters, uppercase letters, and numbers. Must include a
number indicating how many characters to generate.
Example: {{random 20}}
generates 20 random characters
truncate
- truncates the previous value to the provided number of characters.
Example: {{.FieldName | truncate 10}}
truncate_sha256
- Truncates the previous value to the provided number of characters. The last 8 characters of the
truncated value will be the first 8 characters of the SHA256 hash of the truncated characters.
This can aid in identifying values (such as the role & display names) if they need to be truncated to a particular length, particularly if the value has common prefixes. An example of this is having many roles with a common prefix in the name of the role, but the role name is truncated such that only the prefix is shown. This function will keep the non-prefix part of the role name in the username which will aid in identification while also keeping uniqueness.
Example:
v_{{.RoleName | truncate_sha256 15}}_{{unix_time}}
.
If two roles exist for this template, myreallylongprefix-foobar
and myreallylongprefix-bazqux
, the username for the first role
would be v_myrealle6da86ec_1234567890
and the username for the second role would be v_myrealld0420a55_1234567890
.
uppercase
- Uppercases the provided value.
Example: {{.FieldName | uppercase}}
lowercase
- Lowercases the provided value.
Example: {{.FieldName | lowercase}}
replace
- Find/replace on the provided value.
Example: {{.FieldName | replace "-" "_"}}
sha256
- SHA256 hashes the provided value.
Example: {{.FieldName | sha256}}
base64
- Base64 encodes the provided value.
Example: {{.FieldName | base64}}
unix_time
- The current unix timestamp (number of seconds since Jan 1 1970).
Example: {{unix_time}}
unix_time_millis
- The current unix timestamp in milliseconds.
Example: {{unix_time_millis}}
timestamp
- The current time. Must provide a formatting string based on Go’s time package.
Example: {{timestamp "2006-01-02T15:04:05Z"}}
uuid
- Generates a random UUID.
Example: {{uuid}}
LDIF template functions
Additionally, the LDIF templates include an additional function to facilitate Active Directory password handling. The username template cannot use this function.
utf16le
- Encodes the provided value into UTF16-LE.
Example: {{.FieldName | utf16le}}