From 91fce38be86e3b02bf2b30a1e9bae89a343e0b99 Mon Sep 17 00:00:00 2001 From: hc-github-team-secure-vault-core <82990506+hc-github-team-secure-vault-core@users.noreply.github.com> Date: Fri, 24 May 2024 07:18:27 -0700 Subject: [PATCH] backport of commit f528036e45d99243cb574a1ec8be944b2b8cfbe1 (#27220) Co-authored-by: John-Michael Faircloth --- changelog/27203.txt | 3 + website/content/api-docs/secret/ldap.mdx | 115 ++++++++++++++++------- website/content/docs/secrets/ldap.mdx | 79 ++++++++++++++++ 3 files changed, 163 insertions(+), 34 deletions(-) create mode 100644 changelog/27203.txt diff --git a/changelog/27203.txt b/changelog/27203.txt new file mode 100644 index 000000000000..b0dee9ee38f4 --- /dev/null +++ b/changelog/27203.txt @@ -0,0 +1,3 @@ +```release-note:feature +**LDAP Secrets engine hierarchical path support**: Hierarchical path handling is now supported for role and set APIs. +``` diff --git a/website/content/api-docs/secret/ldap.mdx b/website/content/api-docs/secret/ldap.mdx index dadb4e8f60fc..511d13194312 100644 --- a/website/content/api-docs/secret/ldap.mdx +++ b/website/content/api-docs/secret/ldap.mdx @@ -166,11 +166,15 @@ The `static-role` endpoint configures Vault to manage the passwords of existing | :------- | :--------------------------------- | | `GET` | `/ldap/static-role` | | `GET` | `/ldap/static-role/:role_name` | +| `LIST` | `/ldap/static-role/:role_name` | | `POST` | `/ldap/static-role/:role_name` | | `DELETE` | `/ldap/static-role/:role_name` | ### Parameters +- `role_name` `(string: )` – URL parameter specifying the name of the + role. Role name can contain an arbitrary number of forward slashes to define a + [hierarchical path](/vault/docs/secrets/ldap#hierarchical-paths). - `username` `(string: )` - The username of the existing LDAP entry to manage password rotation for. LDAP search for the username will be rooted at the [userdn](/vault/api-docs/secret/ldap#userdn) configuration value. The attribute to use when searching for the user can be configured @@ -245,7 +249,12 @@ The `static-cred` endpoint offers the credential information for a given static- | :----- | :--------------------------------- | | `GET` | `/ldap/static-cred/:role_name` | -#### Sample get request +### Parameters + +- `role_name` `(string: )` – URL parameter specifying the name of the + role. + +#### Sample GET request ```shell-session $ curl \ @@ -254,7 +263,7 @@ $ curl \ http://127.0.0.1:8200/v1/ldap/static-cred/hashicorp ``` -#### Sample get response +#### Sample GET response ```json { @@ -276,6 +285,11 @@ The `rotate-role` endpoint rotates the password of an existing static role. | :----- | :--------------------------------- | | `POST` | `/ldap/rotate-role/:role_name` | +### Parameters + +- `role_name` `(string: )` – URL parameter specifying the name of the + role. + ### Sample request ```shell-session @@ -296,6 +310,7 @@ Creates, updates, or deletes a dynamic role. | Method | Path | | :------- | :-------------------------- | +| `GET` | `/ldap/role/:role_name` | | `POST` | `/ldap/role/:role_name` | | `DELETE` | `/ldap/role/:role_name` | @@ -305,7 +320,9 @@ empty string as the value. Example: `vault write ldap/role/myrole default_ttl="" #### Parameters -- `role_name` `(string, required)` - The name of the dynamic role. +- `role_name` `(string: )` – URL parameter specifying the name of the + role. Role name can contain an arbitrary number of forward slashes to define a + [hierarchical path](/vault/docs/secrets/ldap#hierarchical-paths). - `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 @@ -409,29 +426,6 @@ $ curl \ http://127.0.0.1:8200/v1/ldap/role/dynamic-role ``` -### Read dynamic role configuration - -Retrieves a dynamic role's configuration. - -| Method | Path | -| ------ | --------------------------- | -| `GET` | `/ldap/role/:role_name` | - -#### Response - -`200 OK` - -```json -{ - "creation_ldif": "...", - "default_ttl": 1800, - "deletion_ldif": "...", - "max_ttl": 0, - "rollback_ldif": "...", - "username_template": "..." -} -``` - ### Templates LDIF and username templates use the [Go template syntax](https://golang.org/pkg/text/template/) to construct the @@ -567,7 +561,12 @@ The `creds` endpoint offers the credential information for a given dynamic role. | :----- | :--------------------------------- | | `GET` | `/ldap/creds/:role_name` | -#### Sample get request +### Parameters + +- `role_name` `(string: )` – URL parameter specifying the name of the + role. + +#### Sample GET request ```shell-session $ curl \ @@ -576,7 +575,7 @@ $ curl \ http://127.0.0.1:8200/v1/ldap/creds/dynamic-role ``` -#### Sample get response +#### Sample GET response ```json { @@ -595,6 +594,7 @@ The `library` endpoint configures the sets of service accounts that Vault will o | Method | Path | | :------- | :---------------------- | | `LIST` | `/ldap/library` | +| `LIST` | `/ldap/library/:set_name` | | `POST` | `/ldap/library/:set_name` | | `GET` | `/ldap/library/:set_name` | | `DELETE` | `/ldap/library/:set_name` | @@ -603,7 +603,8 @@ When adding a service account to the library, Vault verifies it already exists i ### Parameters -- `name` `(string: "", required)` - The name of the set of service accounts. +- `set_name` `(string: )` – URL parameter specifying the name of the + set. - `service_account_names` `(string: "", or list: [] required)` - The names of all the service accounts that can be checked out from this set. These service accounts must only be used by Vault, and may only be in one set. These service accounts must already exist in the LDAP directory. @@ -648,12 +649,48 @@ $ curl \ } ``` -### Sample LIST response +### Sample LIST request -Performing a `LIST` on the `/ldap/library` endpoint will list the names of all the sets of service accounts Vault contains. +Use the `/ldap/library` endpoint to list the top-level set names of service +accounts in Vault. Refer to the LDAP secrets engine +[hierarchical paths](/vault/docs/secrets/ldap#hierarchical-paths) documentation +for more information on path-based names. + +For example: + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/ldap/library +``` + +#### Sample LIST response + +```json +["accounting-team", "dev/"] +``` + +### Sample LIST request + +Use the `/ldap/library` endpoint to list the top-level set names of service +accounts in Vault at the given path. Refer to the LDAP secrets engine +[hierarchical paths](/vault/docs/secrets/ldap#hierarchical-paths) documentation +for more information on path-based names. + +For example: + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/ldap/library/dev +``` + +#### Sample LIST response ```json -["accounting-team"] +["backend", "frontend"] ``` ## Library set status check @@ -664,6 +701,12 @@ This endpoint provides the check-out status of service accounts in a library set | :----- | :----------------------------- | | `GET` | `/ldap/library/:set_name/status` | +### Parameters + +- `set_name` `(string: "", required)` - URL parameter specifying the set name of + the requested service accounts. The set name can contain an arbitrary number of + forward slashes to define a [hierarchical path](/vault/docs/secrets/ldap#hierarchical-paths). + ### Sample GET request ```shell-session @@ -709,7 +752,9 @@ Returns a `200` if a credential is available, and a `400` if no credential is av ### Parameters -- `name` `(string: "", required)` - The name of the set of service accounts. +- `set_name` `(string: "", required)` - URL parameter specifying the set name of + the requested service accounts. The set name can contain an arbitrary number of + forward slashes to define a [hierarchical path](/vault/docs/secrets/ldap#hierarchical-paths). - `ttl` `(duration: "", optional)` - The maximum amount of time a check-out lasts before Vault automatically checks it back in. Setting it to zero reflects an unlimited lending period. Defaults to the set's `ttl`. If the requested `ttl` is higher than the set's, the set's will be used. @@ -771,7 +816,9 @@ in _by this particular call_. ### Parameters -- `name` `(string: "", required)` - The name of the set of service accounts. +- `set_name` `(string: "", required)` - URL parameter specifying the set name of + the requested service accounts. The set name can contain an arbitrary number of + forward slashes to define a [hierarchical path](/vault/docs/secrets/ldap#hierarchical-paths). - `service_account_names` `(string: "", or list: [] optional)` - The names of all the service accounts to be checked in. May be omitted if only one is checked out. diff --git a/website/content/docs/secrets/ldap.mdx b/website/content/docs/secrets/ldap.mdx index c4551ff6e068..5ac9b4aa9042 100644 --- a/website/content/docs/secrets/ldap.mdx +++ b/website/content/docs/secrets/ldap.mdx @@ -462,6 +462,85 @@ olcPPolicyHashCleartext: TRUE olcPPolicyUseLockout: TRUE ``` +## Hierarchical paths + +The LDAP secrets engine lets you define role and set names that contain an +arbitrary number of forward slashes. Names with forward slashes define +hierarchical path structures. + +For example, you can configure two static roles with the names `org/secure` and `org/platform/dev`: + +```shell-session +$ vault write ldap/static-role/org/secure \ + username="user1" \ + rotation_period="1h" +Success! Data written to: ldap/static-role/org/secure + +$ vault write ldap/static-role/org/platform/dev \ + username="user2" \ + rotation_period="1h" +Success! Data written to: ldap/static-role/org/platform/dev +``` + +Names with hierarchical paths let you use the Vault API to query the available +roles at a specific path with arbitrary depth. Names that end with a forward +slash indicate that sub-paths reside under that path. + +For example, to list all direct children under the `org/` path: + +```shell-session +$ vault list ldap/static-role/org/ +Keys +---- +platform/ +secure +``` + +The `platform/` key also ends in a forward slash. To list the `platform` sub-keys: + +```shell-session +$ vault list ldap/static-role/org/platform +Keys +---- +dev +``` + +You can read and rotate credentials using the same role name and the respective +APIs. For example, + +```shell-session +$ vault read ldap/static-cred/org/platform/dev +Key Value +--- ----- +dn n/a +last_password a3sQ6OkmXKt2dtx22kAt36YLkkxLsg4RmhMZCLYCBCbvvv67ILROaOokdCaGPEAE +last_vault_rotation 2024-05-03T16:39:27.174164-05:00 +password ECf7ZoxfDxGuJEYZrzgzTffSIDI4tx5TojBR9wuEGp8bqUXbl4Kr9eAgPjmizcvg +rotation_period 5m +ttl 4m58s +username user2 +``` + +```shell-session +$ vault write -f ldap/rotate-role/org/platform/dev +``` + +Since [Vault policies](/vault/docs/concepts/policies) are also path-based, +hierarchical names also let you define policies that map 1-1 to LDAP secrets +engine roles and set paths. + +The following Vault API endpoints support hierarchical path handling: + +- [Static roles](/vault/api-docs/secret/ldap#static-roles) +- [Static role passwords](/vault/api-docs/secret/ldap#static-role-passwords) +- [Manually rotate static role password](/vault/api-docs/secret/ldap#manually-rotate-static-role-password) +- [Dynamic roles](/vault/api-docs/secret/ldap#dynamic-roles) +- [Dynamic role passwords](/vault/api-docs/secret/ldap#dynamic-role-passwords) +- [Library set management](/vault/api-docs/secret/ldap#library-set-management) +- [Library set status check](/vault/api-docs/secret/ldap#library-set-status-check) +- [Check-Out management](/vault/api-docs/secret/ldap#check-out-management) +- [Check-In management](/vault/api-docs/secret/ldap#check-in-management) + ## Tutorial Refer to the [LDAP Secrets Engine](/vault/tutorials/secrets-management/openldap)