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 scheduled root rotation feature for the AWS and DB engines (#29755)

Browse Source
This commit is contained in:
vinay-gopalan
2025-02-27 15:48:47 -08:00
committed by GitHub
parent 58a49e6ce0
commit 1091474e4d
7 changed files with 149 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -91,6 +91,8 @@ capabilities, the credentials are fetched automatically.
an IAM based login call. In any case, a default list of headers AWS STS
expects for a GetCallerIdentity are allowed.
@include 'rotationfields.mdx'
### Sample payload
```json

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

@@ -103,6 +103,8 @@ valid AWS credentials with proper permissions.
{{ end }}
```
@include 'rotationfields.mdx'
### Sample payload
```json

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

@@ -61,6 +61,8 @@ list of additional parameters.
overridden at the role-level by the static role's [skip_import_rotation](#skip_import_rotation)
field. The default is false.
@include 'rotationfields.mdx'
~> We highly recommended that you use a Vault-specific user rather than the admin user
in your database when configuring the plugin. This user will be used to
create/update/delete users within the database so it will need to have the appropriate

43
website/content/docs/auth/aws.mdx
View File

@@ -351,6 +351,49 @@ are needed.
[Rotate Root Credentials](/vault/api-docs/auth/aws#rotate-root-credentials)
API call.
### Schedule-based root credential rotation
@include 'alerts/enterprise-only.mdx'
Use the [`rotation_schedule`](/vault/api-docs/auth/aws#rotation_schedule) field
to configure schedule-based, automatic credential rotation for root credentials in
the AWS auth engine. For example, the following command set the rotation to
occur every Saturday at midnight (00:00):
```shell-session
$ vault write auth/aws/config/client \
...
rotation_schedule="0 * * * SAT"
...
```
Scheduled root credential rotation can also set a
[rotation_window](/vault/api-docs/auth/aws#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/aws/config/client \
...
rotation_window="1h" \
rotation_schedule="0 * * * SAT"
...
```
You can temporarily disable root rotation by setting
[`disable_automated_rotation`](/vault/api-docs/auth/aws#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 AWS Auth engine, refer to the
[Rotate Root credentials](/vault/api-docs/auth/aws#rotate-root-credentials) API docs.
## Plugin Workload Identity Federation (WIF)
<EnterpriseAlert product="vault" />

59
website/content/docs/secrets/aws.mdx
View File

@@ -290,6 +290,49 @@ the proper permission, it can generate credentials.
</Note>
### Schedule-based root credential rotation
@include 'alerts/enterprise-only.mdx'
Use the [`rotation_schedule`](/vault/api-docs/secret/aws#rotation_schedule) field
to configure schedule-based, automatic credential rotation for root credentials in
the AWS secrets engine. For example, the following command set the rotation to
occur every Saturday at midnight (00:00):
```shell-session
$ vault write aws/config/root \
...
rotation_schedule="0 * * * SAT"
...
```
Scheduled root credential rotation can also set a
[rotation_window](/vault/api-docs/secret/aws#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 aws/config/root \
...
rotation_window="1h" \
rotation_schedule="0 * * * SAT"
...
```
You can temporarily disable root rotation by setting
[`disable_automated_rotation`](/vault/api-docs/secret/aws#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 AWS Secrets engine, refer to the
[Root credential rotation](/vault/api-docs/secret/aws#rotate-root-iam-credentials) API docs.
## IAM permissions policy for Vault
The `aws/config/root` credentials need permission to manage dynamic IAM users.
@@ -382,8 +425,8 @@ them).
<EnterpriseAlert product="vault" />
The AWS secrets engine supports the Plugin WIF workflow, and has a source of identity called
a plugin identity token. The plugin identity token is a JWT that is internally signed by Vault's
[plugin identity token issuer](/vault/api-docs/secret/identity/tokens#read-plugin-workload-identity-issuer-s-openid-configuration).
a plugin identity token. The plugin identity token is a JWT that is internally signed by Vault's
[plugin identity token issuer](/vault/api-docs/secret/identity/tokens#read-plugin-workload-identity-issuer-s-openid-configuration).
If there is a trust relationship configured between Vault and AWS through
[Web Identity Federation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_oidc.html),
@@ -397,15 +440,15 @@ credentials.
To configure the secrets engine to use plugin WIF:
1. Ensure that Vault [openid-configuration](/vault/api-docs/secret/identity/tokens#read-plugin-identity-token-issuer-s-openid-configuration)
and [public JWKS](/vault/api-docs/secret/identity/tokens#read-plugin-identity-token-issuer-s-public-jwks)
and [public JWKS](/vault/api-docs/secret/identity/tokens#read-plugin-identity-token-issuer-s-public-jwks)
APIs are network-reachable by AWS. We recommend using an API proxy or gateway
if you need to limit Vault API exposure.
if you need to limit Vault API exposure.
1. Create an
[IAM OIDC identity provider](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html)
in AWS.
1. The provider URL **must** point at your [Vault plugin identity token issuer](/vault/api-docs/secret/identity/tokens#read-plugin-workload-identity-issuer-s-openid-configuration) with the
`/.well-known/openid-configuration` suffix removed. For example:
`/.well-known/openid-configuration` suffix removed. For example:
`https://host:port/v1/identity/oidc/plugins`.
1. The audience should uniquely identify the recipient of the plugin identity
token. In AWS, the recipient is the identity provider. We recommend using
@@ -424,11 +467,11 @@ $ vault write aws/config/root \
role_arn="arn:aws:iam::123456789123:role/example-web-identity-role"
```
Your secrets engine can now use plugin WIF for its configuration credentials.
By default, WIF [credentials](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html)
Your secrets engine can now use plugin WIF for its configuration credentials.
By default, WIF [credentials](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html)
have a time-to-live of 1 hour and automatically refresh when they expire.
Please see the [API documentation](/vault/api-docs/secret/aws#configure-root-credentials)
Please see the [API documentation](/vault/api-docs/secret/aws#configure-root-credentials)
for more details on the fields associated with plugin WIF.
## STS credentials

47
website/content/docs/secrets/databases/index.mdx
View File

@@ -2,7 +2,7 @@
layout: docs
page_title: Database secrets engine
description: >-
Dynamically generate database credentials based on configured roles with the database secrets engine through a plugin interface to a number of different databases.
Dynamically generate database credentials based on configured roles with the database secrets engine through a plugin interface to a number of different databases.
---
# Database secrets engine
@@ -61,6 +61,51 @@ API endpoint.
</Warning>
### Schedule-based root credential rotation
@include 'alerts/enterprise-only.mdx'
Use the [`rotation_schedule`](/vault/api-docs/secret/databases#rotation_schedule) field
to configure schedule-based, automatic credential rotation for root credentials in
the DB Secrets engine. For example, the following command set the rotation to
occur every Saturday at midnight (00:00):
```shell-session
$ vault write database/config/my-mssql-database \
...
rotation_schedule="0 * * * SAT"
...
```
Scheduled root credential rotation can also set a
[rotation_window](/vault/api-docs/secret/databases#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 database/config/my-mssql-database \
...
rotation_window="1h" \
rotation_schedule="0 * * * SAT"
...
```
You can temporarily disable root rotation by setting
[`disable_automated_rotation`](/vault/api-docs/secret/databases#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 DB Secrets engine, refer to the
[Rotate Root credentials](/vault/api-docs/secret/databases#rotate-root-credentials) API docs.
## Setup
Most secrets engines must be configured in advance before they can perform their

6
website/content/partials/rotationfields.mdx
View File

@@ -1,7 +1,7 @@
- `rotation_period` `(integer: 0)` – <EnterpriseAlert product="vault" inline />
- `rotation_period` `(string/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
not to rotate the root credential. The minimum rotation period is 10 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),
@@ -10,7 +10,7 @@
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 />
- `rotation_window` `(string/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