mirrors/vault
1
0
Fork 0
mirror of https://github.com/hashicorp/vault.git synced 2025-08-17 20:17:00 +02:00
Code Issues Projects Releases Wiki Activity

docs: ldap secrets hierarchical paths (#27203)

Browse Source 
* docs: ldap secrets hierarchical paths

* changelog

* Apply suggestions from code review

Co-authored-by: Sarah Chavis <62406755+schavis@users.noreply.github.com>

* role_name => set_name

---------

Co-authored-by: Sarah Chavis <62406755+schavis@users.noreply.github.com>
This commit is contained in:
John-Michael Faircloth 2024-05-24 09:10:59 -05:00 committed by GitHub
parent 7438d63f81
commit f528036e45
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
3 changed files with 163 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
changelog/27203.txt Normal file
View File

@ -0,0 +1,3 @@
```release-note:feature
**LDAP Secrets engine hierarchical path support**: Hierarchical path handling is now supported for role and set APIs.
```

115
website/content/api-docs/secret/ldap.mdx
View File

@ -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"]
["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
["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.

79
website/content/docs/secrets/ldap.mdx
View File

@ -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)