scottk/vault
1
0
Fork 0
mirror of https://github.com/optim-enterprises-bv/vault.git synced 2025-10-28 17:22:41 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add docs for plugins with enterprise scheduled root rotation feature (#29608)

Browse Source
This commit is contained in:
kpcraig
2025-02-27 13:44:36 -05:00
committed by GitHub
parent 018674a798
commit 8497dc66d0
9 changed files with 258 additions and 34 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
website/content/api-docs/auth/azure.mdx
View File

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

23
website/content/api-docs/auth/ldap.mdx
View File

@@ -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)` – <EnterpriseAlert product="vault" inline />
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: "")` – <EnterpriseAlert product="vault" inline />
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)` – <EnterpriseAlert product="vault" inline />
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)` - <EnterpriseAlert product="vault" inline />
Cancels all upcoming rotations of the root credential until unset.
@include 'rotationfields.mdx'
@include 'tokenfields.mdx'

2
website/content/api-docs/secret/azure.mdx
View File

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

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

@@ -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` |
<Note>
<Note>
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.

54
website/content/docs/auth/azure.mdx
View File

@@ -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)

66
website/content/docs/auth/ldap.mdx
View File

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

52
website/content/docs/secrets/azure.mdx
View File

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

66
website/content/docs/secrets/ldap.mdx
View File

@@ -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)
<Note>
<Note>
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.

21
website/content/partials/rotationfields.mdx Normal file
View File

@@ -0,0 +1,21 @@
- `rotation_period` `(integer: 0)` – <EnterpriseAlert product="vault" inline />
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: "")` – <EnterpriseAlert product="vault" inline />
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)` – <EnterpriseAlert product="vault" inline />
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)` - <EnterpriseAlert product="vault" inline />
Cancels all upcoming rotations of the root credential until unset.