From 8497dc66d09673dbefa00b678b7a05297cfeec30 Mon Sep 17 00:00:00 2001 From: kpcraig <3031348+kpcraig@users.noreply.github.com> Date: Thu, 27 Feb 2025 13:44:36 -0500 Subject: [PATCH] Add docs for plugins with enterprise scheduled root rotation feature (#29608) --- website/content/api-docs/auth/azure.mdx | 2 + website/content/api-docs/auth/ldap.mdx | 23 +------ website/content/api-docs/secret/azure.mdx | 2 + website/content/api-docs/secret/ldap.mdx | 6 +- website/content/docs/auth/azure.mdx | 54 +++++++++++++++++ website/content/docs/auth/ldap.mdx | 66 +++++++++++++++++++++ website/content/docs/secrets/azure.mdx | 52 ++++++++++++++-- website/content/docs/secrets/ldap.mdx | 66 +++++++++++++++++++-- website/content/partials/rotationfields.mdx | 21 +++++++ 9 files changed, 258 insertions(+), 34 deletions(-) create mode 100644 website/content/partials/rotationfields.mdx diff --git a/website/content/api-docs/auth/azure.mdx b/website/content/api-docs/auth/azure.mdx index 98ebc9f2c9..4c090a857e 100644 --- a/website/content/api-docs/auth/azure.mdx +++ b/website/content/api-docs/auth/azure.mdx @@ -56,6 +56,8 @@ identity federation (WIF). - `max_retry_delay` `(string: '60s')` - The maximum delay, in seconds, allowed before retrying an operation. - `retry_delay` `(string: '4s')` - The initial amount of delay, in seconds, to use before retrying an operation. Increases exponentially. +@include 'rotationfields.mdx' + ### Sample payload ```json diff --git a/website/content/api-docs/auth/ldap.mdx b/website/content/api-docs/auth/ldap.mdx index 14ac7a0c79..02e518e536 100644 --- a/website/content/api-docs/auth/ldap.mdx +++ b/website/content/api-docs/auth/ldap.mdx @@ -108,27 +108,8 @@ This endpoint configures the LDAP auth method. - `enable_samaccountname_login` `(bool: false)` - (Optional) Lets Active Directory LDAP users log in using `sAMAccountName` or `userPrincipalName` when the `upndomain` parameter is set. -- `rotation_period` `(integer: 0)` – - The amount of time, in seconds, - Vault should wait before rotating the root credential. A zero value tells Vault - not to rotate the token. The minimum rotation period is 5 seconds. **You must - set one of `rotation_period` or `rotation_schedule`, but cannot set both**. -- `rotation_schedule` `(string: "")` – - The schedule, in [cron-style time format](https://en.wikipedia.org/wiki/Cron), - defining the schedule on which Vault should rotate the root token. Standard - cron-style time format uses five fields to define the minute, hour, day of - month, month, and day of week respectively. For example, `0 0 * * SAT` tells - Vault to rotate the root token every Saturday at 00:00. **You must set one of - `rotation_schedule` or `rotation_period`, but cannot set both**. -- `rotation_window` `(integer: 0)` – - The maximum amount of time, in seconds, allowed to complete - a rotation when a scheduled token rotation occurs. If Vault cannot rotate the - token within the window (for example, due to a failure), Vault must wait to - try again until the next scheduled rotation. The default rotation window is - unbound and the minimum allowable window is 1 hour. **You cannot set a rotation - window when using `rotation_period`**. -- `disable_automated_rotation` `(bool: false)` - - Cancels all upcoming rotations of the root credential until unset. + +@include 'rotationfields.mdx' @include 'tokenfields.mdx' diff --git a/website/content/api-docs/secret/azure.mdx b/website/content/api-docs/secret/azure.mdx index b10c694558..5439f488e1 100644 --- a/website/content/api-docs/secret/azure.mdx +++ b/website/content/api-docs/secret/azure.mdx @@ -47,6 +47,8 @@ plugin workload identity federation (WIF). - `root_password_ttl` `(string: 182d)` - Specifies how long the root password is valid for in Azure when rotate-root generates a new client secret. Uses [duration format strings](/vault/docs/concepts/duration-format). +@include 'rotationfields.mdx' + ### Sample payload ```json diff --git a/website/content/api-docs/secret/ldap.mdx b/website/content/api-docs/secret/ldap.mdx index a2151ac719..f130e923ad 100644 --- a/website/content/api-docs/secret/ldap.mdx +++ b/website/content/api-docs/secret/ldap.mdx @@ -67,6 +67,8 @@ to search and change entry passwords in LDAP. creating static roles. This field can be overridden on an individual role level during [role creation](#static-roles). See the [static roles section](#static-roles) for more detailed information and caveats. +@include 'rotationfields.mdx' + **Deprecated Parameters**: - `length` `(int: 64)` - The length of generated password strings. Note: some schemas may require shorter @@ -170,9 +172,9 @@ The `static-role` endpoint configures Vault to manage the passwords of existing | `POST` | `/ldap/static-role/:role_name` | | `DELETE` | `/ldap/static-role/:role_name` | - + - Windows Servers hosting Active Directory include a + Windows Servers hosting Active Directory include a `lifetime period of an old password` configuration setting that lets clients authenticate with old passwords for a specified amount of time. diff --git a/website/content/docs/auth/azure.mdx b/website/content/docs/auth/azure.mdx index bae60e9b2a..9b8f77909a 100644 --- a/website/content/docs/auth/azure.mdx +++ b/website/content/docs/auth/azure.mdx @@ -234,6 +234,60 @@ tool. https://127.0.0.1:8200/v1/auth/azure/role/dev-role ``` +## Root credential rotation + +Mounts can rotate root credential keys configured directly within the mount. +Rotating to a Vault-generated key makes the key value inaccessible to the +operator and ensures only Vault can operate as a root user to manipulate dynamic +and static credentials. + +```shell-session +vault write -f auth/azure/rotate-root +``` + +### Schedule-based root credential rotation + +@include 'alerts/enterprise-only.mdx' + +Use the [`rotation_schedule`](/vault/api-docs/auth/azure#rotation_schedule) field +to configure schedule-based, automatic credential rotation for root credentials in +the Azure auth engine. For example, the following command set the rotation to +occur every Saturday at midnight (00:00): + +```shell-session +$ vault write auth/azure/config \ + ... + rotation_schedule="0 * * * SAT" + ... +``` + +Scheduled root credential rotation can also set a +[rotation_window](/vault/api-docs/auth/azure#rotation_window) during which the +scheduled rotation is allowed to occur. Vault will stop trying to rotate the +credential once the window expires. For example, the following command tells +Vault to rotate the credential on Saturday at midnight, but only within the span +of an hour. If Vault cannot rotate the credential by 1:00, due to a failure +or otherwise, Vault will stop trying to rotate the credential until the next +scheduled rotation. + +```shell-session +$ vault write auth/azure/config \ + ... + rotation_window="1h" \ + rotation_schedule="0 * * * SAT" + ... +``` + +You can temporarily disable root rotation by setting +[`disable_automated_rotation`](/vault/api-docs/auth/azure#disable_automated_rotation) +to `true`. Setting the `disable_automated_rotation` field prevent any rotation +of the root credential until the field is reset to `false`. If you use +`rotation_period`, setting `disable_automated_rotation` also resets the credential +TTL. + +For more details on rotating root credentials in the Azure plugin, refer to the +[Root credential rotation](/vault/api-docs/auth/azure#rotate-root) API docs. + ## Azure managed identities There are two types of [managed identities](https://learn.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/overview#managed-identity-types) diff --git a/website/content/docs/auth/ldap.mdx b/website/content/docs/auth/ldap.mdx index a7e2fee80f..5a1d4c8c8b 100644 --- a/website/content/docs/auth/ldap.mdx +++ b/website/content/docs/auth/ldap.mdx @@ -160,11 +160,77 @@ _Note_: When using _Authenticated Search_ for binding parameters (see above) the Use `vault path-help` for more details. +### Root secret rotation + +@include 'alerts/enterprise-only.mdx' + +- `rotation_schedule` (string: "") - The schedule, in + [cron-style time format](https://en.wikipedia.org/wiki/Cron), defining the + schedule on which Vault should rotate the root token. +- `rotation_window` (string: "") - The maximum amount of time, in + [duration format](https://pkg.go.dev/time#ParseDuration), allowed to complete + a rotation when a scheduled token rotation occurs. +- `rotation_period` (string: "") - The amount of time, in + [duration format](https://pkg.go.dev/time#ParseDuration), Vault should wait + before rotating the root credential. + ### Other - `username_as_alias` (bool, optional) - If set to true, forces the auth method to use the username passed by the user as the alias name. - `max_page_size` (int, optional) - If set to a value greater than 0, the LDAP backend will use the LDAP server's paged search control to request pages of up to the given size. This can be used to avoid hitting the LDAP server's maximum result size limit. Otherwise, the LDAP backend will not use the paged search control. +## Root credential rotation + +The root bindpass can be rotated to a Vault-generated value that is not accessible by the operator. +This will ensure that only Vault is able to access the "root" user that Vault uses to manipulate credentials. + +```shell-session +vault write -f auth/azure/rotate-root +``` + +### Schedule-based root credential rotation + +@include 'alerts/enterprise-only.mdx' + +Use the [`rotation_schedule`](/vault/api-docs/auth/ldap#rotation_schedule) field +to configure schedule-based, automatic credential rotation for root credentials in +the LDAP auth engine. For example, the following command set the rotation to +occur every Saturday at midnight (00:00): + +```shell-session +$ vault write auth/ldap/config \ + ... + rotation_schedule="0 * * * SAT" + ... +``` + +Scheduled root credential rotation can also set a +[rotation_window](/vault/api-docs/auth/ldap#rotation_window) during which the +scheduled rotation is allowed to occur. Vault will stop trying to rotate the +credential once the window expires. For example, the following command tells +Vault to rotate the credential on Saturday at midnight, but only within the span +of an hour. If Vault cannot rotate the credential by 1:00, due to a failure +or otherwise, Vault will stop trying to rotate the credential until the next +scheduled rotation. + +```shell-session +$ vault write auth/ldap/config \ + ... + rotation_window="1h" \ + rotation_schedule="0 * * * SAT" + ... +``` + +You can temporarily disable root rotation by setting +[`disable_automated_rotation`](/vault/api-docs/auth/ldap#disable_automated_rotation) +to `true`. Setting the `disable_automated_rotation` field prevent any rotation +of the root credential until the field is reset to `false`. If you use +`rotation_period`, setting `disable_automated_rotation` also resets the credential +TTL. + +For more details on rotating root credentials in the Azure plugin, refer to the +[Root credential rotation](/vault/api-docs/auth/ldap#rotate-root) API docs. + ## Examples: ### Scenario 1 diff --git a/website/content/docs/secrets/azure.mdx b/website/content/docs/secrets/azure.mdx index 6f704f0ebc..a7b30e4f20 100644 --- a/website/content/docs/secrets/azure.mdx +++ b/website/content/docs/secrets/azure.mdx @@ -227,17 +227,57 @@ principal or the Azure roles set in the "my-role" configuration. ## Root credential rotation -If the mount is configured with credentials directly, the credential's key may be -rotated to a Vault-generated value that is not accessible by the operator. -This will ensure that only Vault is able to access the "root" user that Vault uses to -manipulate dynamic & static credentials. +Mounts can rotate root credential keys configured directly within the mount. +Rotating to a Vault-generated key makes the key value inaccessible to the +operator and ensures only Vault can operate as a root user to manipulate dynamic +and static credentials. ```shell-session vault write -f azure/rotate-root ``` -For more details on this operation, please see the -[Root Credential Rotation](/vault/api-docs/secret/azure#rotate-root) API docs. +### Schedule-based credential rotation + +@include 'alerts/enterprise-only.mdx' + +Use the [`rotation_schedule`](/vault/api-docs/secret/azure#rotation_schedule) field +to configure schedule-based, automatic credential rotation for root credentials in +the Azure secrets engine. For example, the following command set the rotation to +occur every Saturday at midnight (00:00):: + +```shell-session +$ vault write azure/config \ + ... + rotation_schedule="0 * * * SAT" + ... +``` + +Scheduled root credential rotation can also set a +[rotation_window](/vault/api-docs/secret/azure#rotation_window) during which the +scheduled rotation is allowed to occur. Vault will stop trying to rotate the +credential once the window expires. For example, the following command tells +Vault to rotate the credential on Saturday at midnight, but only within the span +of an hour. If Vault cannot rotate the credential by 1:00, due to a failure +or otherwise, Vault will stop trying to rotate the credential until the next +scheduled rotation. + +```shell-session +$ vault write azure/config \ + ... + rotation_window="1h" \ + rotation_schedule="0 * * * SAT" + ... +``` + +You can temporarily disable root rotation by setting +[`disable_automated_rotation`](/vault/api-docs/secret/azure#disable_automated_rotation) +to `true`. Setting the `disable_automated_rotation` field prevent any rotation +of the root credential until the field is reset to `false`. If you use +`rotation_period`, setting `disable_automated_rotation` also resets the credential +TTL. + +For more details on rotating root credentials in the Azure plugin, refer to the +[Root credential rotation](/vault/api-docs/secret/azure#rotate-root) API docs. ## Roles diff --git a/website/content/docs/secrets/ldap.mdx b/website/content/docs/secrets/ldap.mdx index 1588346566..604684e02e 100644 --- a/website/content/docs/secrets/ldap.mdx +++ b/website/content/docs/secrets/ldap.mdx @@ -101,6 +101,63 @@ $ vault write ldap/config \ schema=ad ``` +## Root credential rotation + +Mounts can rotate root credential keys configured directly within the mount. +Rotating to a Vault-generated key makes the key value inaccessible to the +operator and ensures only Vault can operate as a root user to manipulate dynamic +and static credentials. + +```shell-session +vault write -f ldap/rotate-root +``` + +### Schedule-based root credential rotation + +@include 'alerts/enterprise-only.mdx' + +Use the [`rotation_schedule`](/vault/api-docs/secret/ldap#rotation_schedule) field +to configure schedule-based, automatic credential rotation for root credentials in +the LDAP secrets engine. For example, the following command set the rotation to +occur every Saturday at midnight (00:00): + +```shell-session +$ vault write ldap/config \ + ... + rotation_schedule="0 * * * SAT" + ... +``` + +This configuration will set the role's credential rotation to occur on Saturday +at 00:00. + +Scheduled root credential rotation can also set a +[rotation_window](/vault/api-docs/secret/ldap#rotation_window) during which the +scheduled rotation is allowed to occur. Vault will stop trying to rotate the +credential once the window expires. For example, the following command tells +Vault to rotate the credential on Saturday at midnight, but only within the span +of an hour. If Vault cannot rotate the credential by 1:00, due to a failure +or otherwise, Vault will stop trying to rotate the credential until the next +scheduled rotation. + +```shell-session +$ vault write ldap/config \ + ... + rotation_window="1h" \ + rotation_schedule="0 * * * SAT" + ... +``` + +You can temporarily disable root rotation by setting +[`disable_automated_rotation`](/vault/api-docs/secret/ldap#disable_automated_rotation) +to `true`. Setting the `disable_automated_rotation` field prevent any rotation +of the root credential until the field is reset to `false`. If you use +`rotation_period`, setting `disable_automated_rotation` also resets the credential +TTL. + +For more details on rotating root credentials in the Azure plugin, refer to the +[Root credential rotation](/vault/api-docs/secret/ldap#rotate-root) API docs. + ## Static credentials ### Setup @@ -128,14 +185,13 @@ Passwords can be managed in two ways: - automatic time based rotation - manual rotation -### Auto password rotation +### TTL-based static role rotation Passwords will automatically be rotated based on the `rotation_period` configured in the static role (minimum of 5 seconds). When requesting credentials for a static role, the response will include the time before the next rotation (`ttl`). -Auto-rotation is currently only supported for static roles. The `binddn` account used -by Vault should be rotated using the `rotate-root` endpoint to generate a password +The `binddn` account used by Vault should be rotated using the `rotate-root` endpoint to generate a password only Vault will know. ### Manual rotation @@ -199,9 +255,9 @@ Some important things to remember when crafting your LDIF entries: ### Active directory (AD) - + - Windows Servers hosting Active Directory include a + Windows Servers hosting Active Directory include a `lifetime period of an old password` configuration setting that lets clients authenticate with old passwords for a specified amount of time. diff --git a/website/content/partials/rotationfields.mdx b/website/content/partials/rotationfields.mdx new file mode 100644 index 0000000000..9f7f5f89af --- /dev/null +++ b/website/content/partials/rotationfields.mdx @@ -0,0 +1,21 @@ +- `rotation_period` `(integer: 0)` – + The amount of time, in seconds, + Vault should wait before rotating the root credential. A zero value tells Vault + not to rotate the token. The minimum rotation period is 5 seconds. **You must + set one of `rotation_period` or `rotation_schedule`, but cannot set both**. +- `rotation_schedule` `(string: "")` – + The schedule, in [cron-style time format](https://en.wikipedia.org/wiki/Cron), + defining the schedule on which Vault should rotate the root token. Standard + cron-style time format uses five fields to define the minute, hour, day of + month, month, and day of week respectively. For example, `0 0 * * SAT` tells + Vault to rotate the root token every Saturday at 00:00. **You must set one of + `rotation_schedule` or `rotation_period`, but cannot set both**. +- `rotation_window` `(integer: 0)` – + The maximum amount of time, in seconds, allowed to complete + a rotation when a scheduled token rotation occurs. If Vault cannot rotate the + token within the window (for example, due to a failure), Vault must wait to + try again until the next scheduled rotation. The default rotation window is + unbound and the minimum allowable window is 1 hour. **You cannot set a rotation + window when using `rotation_period`**. +- `disable_automated_rotation` `(bool: false)` - + Cancels all upcoming rotations of the root credential until unset.