docs/ldap: rename openldap secrets to ldap secrets (#17433)

This commit is contained in:
Austin Gebauer
2022-10-05 13:16:26 -07:00
committed by GitHub
parent 85edc2bcc2
commit 96e04666d6
9 changed files with 92 additions and 77 deletions

View File

@@ -1,18 +1,18 @@
--- ---
layout: api layout: api
page_title: OpenLDAP - Secrets Engines - HTTP API page_title: LDAP - Secrets Engines - HTTP API
description: This is the API documentation for the Vault OpenLDAP secrets engine. description: This is the API documentation for the Vault LDAP secrets engine.
--- ---
# OpenLDAP Secrets Engine (API) # LDAP Secrets Engine (API)
@include 'x509-sha1-deprecation.mdx' @include 'x509-sha1-deprecation.mdx'
This is the API documentation for the Vault OpenLDAP secrets engine. For general This is the API documentation for the Vault LDAP secrets engine. For general
information about the usage and operation of the OpenLDAP secrets engine, information about the usage and operation of the LDAP secrets engine,
please see [these docs](/docs/secrets/openldap). please see the [LDAP secrets engine docs](/docs/secrets/ldap).
This documentation assumes the OpenLDAP secrets engine is enabled at the `/openldap` path This documentation assumes the LDAP secrets engine is enabled at the `/ldap` path
in Vault. Since it is possible to mount secrets engines at any path, please in Vault. Since it is possible to mount secrets engines at any path, please
update your API calls accordingly. update your API calls accordingly.
@@ -20,19 +20,19 @@ update your API calls accordingly.
| Method | Path | | Method | Path |
| :------- | :----------------- | | :------- | :----------------- |
| `POST` | `/openldap/config` | | `POST` | `/ldap/config` |
| `GET` | `/openldap/config` | | `GET` | `/ldap/config` |
| `DELETE` | `/openldap/config` | | `DELETE` | `/ldap/config` |
This endpoint configures the OpenLDAP secret engine to managed user entries. This endpoint configures the LDAP secret engine to managed user entries.
Note: the OpenLDAP entry used by `config` should have the necessary privileges -> **Note**: The LDAP entry used by `config` should have the necessary privileges
to search and change entry passwords in OpenLDAP. to search and change entry passwords in LDAP.
### Parameters ### Parameters
- `binddn` `(string: <required>)` - Distinguished name (DN) of object to bind for managing user entries.<br /> - `binddn` `(string: <required>)` - Distinguished name (DN) of object to bind for managing user entries.
**Example:** `cn=vault,ou=Users,dc=hashicorp,dc=com` For example, `cn=vault,ou=Users,dc=hashicorp,dc=com`.
- `bindpass` `(string: <required>)` - Password to use along with `binddn` for managing user entries. - `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`, - `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:636`. This can also be a comma-delineated list of URLs, e.g.
@@ -40,18 +40,18 @@ to search and change entry passwords in OpenLDAP.
there are errors during the connection process.`. there are errors during the connection process.`.
- `password_policy` `(string: <optional>)` - The name of the [password policy](/docs/concepts/password-policies) - `password_policy` `(string: <optional>)` - 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. 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. - `schema` `(string: "openldap")` - The LDAP schema to use when storing entry passwords.
Valid schemas include:`openldap`, `racf` and `ad`. Valid schemas include `openldap`, `ad`, and `racf`.
- `request_timeout` `(integer: 90, string: "90s" <optional>)` - Timeout, in seconds, for the connection when - `request_timeout` `(integer: 90, string: "90s" <optional>)` - Timeout, in seconds, for the connection when
making requests against the server before returning back an error. making requests against the server before returning back an error.
- `starttls` `(bool: <optional>)` - If true, issues a `StartTLS` command after establishing an unencrypted connection. - `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, - `insecure_tls` `(bool: <optional>)` - If true, skips LDAP server SSL certificate verification - insecure,
use with caution! use with caution!
- `certificate` - `(string: <optional>)` - CA certificate to use when verifying LDAP server certificate, must be - `certificate` `(string: <optional>)` - CA certificate to use when verifying LDAP server certificate, must be
x509 PEM encoded. x509 PEM encoded.
- `client_tls_cert` - `(string: <optional>)` - Client certificate to provide to the LDAP server, must be x509 - `client_tls_cert` `(string: <optional>)` - Client certificate to provide to the LDAP server, must be x509
PEM encoded. PEM encoded.
- `client_tls_key` - `(string: <optional>)` - Client key 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**: **Deprecated Parameters**:
@@ -71,7 +71,7 @@ configuration if both are specified.
The policy will need to exist prior to passwords needing to be generated by this engine, but does not need to exist 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. prior to saving the configuration.
See [OpenLDAP docs](/docs/secrets/openldap) for additional information. See [LDAP secrets engine docs](/docs/secrets/ldap) for additional information.
### Sample Payload ### Sample Payload
@@ -90,7 +90,7 @@ $ curl \
--header "X-Vault-Token: ..." \ --header "X-Vault-Token: ..." \
--request POST \ --request POST \
--data @payload.json \ --data @payload.json \
http://127.0.0.1:8200/v1/openldap/config http://127.0.0.1:8200/v1/ldap/config
``` ```
### Sample GET Request ### Sample GET Request
@@ -99,7 +99,7 @@ $ curl \
$ curl \ $ curl \
--header "X-Vault-Token: ..." \ --header "X-Vault-Token: ..." \
--request GET \ --request GET \
https://127.0.0.1:8200/v1/openldap/config https://127.0.0.1:8200/v1/ldap/config
``` ```
### Sample Response ### Sample Response
@@ -123,11 +123,12 @@ $ curl \
## Rotate Root Password ## 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. The `rotate-root` endpoint offers password rotation for the `binddn` entry used to manage LDAP.
This generated password will only be known to Vault and will not be retrievable once rotated.
| Method | Path | | Method | Path |
| :----- | :---------------------- | | :----- | :---------------------- |
| `POST` | `/openldap/rotate-root` | | `POST` | `/ldap/rotate-root` |
### Sample Request ### Sample Request
@@ -135,12 +136,12 @@ The `rotate-root` endpoint offers password rotation for the `binddn` entry used
$ curl \ $ curl \
--header "X-Vault-Token: ..." \ --header "X-Vault-Token: ..." \
--request POST \ --request POST \
http://127.0.0.1:8200/v1/openldap/rotate-root http://127.0.0.1:8200/v1/ldap/rotate-root
``` ```
## Static Roles ## Static Roles
The `static-role` endpoint configures Vault to manage the passwords of existing individual OpenLDAP entries. The `static-role` endpoint configures Vault to manage the passwords of existing individual LDAP entries.
### Parameters ### Parameters
@@ -155,10 +156,10 @@ The `static-role` endpoint configures Vault to manage the passwords of existing
| Method | Path | | Method | Path |
| :------- | :--------------------------------- | | :------- | :--------------------------------- |
| `GET` | `/openldap/static-role` | | `GET` | `/ldap/static-role` |
| `GET` | `/openldap/static-role/:role_name` | | `GET` | `/ldap/static-role/:role_name` |
| `POST` | `/openldap/static-role/:role_name` | | `POST` | `/ldap/static-role/:role_name` |
| `DELETE` | `/openldap/static-role/:role_name` | | `DELETE` | `/ldap/static-role/:role_name` |
### Sample Payload ### Sample Payload
@@ -177,7 +178,7 @@ $ curl \
--header "X-Vault-Token: ..." \ --header "X-Vault-Token: ..." \
--request POST \ --request POST \
--data @payload.json \ --data @payload.json \
http://127.0.0.1:8200/v1/openldap/static-role/hashicorp http://127.0.0.1:8200/v1/ldap/static-role/hashicorp
``` ```
### Sample GET Request ### Sample GET Request
@@ -186,7 +187,7 @@ $ curl \
$ curl \ $ curl \
--header "X-Vault-Token: ..." \ --header "X-Vault-Token: ..." \
--request GET \ --request GET \
http://127.0.0.1:8200/v1/openldap/static-role/hashicorp http://127.0.0.1:8200/v1/ldap/static-role/hashicorp
``` ```
### Sample GET Response ### Sample GET Response
@@ -214,7 +215,7 @@ The `static-cred` endpoint offers the credential information for a given static-
| Method | Path | | Method | Path |
| :----- | :--------------------------------- | | :----- | :--------------------------------- |
| `GET` | `/openldap/static-cred/:role_name` | | `GET` | `/ldap/static-cred/:role_name` |
#### Sample Get Request #### Sample Get Request
@@ -222,7 +223,7 @@ The `static-cred` endpoint offers the credential information for a given static-
$ curl \ $ curl \
--header "X-Vault-Token: ..." \ --header "X-Vault-Token: ..." \
--request GET \ --request GET \
http://127.0.0.1:8200/v1/openldap/static-cred/hashicorp http://127.0.0.1:8200/v1/ldap/static-cred/hashicorp
``` ```
#### Sample Get Response #### Sample Get Response
@@ -244,7 +245,7 @@ The `rotate-role` endpoint rotates the password of an existing static role.
| Method | Path | | Method | Path |
| :----- | :--------------------------------- | | :----- | :--------------------------------- |
| `POST` | `/openldap/rotate-role/:role_name` | | `POST` | `/ldap/rotate-role/:role_name` |
### Sample Request ### Sample Request
@@ -252,13 +253,13 @@ The `rotate-role` endpoint rotates the password of an existing static role.
$ curl \ $ curl \
--header "X-Vault-Token: ..." \ --header "X-Vault-Token: ..." \
--request POST \ --request POST \
http://127.0.0.1:8200/v1/openldap/rotate-role/:role_name http://127.0.0.1:8200/v1/ldap/rotate-role/:role_name
``` ```
## Dynamic Roles ## Dynamic Roles
Create or update a dynamic role configuration. This provides instructions to Vault on how to create an Create or update a dynamic role configuration. This provides instructions to Vault on how to create an
OpenLDAP domain user account. LDAP domain user account.
### Create/Delete Dynamic Role Configuration ### Create/Delete Dynamic Role Configuration
@@ -266,12 +267,12 @@ OpenLDAP domain user account.
| Method | Path | | Method | Path |
| :------- | :-------------------------- | | :------- | :-------------------------- |
| `POST` | `/openldap/role/:role_name` | | `POST` | `/ldap/role/:role_name` |
| `DELETE` | `/openldap/role/:role_name` | | `DELETE` | `/ldap/role/:role_name` |
The `POST` endpoint allows for partial updates of existing roles. If a role exists and a `POST` request is made 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 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=""` empty string as the value. Example: `vault write ldap/role/myrole default_ttl=""`
`role_name` `(string, required)` - The name of the dynamic role. `role_name` `(string, required)` - The name of the dynamic role.
@@ -379,14 +380,14 @@ $ curl \
--header "X-Vault-Token: ..." \ --header "X-Vault-Token: ..." \
--request POST \ --request POST \
--data @payload.json \ --data @payload.json \
http://127.0.0.1:8200/v1/openldap/role/dynamic-role http://127.0.0.1:8200/v1/ldap/role/dynamic-role
``` ```
### Read Dynamic Role Configuration ### Read Dynamic Role Configuration
| Method | Path | | Method | Path |
| ------ | --------------------------- | | ------ | --------------------------- |
| `GET` | `/openldap/role/:role_name` | | `GET` | `/ldap/role/:role_name` |
Retrieves a dynamic role's configuration. Retrieves a dynamic role's configuration.

View File

@@ -86,7 +86,7 @@ Here are the use cases that may still use certificates with SHA-1:
- [Consul Secrets Engine](/docs/secrets/consul) - [Consul Secrets Engine](/docs/secrets/consul)
- [Kubernetes Secrets Engine](/docs/secrets/kubernetes) - [Kubernetes Secrets Engine](/docs/secrets/kubernetes)
- [Nomad Secrets Engine](/docs/secrets/nomad) - [Nomad Secrets Engine](/docs/secrets/nomad)
- [OpenLDAP Secrets Engine](/docs/secrets/openldap) - [LDAP Secrets Engine](/docs/secrets/ldap)
- [PKI Secrets Engine](/docs/secrets/pki/) - [PKI Secrets Engine](/docs/secrets/pki/)
### Q: What are the phases of deprecation? ### Q: What are the phases of deprecation?

View File

@@ -86,7 +86,7 @@ exists within the Vault repository, the plugin can be built as instructed in
- [Kubernetes](https://github.com/hashicorp/vault-plugin-secrets-kubernetes) - [Kubernetes](https://github.com/hashicorp/vault-plugin-secrets-kubernetes)
- [MongoDB Atlas](https://github.com/hashicorp/vault-plugin-secrets-mongodbatlas) - [MongoDB Atlas](https://github.com/hashicorp/vault-plugin-secrets-mongodbatlas)
- [Nomad](/api-docs/secret/nomad) - [Nomad](/api-docs/secret/nomad)
- [OpenLDAP](https://github.com/hashicorp/vault-plugin-secrets-openldap) - [LDAP](https://github.com/hashicorp/vault-plugin-secrets-openldap)
- [PKI](/api-docs/secret/pki) - [PKI](/api-docs/secret/pki)
- [RabbitMQ](/api-docs/secret/rabbitmq) - [RabbitMQ](/api-docs/secret/rabbitmq)
- [SSH](/api-docs/secret/ssh) - [SSH](/api-docs/secret/ssh)

View File

@@ -2,7 +2,7 @@
layout: docs layout: docs
page_title: IBM Db2 - Database - Credentials page_title: IBM Db2 - Database - Credentials
description: |- description: |-
Manage credentials for IBM Db2 using Vault's OpenLDAP secrets engine. Manage credentials for IBM Db2 using Vault's LDAP secrets engine.
--- ---
# IBM Db2 # IBM Db2
@@ -19,7 +19,7 @@ for Lightweight Directory Access Protocol (LDAP). This enables the Db2 database
authenticate users and obtain group membership defined in an LDAP directory, removing the authenticate users and obtain group membership defined in an LDAP directory, removing the
requirement that users and groups be defined to the operating system. requirement that users and groups be defined to the operating system.
Vault's [OpenLDAP secrets engine](/docs/secrets/openldap) can be used to manage the lifecycle Vault's [LDAP secrets engine](/docs/secrets/ldap) can be used to manage the lifecycle
of credentials for Db2 environments that have been configured to delegate user authentication of credentials for Db2 environments that have been configured to delegate user authentication
and group membership to an LDAP server. and group membership to an LDAP server.

View File

@@ -1,35 +1,35 @@
--- ---
layout: docs layout: docs
page_title: OpenLDAP - Secrets Engine page_title: LDAP - Secrets Engine
description: >- description: >-
The OpenLDAP secret engine manages OpenLDAP entry passwords. The LDAP secret engine manages LDAP entry passwords.
--- ---
# OpenLDAP Secrets Engine # LDAP Secrets Engine
@include 'x509-sha1-deprecation.mdx' @include 'x509-sha1-deprecation.mdx'
The OpenLDAP secret engine allows management of LDAP entry passwords as well as dynamic creation of credentials. The LDAP secret engine allows management of LDAP entry passwords as well as dynamic creation of credentials.
This engine supports interacting with Active Directory which is compatible with LDAP v3. This engine supports interacting with Active Directory which is compatible with LDAP v3.
This plugin currently supports LDAP v3. This plugin currently supports LDAP v3.
## Quick Setup ## Quick Setup
1. Enable the OpenLDAP secret engine: 1. Enable the LDAP secret engine:
```sh ```sh
$ vault secrets enable openldap $ vault secrets enable ldap
``` ```
By default, the secrets engine will mount at the name of the engine. To By default, the secrets engine will mount at the name of the engine. To
enable the secrets engine at a different path, use the `-path` argument. enable the secrets engine at a different path, use the `-path` argument.
2. Configure the credentials that Vault uses to communicate with OpenLDAP 2. Configure the credentials that Vault uses to communicate with LDAP
to generate passwords: to generate passwords:
```sh ```sh
$ vault write openldap/config \ $ vault write ldap/config \
binddn=$USERNAME \ binddn=$USERNAME \
bindpass=$PASSWORD \ bindpass=$PASSWORD \
url=ldaps://138.91.247.105 url=ldaps://138.91.247.105
@@ -40,7 +40,7 @@ This plugin currently supports LDAP v3.
3. Rotate the root password so only Vault knows the credentials: 3. Rotate the root password so only Vault knows the credentials:
```sh ```sh
$ vault write -f openldap/rotate-root $ vault write -f ldap/rotate-root
``` ```
Note: it's not possible to retrieve the generated password once rotated by Vault. Note: it's not possible to retrieve the generated password once rotated by Vault.
@@ -65,11 +65,11 @@ rule "charset" {
### Setup ### Setup
1. Configure a static role that maps a name in Vault to an entry in OpenLDAP. 1. Configure a static role that maps a name in Vault to an entry in LDAP.
Password rotation settings will be managed by this role. Password rotation settings will be managed by this role.
```sh ```sh
$ vault write openldap/static-role/hashicorp \ $ vault write ldap/static-role/hashicorp \
dn='uid=hashicorp,ou=users,dc=hashicorp,dc=com' \ dn='uid=hashicorp,ou=users,dc=hashicorp,dc=com' \
username='hashicorp' \ username='hashicorp' \
rotation_period="24h" rotation_period="24h"
@@ -78,12 +78,12 @@ rule "charset" {
2. Request credentials for the "hashicorp" role: 2. Request credentials for the "hashicorp" role:
```sh ```sh
$ vault read openldap/static-cred/hashicorp $ vault read ldap/static-cred/hashicorp
``` ```
### LDAP Password Policy ### LDAP Password Policy
The OpenLDAP secret engine does not hash or encrypt passwords prior to modifying The LDAP secret engine does not hash or encrypt passwords prior to modifying
values in LDAP. This behavior can cause plaintext passwords to be stored in LDAP. values in LDAP. This behavior can cause plaintext passwords to be stored in LDAP.
To avoid having plaintext passwords stored, the LDAP server should be configured To avoid having plaintext passwords stored, the LDAP server should be configured
@@ -112,12 +112,15 @@ olcPPolicyUseLockout: TRUE
### Schema ### Schema
The OpenLDAP Secret Engine supports three different schemas: `openldap` (default), The LDAP Secret Engine supports three different schemas:
`racf` and `ad`.
- `openldap` (default)
- `racf`
- `ad`
#### OpenLDAP #### OpenLDAP
By default the OpenLDAP Secret Engine assumes the entry password is stored in `userPassword`. By default, the LDAP Secret Engine assumes the entry password is stored in `userPassword`.
There are many object classes that provide `userPassword` including for example: There are many object classes that provide `userPassword` including for example:
- `organization` - `organization`
@@ -136,7 +139,7 @@ Generated passwords must be 8 characters or less to support RACF. The length of
password can be configured using a [password policy](/docs/concepts/password-policies): password can be configured using a [password policy](/docs/concepts/password-policies):
```bash ```bash
$ vault write openldap/config \ $ vault write ldap/config \
binddn=$USERNAME \ binddn=$USERNAME \
bindpass=$PASSWORD \ bindpass=$PASSWORD \
url=ldaps://138.91.247.105 \ url=ldaps://138.91.247.105 \
@@ -150,7 +153,7 @@ For managing Active Directory instances, the secret engine must be configured to
schema `ad`. schema `ad`.
```bash ```bash
$ vault write openldap/config \ $ vault write ldap/config \
binddn=$USERNAME \ binddn=$USERNAME \
bindpass=$PASSWORD \ bindpass=$PASSWORD \
url=ldaps://138.91.247.105 \ url=ldaps://138.91.247.105 \
@@ -161,8 +164,8 @@ $ vault write openldap/config \
Passwords can be managed in two ways: Passwords can be managed in two ways:
- automatic time based rotation, and - automatic time based rotation
- manual rotation. - manual rotation
### Auto Password Rotation ### Auto Password Rotation
@@ -191,7 +194,7 @@ rotated prior to deleting the role or revoking access to the static role.
Dynamic credentials can be configured by calling the `/role/:role_name` endpoint: Dynamic credentials can be configured by calling the `/role/:role_name` endpoint:
```bash ```bash
$ vault write openldap/role/dynamic-role \ $ vault write ldap/role/dynamic-role \
creation_ldif=@/path/to/creation.ldif \ creation_ldif=@/path/to/creation.ldif \
deletion_ldif=@/path/to/deletion.ldif \ deletion_ldif=@/path/to/deletion.ldif \
rollback_ldif=@/path/to/rollback.ldif \ rollback_ldif=@/path/to/rollback.ldif \
@@ -205,10 +208,10 @@ executed if the creation fails for any reason. This ensures any entities are rem
To generate credentials: To generate credentials:
```bash ```bash
$ vault read openldap/creds/dynamic-role $ vault read ldap/creds/dynamic-role
Key Value Key Value
--- ----- --- -----
lease_id openldap/creds/dynamic-role/HFgd6uKaDomVMvJpYbn9q4q5 lease_id ldap/creds/dynamic-role/HFgd6uKaDomVMvJpYbn9q4q5
lease_duration 1h lease_duration 1h
lease_renewable true lease_renewable true
distinguished_names [cn=v_token_dynamic-role_FfH2i1c4dO_1611952635,ou=users,dc=learn,dc=example] distinguished_names [cn=v_token_dynamic-role_FfH2i1c4dO_1611952635,ou=users,dc=learn,dc=example]
@@ -301,5 +304,5 @@ member: CN={{.Username}},OU=HashiVault,DC=adtesting,DC=lab
## API ## API
The OpenLDAP secrets engine has a full HTTP API. Please see the [OpenLDAP secrets engine API docs](/api-docs/secret/openldap) The LDAP secrets engine has a full HTTP API. Please see the [LDAP secrets engine API docs](/api-docs/secret/ldap)
for more details. for more details.

View File

@@ -88,6 +88,7 @@ consul
gcp gcp
gcpkms gcpkms
kv kv
ldap
mongodb mongodb
mongodbatlas mongodbatlas
mssql mssql

View File

@@ -254,8 +254,8 @@
"path": "secret/nomad" "path": "secret/nomad"
}, },
{ {
"title": "OpenLDAP", "title": "LDAP",
"path": "secret/openldap" "path": "secret/ldap"
}, },
{ {
"title": "PKI", "title": "PKI",

View File

@@ -1128,8 +1128,8 @@
"path": "secrets/nomad" "path": "secrets/nomad"
}, },
{ {
"title": "OpenLDAP", "title": "LDAP",
"path": "secrets/openldap" "path": "secrets/ldap"
}, },
{ {
"title": "PKI (Certificates)", "title": "PKI (Certificates)",

View File

@@ -345,6 +345,16 @@ module.exports = [
destination: '/docs/secrets/databases/postgresql', destination: '/docs/secrets/databases/postgresql',
permanent: true, permanent: true,
}, },
{
source: '/docs/secrets/openldap',
destination: '/docs/secrets/ldap',
permanent: true,
},
{
source: '/api-docs/secret/openldap',
destination: '/api-docs/secret/ldap',
permanent: true,
},
{ {
source: '/guides/authentication', source: '/guides/authentication',
destination: '/guides/identity/authentication', destination: '/guides/identity/authentication',