diff --git a/website/content/api-docs/secret/databases/index.mdx b/website/content/api-docs/secret/databases/index.mdx index 2373410a04..e788d452ed 100644 --- a/website/content/api-docs/secret/databases/index.mdx +++ b/website/content/api-docs/secret/databases/index.mdx @@ -534,6 +534,11 @@ this in order to know the password. - `username` `(string: )` – Specifies the database username that this Vault role corresponds to. +- `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_name` `(string: )` - The name of the database connection to use for this role. diff --git a/website/content/api-docs/secret/databases/postgresql.mdx b/website/content/api-docs/secret/databases/postgresql.mdx index 0094422000..9ddfece16c 100644 --- a/website/content/api-docs/secret/databases/postgresql.mdx +++ b/website/content/api-docs/secret/databases/postgresql.mdx @@ -51,6 +51,10 @@ has a number of parameters to further configure a connection. - `password` `(string: "")` - The root credential password used in the connection URL. +- `self_managed` `(boolean: "false")` - If + set, allows onboarding static roles with a rootless connection configuration. Mutually + exclusive with `username` and `password`. If set, will force `verify_connection` to be false. + - `tls_ca` `(string: "")` - The x509 CA file for validating the certificate presented by the PostgreSQL server. Must be PEM encoded. diff --git a/website/content/docs/secrets/databases/postgresql.mdx b/website/content/docs/secrets/databases/postgresql.mdx index e9efbb1de1..2193ffc399 100644 --- a/website/content/docs/secrets/databases/postgresql.mdx +++ b/website/content/docs/secrets/databases/postgresql.mdx @@ -24,9 +24,9 @@ options, including SSL options, can be found in the [pgx][pgxlib] and ## Capabilities -| Plugin Name | Root Credential Rotation | Dynamic Roles | Static Roles | Username Customization | -| ---------------------------- | ------------------------ | ------------- | ------------ | ---------------------- | -| `postgresql-database-plugin` | Yes | Yes | Yes | Yes (1.7+) | +| Plugin Name | Root Credential Rotation | Dynamic Roles | Static Roles | Username Customization | Credential Types | +| ---------------------------- | ------------------------ | ------------- | ------------ | ---------------------- | ---------------------------- | +| `postgresql-database-plugin` | Yes | Yes | Yes | Yes (1.7+) | password, gcp_iam | ## Setup @@ -84,6 +84,70 @@ the proper permission, it can generate credentials. username v-vaultuse-my-role-x ``` +## Rootless Configuration and Password Rotation for Static Roles + + + +The PostgreSQL secrets engine supports using Static Roles and its password rotation mechanisms with a Rootless +DB connection configuration. In this workflow, a static DB user can be onboarded onto Vault's static role rotation +mechanism without the need of privileged root accounts to configure the connection. Instead of using a single root +connection, multiple dedicated connections to the DB are made for each static role. This workflow does not support +dynamic roles/credentials. + +~> Note: It is **highly recommended** that the DB users being onboarded as static roles +have the minimum set of privileges. Each static role will open a new connection into the DB. +Granting minimum privileges to the DB users being onboarded ensures that multiple +highly-privileged connections to an external system are not being made. + +~> Note: Out-of-band password rotations will cause Vault to be out of sync with the state of +the DB user, and will require manually updating the user's password in the external PostgreSQL +DB in order to resolve any errors encountered during rotation. + +1. Enable the database secrets engine if it is not already enabled: + + ```shell-session + $ vault secrets enable database + Success! Enabled the database secrets engine at: database/ + ``` + + By default, the secrets engine will enable at the name of the engine. To + enable the secrets engine at a different path, use the `-path` argument. + +1. Configure connection to DB without root credentials and enable the rootless + workflow by setting the `self_managed` parameter: + + ```shell-session + $ vault write database/config/my-postgresql-database \ + plugin_name="postgresql-database-plugin" \ + allowed_roles="my-role" \ + connection_url="postgresql://{{username}}:{{password}}@localhost:5432/database-name" \ + self_managed=true + ``` + +1. Configure a static role that creates a dedicated connection to a user in the DB with + the `self_managed_password` parameter: + + ```shell-session + $ vault write database/static-roles/my-static-role \ + db_name="my-postgresql-database" \ + username="staticuser" \ + self_managed_password="password" \ + rotation_period="1h" + ``` + +1. Read static credentials: + + ```shell-session + $ vault read database/static-creds/static-test + Key Value + --- ----- + last_vault_rotation 2024-09-11T14:15:13.764783-07:00 + password XZY42BVc-UO5bMsbgxrW + rotation_period 1h + ttl 59m55s + username staticuser + ``` + ## Client x509 certificate authentication This plugin supports using PostgreSQl's [x509 Client-side Certificate Authentication](https://www.postgresql.org/docs/16/libpq-ssl.html#LIBPQ-SSL-CLIENTCERT).