Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Backport of docs: ldap secrets hierarchical paths into release/1.17.x #27220

Merged
merged 1 commit into from
May 24, 2024
Merged

Backport of docs: ldap secrets hierarchical paths into release/1.17.x #27220

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions changelog/27203.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 changes: 81 additions & 34 deletions website/content/api-docs/secret/ldap.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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 \
Expand All @@ -254,7 +263,7 @@ $ curl \
http://127.0.0.1:8200/v1/ldap/static-cred/hashicorp
```

#### Sample get response
#### Sample GET response

```json
{
Expand All @@ -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
Expand All @@ -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` |

Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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 \
Expand All @@ -576,7 +575,7 @@ $ curl \
http://127.0.0.1:8200/v1/ldap/creds/dynamic-role
```

#### Sample get response
#### Sample GET response

```json
{
Expand All @@ -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` |
Expand All @@ -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.
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.

Expand Down
79 changes: 79 additions & 0 deletions website/content/docs/secrets/ldap.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
Loading