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

Jump to bottom

docs: ldap secrets hierarchical paths #27203

Merged
merged 4 commits into from
May 24, 2024
Merged

docs: ldap secrets hierarchical paths #27203

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
aef3862
docs: ldap secrets hierarchical paths
fairclothjm May 23, 2024
9e01e50
changelog
fairclothjm May 23, 2024
e90e637
Apply suggestions from code review
fairclothjm May 23, 2024
1cc5075
role_name => set_name
fairclothjm May 23, 2024
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
116 changes: 82 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>)` – Specifies the name of the role. This is
part of the request URL. The value can contain an arbitrary number of forward
slashes to define a [hierarchical path](/vault/docs/secrets/ldap#hierarchical-paths).
fairclothjm marked this conversation as resolved.
Show resolved Hide resolved
- `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>)` – Specifies the name of the role. This is
part of the request URL.
fairclothjm marked this conversation as resolved.
Show resolved Hide resolved

#### 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>)` – Specifies the name of the role. This is
part of the request URL.
fairclothjm marked this conversation as resolved.
Show resolved Hide resolved

### 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>)` – Specifies the name of the role to
create. This is part of the request URL. The value can contain an arbitrary
number of forward slashes to define a [hierarchical path](/vault/docs/secrets/ldap#hierarchical-paths).
fairclothjm marked this conversation as resolved.
Show resolved Hide resolved
- `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
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This was moved to be grouped with the other /ldap/role/:role_name endpoints since that is more standard practice in the Vault docs.


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>)` – Specifies the name of the role to
create. This is part of the request URL.
fairclothjm marked this conversation as resolved.
Show resolved Hide resolved

#### 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,9 @@ 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)` - The name of the set of service accounts.
This is part of the request URL. The value can contain an arbitrary number of
forward slashes to define a [hierarchical path](/vault/docs/secrets/ldap#hierarchical-paths).
fairclothjm marked this conversation as resolved.
Show resolved Hide resolved
- `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 +650,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.
Performing a `LIST` on the `/ldap/library` endpoint will list the top-level
names of all sets of service accounts Vault contains. See LDAP secrets engine
[hierarchical paths](/vault/docs/secrets/ldap#hierarchical-paths) for more
information on path-based names.
fairclothjm marked this conversation as resolved.
Show resolved Hide resolved

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

Performing a `LIST` on the `/ldap/library/:set_name` endpoint will list the
names of all sets of service accounts Vault contains at that path. See LDAP
secrets engine [hierarchical paths](/vault/docs/secrets/ldap#hierarchical-paths)
for more information on path-based names.
fairclothjm marked this conversation as resolved.
Show resolved Hide resolved

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 +702,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)` - The name of the set of service accounts.
This is part of the request URL. The value can contain an arbitrary number of
forward slashes to define a [hierarchical path](/vault/docs/secrets/ldap#hierarchical-paths).
fairclothjm marked this conversation as resolved.
Show resolved Hide resolved

### Sample GET request

```shell-session
Expand Down Expand Up @@ -709,7 +753,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)` - The name of the set of service accounts.
This is part of the request URL. The value can contain an arbitrary number of
forward slashes to define a [hierarchical path](/vault/docs/secrets/ldap#hierarchical-paths).
fairclothjm marked this conversation as resolved.
Show resolved Hide resolved
- `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 +817,9 @@ in _by this particular call_.

### Parameters

- `name` `(string: "", required)` - The name of the set of service accounts.
- `set_name` `(string: "", required)` - The name of the set of service accounts.
This is part of the request URL. The value can contain an arbitrary number of
forward slashes to define a [hierarchical path](/vault/docs/secrets/ldap#hierarchical-paths).
fairclothjm marked this conversation as resolved.
Show resolved Hide resolved
- `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 allows you to define role and set names that contain an
arbitrary number of forward slashes. A name with forward slashes will define a
hierarchical path structure. For example, you can configure two static roles
with the names `org/secure` and `org/platform/dev`:
fairclothjm marked this conversation as resolved.
Show resolved Hide resolved

```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
```

A name with a hierarchical path allows you to perform LIST operations to query
the available roles at a specific path with arbitrary depth. A name that ends
in the forward slash indicates sub-paths reside under the given path. For
example, continuing from the previous example, we can list all direct children
under the `org/` path:
fairclothjm marked this conversation as resolved.
Show resolved Hide resolved

```shell-session
$ vault list ldap/static-role/org/
Keys
----
platform/
secure
```

The `platform/` key ends in a forward slash so we can list its sub-keys:
fairclothjm marked this conversation as resolved.
Show resolved Hide resolved

```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
API's. For example,
fairclothjm marked this conversation as resolved.
Show resolved Hide resolved

```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
```

Additionally, name with a hierarchical paths allows you to define policies that
map 1-1 to the LDAP secrets engine's role or set path because Vault policies
themselves are path-based. Refer to [Vault policies](/vault/docs/concepts/policies)
to learn more about Vault and Role-Based Access Control (RBAC).
fairclothjm marked this conversation as resolved.
Show resolved Hide resolved

Hierarchical path handling is available for the following APIs:
fairclothjm marked this conversation as resolved.
Show resolved Hide resolved

- [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