From db8c6906849fbdb29825826f362c38b8dc279151 Mon Sep 17 00:00:00 2001 From: Austin Gebauer <34121980+austingebauer@users.noreply.github.com> Date: Fri, 7 Oct 2022 06:50:37 -0700 Subject: [PATCH] secrets/ldap: updates API documentation (#17448) * secrets/ldap: updates API documentation * Update website/content/api-docs/secret/ldap.mdx Co-authored-by: Christopher Swenson * Update website/content/api-docs/secret/ldap.mdx Co-authored-by: Christopher Swenson * Update website/content/api-docs/secret/ldap.mdx Co-authored-by: Christopher Swenson * Update website/content/api-docs/secret/ldap.mdx Co-authored-by: Christopher Swenson * Update website/content/api-docs/secret/ldap.mdx Co-authored-by: Christopher Swenson * Update website/content/api-docs/secret/ldap.mdx Co-authored-by: Christopher Swenson * Update website/content/api-docs/secret/ldap.mdx Co-authored-by: Christopher Swenson * Update website/content/api-docs/secret/ldap.mdx Co-authored-by: Christopher Swenson * Update website/content/api-docs/secret/ldap.mdx Co-authored-by: Christopher Swenson * Update website/content/api-docs/secret/ldap.mdx Co-authored-by: Christopher Swenson * Update website/content/api-docs/secret/ldap.mdx Co-authored-by: Christopher Swenson * Update website/content/api-docs/secret/ldap.mdx Co-authored-by: Christopher Swenson * Update website/content/api-docs/secret/ldap.mdx Co-authored-by: Christopher Swenson * Update website/content/api-docs/secret/ldap.mdx Co-authored-by: Christopher Swenson Co-authored-by: Christopher Swenson --- website/content/api-docs/secret/ldap.mdx | 332 +++++++++++++++++++---- 1 file changed, 282 insertions(+), 50 deletions(-) diff --git a/website/content/api-docs/secret/ldap.mdx b/website/content/api-docs/secret/ldap.mdx index 87dac09de..544484cd8 100644 --- a/website/content/api-docs/secret/ldap.mdx +++ b/website/content/api-docs/secret/ldap.mdx @@ -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: )` - 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: )` – 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" )` - Timeout, in seconds, for the connection when making requests against the server before returning back an error. - `starttls` `(bool: )` - 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: )` - Distinguished name (DN) of entry Vault should manage.
- **Example:** `cn=bob,ou=Users,dc=hashicorp,dc=com` -- `rotation_period` `(string: )` - 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.
- **Example:** "3600", "5s", "1h". -- `username` `(string: )` - 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).
- **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: )` - 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.
+ **Example:** `"bob"` +- `dn` `(string: )` - 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.
+ **Example:** `cn=bob,ou=Users,dc=hashicorp,dc=com` +- `rotation_period` `(string: )` - 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.
+ **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.
Default Username Template @@ -322,13 +337,12 @@ v_{{.DisplayName}}_{{.RoleName}}_{{random 10}}_{{unix_time}}
-`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.
**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 +} +```