docs: ldap secrets hierarchical paths (#27203)

* docs: ldap secrets hierarchical paths * changelog * Apply suggestions from code review Co-authored-by: Sarah Chavis <[email protected]> * role_name => set_name --------- Co-authored-by: Sarah Chavis <[email protected]>
hashicorp · May 24, 2024 · f528036 · f528036
1 parent 7438d63
commit f528036
Show file tree

Hide file tree

Showing 3 changed files with 163 additions and 34 deletions.
diff --git a/changelog/27203.txt 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
@@ -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: <required>)` – 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: <required>)` - 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: <required>)` – 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: <required>)` – 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: <required>)` – 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: <required>)` – 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: <required>)` – 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
@@ -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)