From 6bba760da099b37853835df141c4636deb14ed63 Mon Sep 17 00:00:00 2001 From: Austin Gebauer <34121980+austingebauer@users.noreply.github.com> Date: Wed, 5 Oct 2022 13:16:26 -0700 Subject: [PATCH] docs/ldap: rename openldap secrets to ldap secrets (#17433) --- .../secret/{openldap.mdx => ldap.mdx} | 89 ++++++++++--------- website/content/docs/deprecation/faq.mdx | 4 +- .../content/docs/plugins/plugin-portal.mdx | 2 +- .../content/docs/secrets/databases/db2.mdx | 4 +- .../docs/secrets/{openldap.mdx => ldap.mdx} | 51 ++++++----- website/content/docs/upgrading/plugins.mdx | 1 + website/data/api-docs-nav-data.json | 4 +- website/data/docs-nav-data.json | 4 +- website/redirects.js | 10 +++ 9 files changed, 92 insertions(+), 77 deletions(-) rename website/content/api-docs/secret/{openldap.mdx => ldap.mdx} (86%) rename website/content/docs/secrets/{openldap.mdx => ldap.mdx} (89%) diff --git a/website/content/api-docs/secret/openldap.mdx b/website/content/api-docs/secret/ldap.mdx similarity index 86% rename from website/content/api-docs/secret/openldap.mdx rename to website/content/api-docs/secret/ldap.mdx index dc1176365..87dac09de 100644 --- a/website/content/api-docs/secret/openldap.mdx +++ b/website/content/api-docs/secret/ldap.mdx @@ -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: )` - Distinguished name (DN) of object to bind for managing user entries.
- **Example:** `cn=vault,ou=Users,dc=hashicorp,dc=com` +- `binddn` `(string: )` - Distinguished name (DN) of object to bind for managing user entries. + For example, `cn=vault,ou=Users,dc=hashicorp,dc=com`. - `bindpass` `(string: )` - 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: )` - 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" )` - 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, +- `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 +- `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 +- `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. +- `client_tls_key` `(string: )` - 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. diff --git a/website/content/docs/deprecation/faq.mdx b/website/content/docs/deprecation/faq.mdx index a99d8f211..6296aeaf8 100644 --- a/website/content/docs/deprecation/faq.mdx +++ b/website/content/docs/deprecation/faq.mdx @@ -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. \ No newline at end of file +3. Upgrade to latest desired version. diff --git a/website/content/docs/plugins/plugin-portal.mdx b/website/content/docs/plugins/plugin-portal.mdx index ac1e13b28..c8213540c 100644 --- a/website/content/docs/plugins/plugin-portal.mdx +++ b/website/content/docs/plugins/plugin-portal.mdx @@ -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) diff --git a/website/content/docs/secrets/databases/db2.mdx b/website/content/docs/secrets/databases/db2.mdx index 125583ee9..1ada71a79 100644 --- a/website/content/docs/secrets/databases/db2.mdx +++ b/website/content/docs/secrets/databases/db2.mdx @@ -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. diff --git a/website/content/docs/secrets/openldap.mdx b/website/content/docs/secrets/ldap.mdx similarity index 89% rename from website/content/docs/secrets/openldap.mdx rename to website/content/docs/secrets/ldap.mdx index 2ecd20803..f56b38d95 100644 --- a/website/content/docs/secrets/openldap.mdx +++ b/website/content/docs/secrets/ldap.mdx @@ -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. diff --git a/website/content/docs/upgrading/plugins.mdx b/website/content/docs/upgrading/plugins.mdx index 84a41ec95..a80c63b63 100644 --- a/website/content/docs/upgrading/plugins.mdx +++ b/website/content/docs/upgrading/plugins.mdx @@ -88,6 +88,7 @@ consul gcp gcpkms kv +ldap mongodb mongodbatlas mssql diff --git a/website/data/api-docs-nav-data.json b/website/data/api-docs-nav-data.json index fe79196ee..ac926b3d9 100644 --- a/website/data/api-docs-nav-data.json +++ b/website/data/api-docs-nav-data.json @@ -254,8 +254,8 @@ "path": "secret/nomad" }, { - "title": "OpenLDAP", - "path": "secret/openldap" + "title": "LDAP", + "path": "secret/ldap" }, { "title": "PKI", diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 1d9f6bf52..cdc0ada51 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -1128,8 +1128,8 @@ "path": "secrets/nomad" }, { - "title": "OpenLDAP", - "path": "secrets/openldap" + "title": "LDAP", + "path": "secrets/ldap" }, { "title": "PKI (Certificates)", diff --git a/website/redirects.js b/website/redirects.js index bd919322c..4467bf234 100644 --- a/website/redirects.js +++ b/website/redirects.js @@ -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',