luxolus
/
open-vault
2
0
Fork 0
Code Issues 1 Pull Requests Releases Activity

secrets/ldap: updates API documentation (#17448) 

* secrets/ldap: updates API documentation

* Update website/content/api-docs/secret/ldap.mdx

Co-authored-by: Christopher Swenson <christopher.swenson@hashicorp.com>

* Update website/content/api-docs/secret/ldap.mdx

Co-authored-by: Christopher Swenson <christopher.swenson@hashicorp.com>

* Update website/content/api-docs/secret/ldap.mdx

Co-authored-by: Christopher Swenson <christopher.swenson@hashicorp.com>

* Update website/content/api-docs/secret/ldap.mdx

Co-authored-by: Christopher Swenson <christopher.swenson@hashicorp.com>

* Update website/content/api-docs/secret/ldap.mdx

Co-authored-by: Christopher Swenson <christopher.swenson@hashicorp.com>

* Update website/content/api-docs/secret/ldap.mdx

Co-authored-by: Christopher Swenson <christopher.swenson@hashicorp.com>

* Update website/content/api-docs/secret/ldap.mdx

Co-authored-by: Christopher Swenson <christopher.swenson@hashicorp.com>

* Update website/content/api-docs/secret/ldap.mdx

Co-authored-by: Christopher Swenson <christopher.swenson@hashicorp.com>

* Update website/content/api-docs/secret/ldap.mdx

Co-authored-by: Christopher Swenson <christopher.swenson@hashicorp.com>

* Update website/content/api-docs/secret/ldap.mdx

Co-authored-by: Christopher Swenson <christopher.swenson@hashicorp.com>

* Update website/content/api-docs/secret/ldap.mdx

Co-authored-by: Christopher Swenson <christopher.swenson@hashicorp.com>

* Update website/content/api-docs/secret/ldap.mdx

Co-authored-by: Christopher Swenson <christopher.swenson@hashicorp.com>

* Update website/content/api-docs/secret/ldap.mdx

Co-authored-by: Christopher Swenson <christopher.swenson@hashicorp.com>

* Update website/content/api-docs/secret/ldap.mdx

Co-authored-by: Christopher Swenson <christopher.swenson@hashicorp.com>

Co-authored-by: Christopher Swenson <christopher.swenson@hashicorp.com>
This commit is contained in:
Austin Gebauer 2022-10-07 06:50:37 -07:00 committed by GitHub
parent 191f6e4bf0
commit db8c690684
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 282 additions and 50 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -18,14 +18,14 @@ update your API calls accordingly.
## Configuration Management
This endpoint configures the LDAP secret engine to manage user entries.
| Method | Path |
| :------- | :----------------- |
| `POST` | `/ldap/config` |
| `GET` | `/ldap/config` |
| `DELETE` | `/ldap/config` |
This endpoint configures the LDAP secret engine to managed user entries.
-> **Note**: The LDAP entry used by `config` should have the necessary privileges
to search and change entry passwords in LDAP.
@ -42,6 +42,17 @@ to search and change entry passwords in LDAP.
to use to generate passwords. Note that this accepts the name of the policy, not the policy itself.
- `schema` `(string: "openldap")` - The LDAP schema to use when storing entry passwords.
Valid schemas include `openldap`, `ad`, and `racf`.
- `userdn` `(string: <optional>)` - The base DN under which to perform user search in
[library management](/api-docs/secret/ldap#library-management) and [static roles](/api-docs/secret/ldap#static-roles).
For example, `ou=Users,dc=hashicorp,dc=com`.
- `userattr` `(string: <optional>)` – The attribute field name used to perform user search
in [library management](/api-docs/secret/ldap#library-management) and [static roles](/api-docs/secret/ldap#static-roles).
Defaults to `cn` for the `openldap` schema, `userPrincipalName` for the `ad` schema, and
`racfid` for the `racf` schema.
- `upndomain` (string: `optional`) - The domain (userPrincipalDomain) used to construct a UPN
string for authentication. The constructed UPN will appear as `[binddn]@[upndomain]`. For
example, if `upndomain=example.com` and `binddn=admin`, the UPN string `admin@example.com`
will be used to log in to Active Directory.
- `request_timeout` `(integer: 90, string: "90s" <optional>)` - Timeout, in seconds, for the connection when
making requests against the server before returning back an error.
- `starttls` `(bool: <optional>)` - If true, issues a `StartTLS` command after establishing an unencrypted connection.
@ -143,17 +154,6 @@ $ curl \
The `static-role` endpoint configures Vault to manage the passwords of existing individual LDAP entries.
### Parameters
- `dn` `(string: <required>)` - Distinguished name (DN) of entry Vault should manage.<br />
**Example:** `cn=bob,ou=Users,dc=hashicorp,dc=com`
- `rotation_period` `(string: <required>)` - How often Vault should rotate the password of the user entry. Accepts
[duration format strings](/docs/concepts/duration-format). The minimum rotation period is 5 seconds.<br />
**Example:** "3600", "5s", "1h".
- `username` `(string: <required>)` - The name of the user to be used when logging in. This is useful when `dn`
isn't used for login purposes (such as SSH).<br />
**Example:** "bob"
| Method | Path |
| :------- | :--------------------------------- |
| `GET` | `/ldap/static-role` |
@ -161,6 +161,22 @@ The `static-role` endpoint configures Vault to manage the passwords of existing
| `POST` | `/ldap/static-role/:role_name` |
| `DELETE` | `/ldap/static-role/:role_name` |
### Parameters
- `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](/api-docs/secret/ldap#userdn)
configuration value. The attribute to use when searching for the user can be configured
with the [userattr](/api-docs/secret/ldap#userattr) configuration value. This is useful
when `dn` isn't used for login purposes (such as SSH). Cannot be modified after creation.<br />
**Example:** `"bob"`
- `dn` `(string: <optional>)` - Distinguished name (DN) of the existing LDAP entry to manage
password rotation for. If given, it will take precedence over `username` for the LDAP
search performed during password rotation. Cannot be modified after creation.<br />
**Example:** `cn=bob,ou=Users,dc=hashicorp,dc=com`
- `rotation_period` `(string: <required>)` - How often Vault should rotate the password of the user entry. Accepts
[duration format strings](/docs/concepts/duration-format). The minimum rotation period is 5 seconds.<br />
**Example:** `"3600", "5s", "1h"`
### Sample Payload
```json
@ -209,7 +225,7 @@ $ curl \
["hashicorp", "bob"]
```
### Static Role Passwords
## Static Role Passwords
The `static-cred` endpoint offers the credential information for a given static-role.
@ -233,13 +249,14 @@ $ curl \
"dn": "uid=hashicorp,ou=Users,dc=hashicorp,dc=com",
"last_vault_rotation": "2020-02-19T11:31:53.7812-05:00",
"password": "LTNfyn7pS7XEZIxEYQ2sEAWic02PEP7zSvIs0xMqIjaU0ORzLhKOKVmYLxL1Xkyv",
"last_password": "?@09AZSen9TzUwK7ZhafS7B0GuWGraQjfWEna5SwnmF/tVaKFqjXhhGV/Z0v/pBJ",
"rotation_period": 86400,
"ttl": 86072,
"username": "hashicorp"
}
```
### Manually Rotate Static Role Password
## Manually Rotate Static Role Password
The `rotate-role` endpoint rotates the password of an existing static role.
@ -263,7 +280,7 @@ LDAP domain user account.
### Create/Delete Dynamic Role Configuration
#### Parameters
Creates, updates, or deletes a dynamic role.
| Method | Path |
| :------- | :-------------------------- |
@ -274,28 +291,26 @@ The `POST` endpoint allows for partial updates of existing roles. If a role exis
against it, only the keys specified in the request will be updated. To delete a value, specify the key with an
empty string as the value. Example: `vault write ldap/role/myrole default_ttl=""`
`role_name` `(string, required)` - The name of the dynamic role.
#### Parameters
`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
stop at the first error and not execute any remaining LDIF entries. If an error occurs and `rollback_ldif` is
specified, the LDIF entries in `rollback_ldif` will be executed. See `rollback_ldif` for more details. This field
may optionally be provided as a base64 encoded string.
`deletion_ldif` `(string, required)` - A templatized LDIF string used to delete the user account once its TTL has
expired. This may contain multiple LDIF entries. All LDIF entries are performed in order. If Vault encounters an
error while executing an entry in the `deletion_ldif` it will attempt to continue executing any remaining entries.
This field may optionally be provided as a base64 encoded string.
`rollback_ldif` `(string, not required but recommended)` - A templatized LDIF string used to attempt to rollback
any changes in the event that execution of the `creation_ldif` results in an error. This may contain multiple LDIF
entries. All LDIF entries are performed in order. If Vault encounters an error while executing an entry in the
`rollback_ldif` it will attempt to continue executing any remaining entries. This field may optionally be provided
as a base64 encoded string.
`username_template` `(string)` - A template used to generate a dynamic username. This will be used to fill in the
`.Username` field within the `creation_ldif` string.
- `role_name` `(string, required)` - The name of the dynamic role.
- `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
stop at the first error and not execute any remaining LDIF entries. If an error occurs and `rollback_ldif` is
specified, the LDIF entries in `rollback_ldif` will be executed. See `rollback_ldif` for more details. This field
may optionally be provided as a base64 encoded string.
- `deletion_ldif` `(string, required)` - A templatized LDIF string used to delete the user account once its TTL has
expired. This may contain multiple LDIF entries. All LDIF entries are performed in order. If Vault encounters an
error while executing an entry in the `deletion_ldif` it will attempt to continue executing any remaining entries.
This field may optionally be provided as a base64 encoded string.
- `rollback_ldif` `(string, not required but recommended)` - A templatized LDIF string used to attempt to rollback
any changes in the event that execution of the `creation_ldif` results in an error. This may contain multiple LDIF
entries. All LDIF entries are performed in order. If Vault encounters an error while executing an entry in the
`rollback_ldif` it will attempt to continue executing any remaining entries. This field may optionally be provided
as a base64 encoded string.
- `username_template` `(string)` - A template used to generate a dynamic username. This will be used to fill in the
`.Username` field within the `creation_ldif` string.
<details>
<summary><b>Default Username Template</b></summary>
@ -322,13 +337,12 @@ v_{{.DisplayName}}_{{.RoleName}}_{{random 10}}_{{unix_time}}
</details>
</details>
`default_ttl` `(string/int)` - Specifies the TTL for the leases associated with this role. Accepts
[duration format strings](/docs/concepts/duration-format). Defaults to system/engine default TTL time.
`max_ttl` `(string/int)` - Specifies the maximum TTL for the leases associated with this role. Accepts
[duration format strings](/docs/concepts/duration-format). Defaults to system/mount default TTL time;
this value is allowed to be less than the mount max TTL (or, if not set, the system max TTL),
but it is not allowed to be longer.
- `default_ttl` `(string/int)` - Specifies the TTL for the leases associated with this role. Accepts
[duration format strings](/docs/concepts/duration-format). Defaults to system/engine default TTL time.
- `max_ttl` `(string/int)` - Specifies the maximum TTL for the leases associated with this role. Accepts
[duration format strings](/docs/concepts/duration-format). Defaults to system/mount default TTL time;
this value is allowed to be less than the mount max TTL (or, if not set, the system max TTL),
but it is not allowed to be longer.
The `creation_ldif`, `deletion_ldif`, `rollback_ldif`, and `username_template` fields are all templated fields. See
[Username Templating](/docs/concepts/username-templating) for details on how to use templating. Also see
@ -385,16 +399,12 @@ $ curl \
### Read Dynamic Role Configuration
Retrieves a dynamic role's configuration.
| Method | Path |
| ------ | --------------------------- |
| `GET` | `/ldap/role/:role_name` |
Retrieves a dynamic role's configuration.
#### Parameters
None
#### Response
`200 OK`
@ -536,3 +546,225 @@ The username template cannot use this function.
`utf16le` - Encodes the provided value into UTF16-LE.<br />
**Example:** `{{.FieldName | utf16le}}`
## Library Set Management
The `library` endpoint configures the sets of service accounts that Vault will offer for check-out.
| Method | Path |
| :------- | :---------------------- |
| `LIST` | `/ldap/library` |
| `POST` | `/ldap/library/:set_name` |
| `GET` | `/ldap/library/:set_name` |
| `DELETE` | `/ldap/library/:set_name` |
When adding a service account to the library, Vault verifies it already exists in the LDAP directory.
### Parameters
- `name` `(string: "", required)` - The name of the set of service accounts.
- `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.
- `ttl` `(duration: "24h", optional)` - The maximum amount of time a single check-out lasts before Vault
automatically checks it back in. Defaults to 24 hours. Setting it to zero reflects an unlimited lending period.
Uses [duration format strings](/docs/concepts/duration-format).
- `max_ttl` `(duration: "24h", optional)` - The maximum amount of time a check-out last with renewal before Vault
automatically checks it back in. Defaults to 24 hours. Setting it to zero reflects an unlimited lending period.
Uses [duration format strings](/docs/concepts/duration-format).
- `disable_check_in_enforcement` `(bool: false, optional)` - Disable enforcing that service accounts must be
checked in by the entity or client token that checked them out. Defaults to false.
### Sample POST Request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/ldap/library/accounting-team
```
### Sample POST Payload
```json
{
"service_account_names": ["fizz@example.com", "buzz@example.com"],
"ttl": "10h",
"max_ttl": "20h",
"disable_check_in_enforcement": false
}
```
### Sample GET Response
```json
{
"service_account_names": ["fizz@example.com", "buzz@example.com"],
"ttl": "10h",
"max_ttl": "20h",
"disable_check_in_enforcement": false
}
```
### Sample LIST Response
Performing a `LIST` on the `/ldap/library` endpoint will list the names of all the sets of service accounts Vault contains.
```json
["accounting-team"]
```
## Library Set Status Check
This endpoint provides the check-out status of service accounts in a library set.
| Method | Path |
| :----- | :----------------------------- |
| `GET` | `/ldap/library/:set_name/status` |
### Sample GET Request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
http://127.0.0.1:8200/v1/ldap/library/accounting-team/status
```
### Sample GET Response
```json
{
"request_id": "9e44c8b5-d142-5867-2a11-49f3ba71215a",
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": {
"buzz@example.com": {
"available": true
},
"fizz@example.com": {
"available": false,
"borrower_client_token": "4c653e473bf7e27c6759fccc3def20c44d776279",
"borrower_entity_id": "631256b1-8523-9838-5501-d0a1e2cdad9c"
}
},
"wrap_info": null,
"warnings": null,
"auth": null
}
```
## Check-Out Management
This endpoint provides service account check out for a library set.
| Method | Path |
| :----- | :-------------------------------- |
| `POST` | `/ldap/library/:set_name/check-out` |
Returns a `200` if a credential is available, and a `400` if no credential is available.
### Parameters
- `name` `(string: "", required)` - The name of the set of service accounts.
- `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.
Uses [duration format strings](/docs/concepts/duration-format).
### Sample POST Request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/ldap/library/accounting-team/check-out
```
### Sample POST Payload
```json
{
"ttl": "1h"
}
```
### Sample POST Response
```json
{
"request_id": "364a17d4-e5ab-998b-ceee-b49929229e0c",
"lease_id": "ad/library/accounting-team/check-out/aoBsaBEI4PK96VnukubvYDlZ",
"renewable": true,
"lease_duration": 36000,
"data": {
"password": "?@09QW0KZ8DSBu3deIu7XLY1NZqzwhozmMAZ6v0IcZJGOjs5GvpVMvOeW7/duls2",
"service_account_name": "fizz@example.com"
},
"wrap_info": null,
"warnings": null,
"auth": null
}
```
## Check-In Management
By default, check-in must be called by the same entity or client token used for check-out.
To disable this behavior, use the `disable_check_in_enforcement` toggle on the library set. Or, use
the `ad/library/manage/:set_name/check-in` behavior to force check-in of the account. Access to the
"manage" endpoint should only be granted to highly privileged Vault users, like Vault operators.
If a caller attempts to check in a service account they're not authorized to check in, they will
receive an error response. If they attempt to check in a service account they _are_ authorized to
check in, but it's _already_ checked in, they will receive a successful response but the account
will not be included in the `check_ins` listed. `check_ins` shows which service accounts were checked
in _by this particular call_.
| Method | Path |
| :----- | :-------------------------------------- |
| `POST` | `/ldap/library/:set_name/check-in` |
| `POST` | `/ldap/library/manage/:set_name/check-in` |
### Parameters
- `name` `(string: "", required)` - The name of the set of service accounts.
- `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.
### Sample POST Request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/ldap/library/accounting-team/check-in
```
### Sample POST Payload
```json
{
"service_account_names": ["fizz@example.com"]
}
```
### Sample POST Response
```json
{
"request_id": "db45c714-3f68-b748-95bc-8f7467637a52",
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": {
"check_ins": ["fizz@example.com"]
},
"wrap_info": null,
"warnings": null,
"auth": null
}
```