Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Backport of docs: db schedule-based static role rotations into release/1.15.x #22878

Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
82 changes: 74 additions & 8 deletions website/content/api-docs/secret/databases/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -479,7 +479,7 @@ $ curl \

This endpoint creates or updates a static role definition. Static Roles are a
1-to-1 mapping of a Vault Role to a user in a database which are automatically
rotated based on the configured `rotation_period`.
rotated based on the configured `rotation_period` or `rotation_schedule`.

~> This endpoint distinguishes between `create` and `update` ACL capabilities.

Expand All @@ -498,20 +498,40 @@ this in order to know the password.
- `username` `(string: <required>)` – Specifies the database username that this
Vault role corresponds to.

- `rotation_period` `(string/int: <required>)` – Specifies the amount of time
Vault should wait before rotating the password. The minimum is 5 seconds.

- `db_name` `(string: <required>)` - The name of the database connection to use
for this role.

- `rotation_period` `(string/int)` – Specifies the amount of time Vault should
wait before rotating the password. The minimum is 5 seconds. Uses [duration
format strings](/vault/docs/concepts/duration-format). Mutually exclusive
with `rotation_schedule`.

- `rotation_schedule` `(string)` – A cron-style string that will define the
schedule on which rotations should occur. This should be a "standard"
[cron-style](https://en.wikipedia.org/wiki/Cron) string made of five fields
of which each entry defines the minute, hour, day of month, month, and day of
week respectively. For example, a value of `0 0 * * SAT` will set rotations
to occur on Saturday at 00:00. Mutually exclusive with `rotation_period`.

~> **Warning**: The `rotation_period` and `rotation_schedule` fields are
mutually exclusive. One of them must be set but not both.

- `rotation_window` `(string/int)` – Specifies the amount of time in which the
rotation is allowed to occur starting from a given `rotation_schedule`. If
the credential is not rotated during this window, due to a failure or
otherwise, it will not be rotated until the next scheduled rotation. The
minimum is 1 hour. Uses [duration format strings](/vault/docs/concepts/duration-format).
Optional when `rotation_schedule` is set and disallowed when `rotation_period`
is set.

- `rotation_statements` `(list: [])` – Specifies the database statements to be
executed to rotate the password for the configured database user. Not every
plugin type will support this functionality. See the plugin's API page for
more information on support and formatting for this parameter.

@include 'db-secrets-credential-types.mdx'

### Sample payload
### Sample payload with rotation period

```json
{
Expand All @@ -524,6 +544,20 @@ this in order to know the password.
}
```

### Sample payload with rotation schedule

```json
{
"db_name": "mysql",
"username": "static-database-user",
"rotation_statements": [
"ALTER USER \"{{name}}\" IDENTIFIED BY '{{password}}';"
],
"rotation_schedule": "0 0 * * SAT",
"rotation_window": "1h"
}
```

### Sample request

```shell-session
Expand Down Expand Up @@ -555,7 +589,7 @@ $ curl \
http://127.0.0.1:8200/v1/database/static-roles/my-static-role
```

### Sample response
### Sample response with rotation period

```json
{
Expand All @@ -566,7 +600,24 @@ $ curl \
"rotation_statements": [
"ALTER USER \"{{name}}\" IDENTIFIED BY '{{password}}';"
],
"rotation_period": "1h"
"rotation_period": 3600
}
}
```

### Sample response with rotation schedule

```json
{
"data": {
"credential_type": "password",
"db_name": "mysql",
"username": "static-user",
"rotation_statements": [
"ALTER USER \"{{name}}\" IDENTIFIED BY '{{password}}';"
],
"rotation_schedule": "0 0 * * SAT",
"rotation_window": 3600
}
}
```
Expand Down Expand Up @@ -644,7 +695,7 @@ $ curl \
http://127.0.0.1:8200/v1/database/static-creds/my-static-role
```

### Sample response
### Sample response with rotation period

```json
{
Expand All @@ -658,6 +709,21 @@ $ curl \
}
```

### Sample response with rotation schedule

```json
{
"data": {
"username": "static-user",
"password": "132ae3ef-5a64-7499-351e-bfe59f3a2a21",
"last_vault_rotation": "2019-05-06T15:26:42.525302-05:00",
"rotation_schedule": "0 0 * * SAT",
"rotation_window": 3600,
"ttl": 5000
}
}
```

## Rotate static role credentials

This endpoint is used to rotate the Static Role credentials stored for a given
Expand Down
60 changes: 48 additions & 12 deletions website/content/docs/secrets/databases/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -28,17 +28,16 @@ become invalid within a reasonable time of the lease expiring.

### Static roles

With dynamic secrets, Vault generates a unique username and password pair for
each unique credential request. Vault also supports **static roles** for
some database secrets engines. Static roles are a 1-to-1 mapping of Vault roles
to usernames in a database. With static roles, Vault stores, and automatically
rotates, passwords for the associated database user based on a configurable
period of time.

When a client requests credentials for the static role, Vault
returns the current password for whichever database user is mapped to the
requested role. With static roles, anyone with the proper Vault policies can
access the associated user account in the database.
Vault also supports **static roles** for all database secrets engines. Static
roles are a 1-to-1 mapping of Vault roles to usernames in a database. With
static roles, Vault stores and automatically rotates passwords for the
associated database user based on a configurable period of time or rotation
schedule.

When a client requests credentials for the static role, Vault returns the
current password for whichever database user is mapped to the requested role.
With static roles, anyone with the proper Vault policies can access the
associated user account in the database.

<Warning title="Do not use static roles for root database credentials">
Do not manage the same root database credentials that you provide to Vault in
Expand All @@ -51,7 +50,7 @@ access the associated user account in the database.
valid.

If you need to rotate root credentials, use the
[Rotate root credentials](vault/api-docs/secret/database/index.mdx#rotate-root-credentials)
[Rotate root credentials](/vault/api-docs/secret/databases#rotate-root-credentials)
API endpoint.
</Warning>

Expand Down Expand Up @@ -188,6 +187,43 @@ of dynamic and static roles configure the credential that Vault will generate an
make available to database plugins. See the documentation of individual database
plugins for the credential types they support and usage examples.

## Schedule-based static role rotation

The database secrets engine supports configuring schedule-based automatic
credential rotation for static roles with the
[rotation_schedule](/vault/api-docs/secret/databases#rotation_schedule) field.
For example:

```shell-session
$ vault write database/static-roles/my-role \
db_name=my-database \
username="vault" \
rotation_schedule="0 * * * SAT"
```

This configuration will set the role's credential rotation to occur on Saturday
at 00:00.

Additionally, this schedule-based approach allows for optionally configuring a
[rotation_window](/vault/api-docs/secret/databases#rotation_window) in which
the automatic rotation is allowed to occur. For example:

```shell-session
$ vault write database/static-roles/my-role \
db_name=my-database \
username="vault" \
rotation_window="1h" \
rotation_schedule="0 * * * SAT"
```

This configuration will set rotations to occur on Saturday at 00:00. The 1
hour `rotation_window` will prevent the rotation from occuring after 01:00. If
the static role's credential is not rotated during this window, due to a failure
or otherwise, it will not be rotated until the next scheduled rotation.

!> The `rotation_period` and `rotation_schedule` fields are
mutually exclusive. One of them must be set but not both.

## Password generation

Passwords are generated via [Password Policies](/vault/docs/concepts/password-policies).
Expand Down