From 187001809015fa7c621477f15badfc46d0503017 Mon Sep 17 00:00:00 2001 From: John-Michael Faircloth Date: Thu, 7 Sep 2023 16:50:57 -0500 Subject: [PATCH] docs: db schedule-based static role rotations (#22863) * docs: db schedule-based static role rotations * fix broken link * add mutual exclusion notice on overview page * prepend slash to relative link --- .../api-docs/secret/databases/index.mdx | 82 +++++++++++++++++-- .../content/docs/secrets/databases/index.mdx | 60 +++++++++++--- 2 files changed, 122 insertions(+), 20 deletions(-) diff --git a/website/content/api-docs/secret/databases/index.mdx b/website/content/api-docs/secret/databases/index.mdx index 96fe415cbdce..7ab3d4e59292 100644 --- a/website/content/api-docs/secret/databases/index.mdx +++ b/website/content/api-docs/secret/databases/index.mdx @@ -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. @@ -498,12 +498,32 @@ this in order to know the password. - `username` `(string: )` – Specifies the database username that this Vault role corresponds to. -- `rotation_period` `(string/int: )` – Specifies the amount of time - Vault should wait before rotating the password. The minimum is 5 seconds. - - `db_name` `(string: )` - 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 @@ -511,7 +531,7 @@ this in order to know the password. @include 'db-secrets-credential-types.mdx' -### Sample payload +### Sample payload with rotation period ```json { @@ -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 @@ -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 { @@ -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 } } ``` @@ -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 { @@ -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 diff --git a/website/content/docs/secrets/databases/index.mdx b/website/content/docs/secrets/databases/index.mdx index 7617317bc2ac..8fdbc7d537fa 100644 --- a/website/content/docs/secrets/databases/index.mdx +++ b/website/content/docs/secrets/databases/index.mdx @@ -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. Do not manage the same root database credentials that you provide to Vault in @@ -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. @@ -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).