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 3ad4d3af6e
commit 6bba760da0
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
9 changed files with 92 additions and 77 deletions

View File

@ -1,18 +1,18 @@
---
layout: api
page_title: OpenLDAP - Secrets Engines - HTTP API
description: This is the API documentation for the Vault OpenLDAP secrets engine.
page_title: LDAP - Secrets Engines - HTTP API
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'
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 is the API documentation for the Vault LDAP secrets engine. For general
information about the usage and operation of the LDAP secrets engine,
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
update your API calls accordingly.
@ -20,19 +20,19 @@ update your API calls accordingly.
| Method | Path |
| :------- | :----------------- |
| `POST` | `/openldap/config` |
| `GET` | `/openldap/config` |
| `DELETE` | `/openldap/config` |
| `POST` | `/ldap/config` |
| `GET` | `/ldap/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
to search and change entry passwords in OpenLDAP.
-> **Note**: The LDAP entry used by `config` should have the necessary privileges
to search and change entry passwords in LDAP.
### Parameters
- `binddn` `(string: <required>)` - Distinguished name (DN) of object to bind for managing user entries.<br />
**Example:** `cn=vault,ou=Users,dc=hashicorp,dc=com`
- `binddn` `(string: <required>)` - Distinguished name (DN) of object to bind for managing user entries.
For 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.
@ -40,18 +40,18 @@ to search and change entry passwords in OpenLDAP.
there are errors during the connection process.`.
- `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.
- `schema` `(string: "openldap")` - The OpenLDAP schema to use when storing entry passwords.
Valid schemas include:`openldap`, `racf` and `ad`.
- `schema` `(string: "openldap")` - The LDAP schema to use when storing entry passwords.
Valid schemas include `openldap`, `ad`, and `racf`.
- `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,
- `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
- `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
- `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.
- `client_tls_key` `(string: <optional>)` - Client key to provide to the LDAP server, must be x509 PEM encoded.
**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
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
@ -90,7 +90,7 @@ $ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/openldap/config
http://127.0.0.1:8200/v1/ldap/config
```
### Sample GET Request
@ -99,7 +99,7 @@ $ curl \
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
https://127.0.0.1:8200/v1/openldap/config
https://127.0.0.1:8200/v1/ldap/config
```
### Sample Response
@ -123,11 +123,12 @@ $ curl \
## 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 |
| :----- | :---------------------- |
| `POST` | `/openldap/rotate-root` |
| `POST` | `/ldap/rotate-root` |
### Sample Request
@ -135,12 +136,12 @@ The `rotate-root` endpoint offers password rotation for the `binddn` entry used
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
http://127.0.0.1:8200/v1/openldap/rotate-root
http://127.0.0.1:8200/v1/ldap/rotate-root
```
## 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
@ -155,10 +156,10 @@ The `static-role` endpoint configures Vault to manage the passwords of existing
| Method | Path |
| :------- | :--------------------------------- |
| `GET` | `/openldap/static-role` |
| `GET` | `/openldap/static-role/:role_name` |
| `POST` | `/openldap/static-role/:role_name` |
| `DELETE` | `/openldap/static-role/:role_name` |
| `GET` | `/ldap/static-role` |
| `GET` | `/ldap/static-role/:role_name` |
| `POST` | `/ldap/static-role/:role_name` |
| `DELETE` | `/ldap/static-role/:role_name` |
### Sample Payload
@ -177,7 +178,7 @@ $ curl \
--header "X-Vault-Token: ..." \
--request POST \
--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
@ -186,7 +187,7 @@ $ curl \
$ curl \
--header "X-Vault-Token: ..." \
--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
@ -214,7 +215,7 @@ The `static-cred` endpoint offers the credential information for a given static-
| Method | Path |
| :----- | :--------------------------------- |
| `GET` | `/openldap/static-cred/:role_name` |
| `GET` | `/ldap/static-cred/:role_name` |
#### Sample Get Request
@ -222,7 +223,7 @@ The `static-cred` endpoint offers the credential information for a given static-
$ curl \
--header "X-Vault-Token: ..." \
--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
@ -244,7 +245,7 @@ The `rotate-role` endpoint rotates the password of an existing static role.
| Method | Path |
| :----- | :--------------------------------- |
| `POST` | `/openldap/rotate-role/:role_name` |
| `POST` | `/ldap/rotate-role/:role_name` |
### Sample Request
@ -252,13 +253,13 @@ The `rotate-role` endpoint rotates the password of an existing static role.
$ curl \
--header "X-Vault-Token: ..." \
--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
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
@ -266,12 +267,12 @@ OpenLDAP domain user account.
| Method | Path |
| :------- | :-------------------------- |
| `POST` | `/openldap/role/:role_name` |
| `DELETE` | `/openldap/role/:role_name` |
| `POST` | `/ldap/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
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.
@ -379,14 +380,14 @@ $ curl \
--header "X-Vault-Token: ..." \
--request POST \
--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
| Method | Path |
| ------ | --------------------------- |
| `GET` | `/openldap/role/:role_name` |
| `GET` | `/ldap/role/:role_name` |
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)
- [Kubernetes Secrets Engine](/docs/secrets/kubernetes)
- [Nomad Secrets Engine](/docs/secrets/nomad)
- [OpenLDAP Secrets Engine](/docs/secrets/openldap)
- [LDAP Secrets Engine](/docs/secrets/ldap)
- [PKI Secrets Engine](/docs/secrets/pki/)
### Q: What are the phases of deprecation?
@ -141,4 +141,4 @@ In order to successfully upgrade, use of the `Removed` feature must be discontin
2. Replace any `Removed` or `Pending Removal` feature with the [preferred alternative feature](#q-what-should-i-do-if-i-use-mount-filters-appid-or-any-of-the-standalone-db-engines).
3. Upgrade to latest desired version.
3. Upgrade to latest desired version.

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)
- [MongoDB Atlas](https://github.com/hashicorp/vault-plugin-secrets-mongodbatlas)
- [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)
- [RabbitMQ](/api-docs/secret/rabbitmq)
- [SSH](/api-docs/secret/ssh)

View File

@ -2,7 +2,7 @@
layout: docs
page_title: IBM Db2 - Database - Credentials
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
@ -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
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
and group membership to an LDAP server.

View File

@ -1,35 +1,35 @@
---
layout: docs
page_title: OpenLDAP - Secrets Engine
page_title: LDAP - Secrets Engine
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'
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 plugin currently supports LDAP v3.
## Quick Setup
1. Enable the OpenLDAP secret engine:
1. Enable the LDAP secret engine:
```sh
$ vault secrets enable openldap
$ vault secrets enable ldap
```
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.
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:
```sh
$ vault write openldap/config \
$ vault write ldap/config \
binddn=$USERNAME \
bindpass=$PASSWORD \
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:
```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.
@ -65,11 +65,11 @@ rule "charset" {
### 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.
```sh
$ vault write openldap/static-role/hashicorp \
$ vault write ldap/static-role/hashicorp \
dn='uid=hashicorp,ou=users,dc=hashicorp,dc=com' \
username='hashicorp' \
rotation_period="24h"
@ -78,12 +78,12 @@ rule "charset" {
2. Request credentials for the "hashicorp" role:
```sh
$ vault read openldap/static-cred/hashicorp
$ vault read ldap/static-cred/hashicorp
```
### 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.
To avoid having plaintext passwords stored, the LDAP server should be configured
@ -112,12 +112,15 @@ olcPPolicyUseLockout: TRUE
### Schema
The OpenLDAP Secret Engine supports three different schemas: `openldap` (default),
`racf` and `ad`.
The LDAP Secret Engine supports three different schemas:
- `openldap` (default)
- `racf`
- `ad`
#### 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:
- `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):
```bash
$ vault write openldap/config \
$ vault write ldap/config \
binddn=$USERNAME \
bindpass=$PASSWORD \
url=ldaps://138.91.247.105 \
@ -150,7 +153,7 @@ For managing Active Directory instances, the secret engine must be configured to
schema `ad`.
```bash
$ vault write openldap/config \
$ vault write ldap/config \
binddn=$USERNAME \
bindpass=$PASSWORD \
url=ldaps://138.91.247.105 \
@ -161,8 +164,8 @@ $ vault write openldap/config \
Passwords can be managed in two ways:
- automatic time based rotation, and
- manual rotation.
- automatic time based rotation
- manual 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:
```bash
$ vault write openldap/role/dynamic-role \
$ vault write ldap/role/dynamic-role \
creation_ldif=@/path/to/creation.ldif \
deletion_ldif=@/path/to/deletion.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:
```bash
$ vault read openldap/creds/dynamic-role
$ vault read ldap/creds/dynamic-role
Key Value
--- -----
lease_id openldap/creds/dynamic-role/HFgd6uKaDomVMvJpYbn9q4q5
lease_id ldap/creds/dynamic-role/HFgd6uKaDomVMvJpYbn9q4q5
lease_duration 1h
lease_renewable true
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
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.

View File

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

View File

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

View File

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

View File

@ -345,6 +345,16 @@ module.exports = [
destination: '/docs/secrets/databases/postgresql',
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',
destination: '/guides/identity/authentication',