diff --git a/website/content/api-docs/secret/databases/index.mdx b/website/content/api-docs/secret/databases/index.mdx index e788d452ed91..9b15d1d62241 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 } } ``` @@ -534,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. @@ -570,6 +582,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 +660,8 @@ $ curl \ "rotation_statements": [ "ALTER USER \"{{name}}\" IDENTIFIED BY '{{password}}';" ], - "rotation_period": 3600 + "rotation_period": 3600, + "skip_import_rotation": false } } ``` @@ -658,7 +678,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 9b682ed7624b..405dd9a4f0ad 100644 --- a/website/content/docs/secrets/databases/index.mdx +++ b/website/content/docs/secrets/databases/index.mdx @@ -31,6 +31,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 @@ -183,6 +191,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