From 13bc86f0eda5a5d2d0f178a266eb366f6395c1e2 Mon Sep 17 00:00:00 2001 From: JM Faircloth Date: Wed, 4 Dec 2024 16:18:54 -0600 Subject: [PATCH 1/3] docs: DB skip auto import rotation --- .../api-docs/secret/databases/index.mdx | 20 +++++++++++++++++-- .../content/docs/secrets/databases/index.mdx | 8 ++++++++ 2 files changed, 26 insertions(+), 2 deletions(-) diff --git a/website/content/api-docs/secret/databases/index.mdx b/website/content/api-docs/secret/databases/index.mdx index e788d452ed91..cecd0d9ba6cb 100644 --- a/website/content/api-docs/secret/databases/index.mdx +++ b/website/content/api-docs/secret/databases/index.mdx @@ -55,6 +55,12 @@ list of additional parameters. for this database. If not specified, this will use a default policy defined as: 20 characters with at least 1 uppercase, 1 lowercase, 1 number, and 1 dash character. +- `skip_static_role_import_rotation` `(bool: false)` – + Specifies if a given static account's password should be rotated on creation + of the static roles associated with this database config. This is can be + overridden at the role-level by the static role's [skip_import_rotation](#skip_import_rotation) + field. The default is false. + ~> 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 @@ -173,6 +179,7 @@ $ curl \ "plugin_name": "mysql-database-plugin", "plugin_version": "", "root_credentials_rotate_statements": [] + "skip_static_role_import_rotation": false } } ``` @@ -570,6 +577,13 @@ this in order to know the password. plugin type will support this functionality. See the plugin's API page for more information on support and formatting for this parameter. +- `skip_import_rotation` `(bool: false)` – + Specifies if the static account's password should be rotated on creation of + the static role. This overrides the config-level field + [skip_static_role_import_rotation](#skip_static_role_import_rotation). The + default is false. + + @include 'db-secrets-credential-types.mdx' ### Sample payload with rotation period @@ -641,7 +655,8 @@ $ curl \ "rotation_statements": [ "ALTER USER \"{{name}}\" IDENTIFIED BY '{{password}}';" ], - "rotation_period": 3600 + "rotation_period": 3600, + "skip_import_rotation": false } } ``` @@ -658,7 +673,8 @@ $ curl \ "ALTER USER \"{{name}}\" IDENTIFIED BY '{{password}}';" ], "rotation_schedule": "0 0 * * SAT", - "rotation_window": 3600 + "rotation_window": 3600, + "skip_import_rotation": false } } ``` diff --git a/website/content/docs/secrets/databases/index.mdx b/website/content/docs/secrets/databases/index.mdx index 223c0a531c02..7b5695b13613 100644 --- a/website/content/docs/secrets/databases/index.mdx +++ b/website/content/docs/secrets/databases/index.mdx @@ -34,6 +34,14 @@ static roles, Vault stores and automatically rotates passwords for the associated database user based on a configurable period of time or rotation schedule. +When the database user is onboarded into Vault via the +[Create static role](/vault/api-docs/secret/databases#create-static-role) API, +the user's password is automatically rotated. Automatic rotation can be +disabled for all roles at the config-level with the +[skip_static_role_import_rotation](/vault/api-docs/secret/databases#skip_static_role_import_rotation) +field or per role with the [skip_import_rotation](/vault/api-docs/secret/databases#skip_import_rotation) +field. + 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 From 298e2719e80ec94e6a55aa347a77fd8c66ad645a Mon Sep 17 00:00:00 2001 From: JM Faircloth Date: Mon, 9 Dec 2024 17:11:00 -0600 Subject: [PATCH 2/3] add usage section --- .../content/docs/secrets/databases/index.mdx | 23 +++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/website/content/docs/secrets/databases/index.mdx b/website/content/docs/secrets/databases/index.mdx index 7b5695b13613..93505f324430 100644 --- a/website/content/docs/secrets/databases/index.mdx +++ b/website/content/docs/secrets/databases/index.mdx @@ -194,6 +194,29 @@ 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. +## Onboarding static database users + +When a static database user is onboarded to the database secrets engine, by +default Vault immediately and automatically rotates the database user's +password. This immediate rotation can add additional operational overhead to +the onboarding process and has proven challenging for some organizations. To +address these challenges, you can configure one or more of the following options: + +- Disable the automatic rotation of static role passwords during Vault + onboarding. This will allow you to enroll the static database user in Vault before + you do the actual cutover of the application to consume the credential from + Vault. You can configure this for all roles associated with a database connection with + [skip_static_role_import_rotation](/vault/api-docs/secret/databases#skip_static_role_import_rotation) + or on a per-role basis with [skip_import_rotation](/vault/api-docs/secret/databases#skip_import_rotation). + +- Set the initial static role password during Vault onboarding. Setting the + static role's [password](/vault/api-docs/secret/databases#password) + gives you the ability to retrieve the static user's existing password + after onboarding and before the first rotation. This capability enables Vault + to be ready for the client application when it begins to look to Vault for + its passwords, and enables multiple clients using the same static role to + transition slowly. + ## Schedule-based static role rotation The database secrets engine supports configuring schedule-based automatic From 6aa6766797b022e4c43b960f2c35d456b47fd3fa Mon Sep 17 00:00:00 2001 From: JM Faircloth Date: Mon, 6 Jan 2025 10:23:39 -0600 Subject: [PATCH 3/3] add password field; mark self_managed_password as deprecated --- website/content/api-docs/secret/databases/index.mdx | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/website/content/api-docs/secret/databases/index.mdx b/website/content/api-docs/secret/databases/index.mdx index cecd0d9ba6cb..9b15d1d62241 100644 --- a/website/content/api-docs/secret/databases/index.mdx +++ b/website/content/api-docs/secret/databases/index.mdx @@ -541,10 +541,15 @@ this in order to know the password. - `username` `(string: )` – Specifies the database username that this Vault role corresponds to. +- `password` `(string)` – + The password corresponding to the username in the database. Required when using + the Rootless Password Rotation workflow or the Skip Automatic Import Rotation + workflow for static roles. + - `self_managed_password` `(string)` – The password corresponding to the username in the database. Required when using the Rootless Password Rotation workflow for static roles. Only enabled for select - DB engines (Postgres). + DB engines (Postgres). This parameter is deprecated in favor of `password`. - `db_name` `(string: )` - The name of the database connection to use for this role.