From aaa54876c8b94998f9bc124c2bd6e8adbf712e35 Mon Sep 17 00:00:00 2001 From: Vinay Gopalan Date: Mon, 6 Oct 2025 15:22:47 -0700 Subject: [PATCH 1/3] add documentation for oracle --- .../api-docs/secret/databases/index.mdx | 2 +- .../content/docs/secrets/databases/oracle.mdx | 64 +++++++++++++++++++ 2 files changed, 65 insertions(+), 1 deletion(-) diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/index.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/index.mdx index 83814b81c5..3af16727d4 100644 --- a/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/index.mdx +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/index.mdx @@ -551,7 +551,7 @@ this in order to know the password. - `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). This parameter is deprecated in favor of `password`. + DB engines (Postgres, Oracle). This parameter is deprecated in favor of `password`. - `db_name` `(string: )` - The name of the database connection to use for this role. diff --git a/content/vault/v1.21.x (rc)/content/docs/secrets/databases/oracle.mdx b/content/vault/v1.21.x (rc)/content/docs/secrets/databases/oracle.mdx index e6d82cdb8c..b7bae29175 100644 --- a/content/vault/v1.21.x (rc)/content/docs/secrets/databases/oracle.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/secrets/databases/oracle.mdx @@ -156,6 +156,70 @@ you will need to enable ipc_lock capabilities for the plugin binary. See the [Commands](/vault/docs/commands#files) docs for more details. +### Rootless Configuration and Password Rotation for Static Roles + + + +The Oracle database plugin 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 Oracle +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-oracle-database \ +plugin_name="oracle-database-plugin" \ +allowed_roles="my-role" \ +connection_url="{{username}}/{{password}}@//localhost:1521/database-name" \ +self_managed=true +``` + +1. Configure a static role that creates a dedicated connection to a user in the DB with +the `password` parameter: + +```shell-session +$ vault write database/static-roles/my-role \ +db_name="my-oracle-database" \ +username="staticuser" \ +password="password" \ +rotation_period="1h" +``` + +1. Read static credentials: + +```shell-session +$ vault read database/static-creds/my-role +Key Value +--- ----- +last_vault_rotation 2024-09-11T14:15:13.764783-07:00 +password XZY42BVc-UO5bMsbgxrW +rotation_period 1h +ttl 59m55s +username staticuser +``` + ### Connect using SSL If the Oracle server Vault is trying to connect to uses an SSL listener, the database From 54dc9848cb0715466f5dce65756322317cf805a9 Mon Sep 17 00:00:00 2001 From: Vinay Gopalan Date: Tue, 7 Oct 2025 13:52:12 -0700 Subject: [PATCH 2/3] address feedback --- .../api-docs/secret/databases/index.mdx | 2 +- .../content/docs/secrets/databases/oracle.mdx | 103 +++++++++--------- 2 files changed, 55 insertions(+), 50 deletions(-) diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/index.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/index.mdx index 3af16727d4..954173b3d0 100644 --- a/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/index.mdx +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/index.mdx @@ -551,7 +551,7 @@ this in order to know the password. - `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, Oracle). This parameter is deprecated in favor of `password`. + DB engines (Postgres, Oracle). The `self_managed_password` parameter is deprecated in favor of `password`. - `db_name` `(string: )` - The name of the database connection to use for this role. diff --git a/content/vault/v1.21.x (rc)/content/docs/secrets/databases/oracle.mdx b/content/vault/v1.21.x (rc)/content/docs/secrets/databases/oracle.mdx index b7bae29175..9e5107c8d5 100644 --- a/content/vault/v1.21.x (rc)/content/docs/secrets/databases/oracle.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/secrets/databases/oracle.mdx @@ -156,69 +156,74 @@ you will need to enable ipc_lock capabilities for the plugin binary. See the [Commands](/vault/docs/commands#files) docs for more details. -### Rootless Configuration and Password Rotation for Static Roles +### Rootless configuration and password rotation for static roles - +@include 'alerts/enterprise-only.mdx' -The Oracle database plugin 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. +The Oracle database plugin supports static roles (including password rotation) +with a rootless DB connection configuration. -~> 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. +With a rootless configuration you can onboard static DB users and use static +role rotation through Vault without requiring privileged root accounts for +connection configuration. Instead of using a single root connection, each static +role has multiple dedicated connections to the database. We highly recommend +onboarding database users as static roles with the minimum set of privileges +possible. Each static role opens a new connection into the database and granting +minimum privileges helps Vault avoid creating multiple, highly-privileged +connections to an external system. -~> 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 Oracle -DB in order to resolve any errors encountered during rotation. +With rootless connections, Vault can become out of sync with the database user +if out-of-band password rotations occur. To resolve the associated rotation +errors, you need to manually update the password in your external Oracle +database. +Vault does not support dynamic roles/credentials with rootless DB connections. + +## Setup 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/ -``` + ```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. + 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: +1. Configure a connection to your database without root credentials and enable + the rootless workflow using the `self_managed` parameter. For example: -```shell-session -$ vault write database/config/my-oracle-database \ -plugin_name="oracle-database-plugin" \ -allowed_roles="my-role" \ -connection_url="{{username}}/{{password}}@//localhost:1521/database-name" \ -self_managed=true -``` + ```shell-session + $ vault write database/config/my-oracle-database \ + plugin_name="oracle-database-plugin" \ + allowed_roles="my-role" \ + connection_url="{{username}}/{{password}}@//localhost:1521/database-name" \ + self_managed=true + ``` -1. Configure a static role that creates a dedicated connection to a user in the DB with -the `password` parameter: +1. Configure a static role that creates a dedicated connection to a user in + the Oracle database with the `password` parameter. For example: -```shell-session -$ vault write database/static-roles/my-role \ -db_name="my-oracle-database" \ -username="staticuser" \ -password="password" \ -rotation_period="1h" -``` + ```shell-session + $ vault write database/static-roles/my-role \ + db_name="my-oracle-database" \ + username="staticuser" \ + password="password" \ + rotation_period="1h" + ``` -1. Read static credentials: +1. Verify the new static credentials with `vault read`. For example: -```shell-session -$ vault read database/static-creds/my-role -Key Value ---- ----- -last_vault_rotation 2024-09-11T14:15:13.764783-07:00 -password XZY42BVc-UO5bMsbgxrW -rotation_period 1h -ttl 59m55s -username staticuser -``` + ```shell-session + $ vault read database/static-creds/my-role + Key Value + --- ----- + last_vault_rotation 2024-09-11T14:15:13.764783-07:00 + password XZY42BVc-UO5bMsbgxrW + rotation_period 1h + ttl 59m55s + username staticuser + ``` ### Connect using SSL From 41c96c0b031312d364114fa17883dd3a0b920c66 Mon Sep 17 00:00:00 2001 From: Sarah Chavis <62406755+schavis@users.noreply.github.com> Date: Tue, 7 Oct 2025 14:56:07 -0700 Subject: [PATCH 3/3] Apply suggestion from @schavis --- .../vault/v1.21.x (rc)/content/docs/secrets/databases/oracle.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/content/vault/v1.21.x (rc)/content/docs/secrets/databases/oracle.mdx b/content/vault/v1.21.x (rc)/content/docs/secrets/databases/oracle.mdx index 9e5107c8d5..432af58201 100644 --- a/content/vault/v1.21.x (rc)/content/docs/secrets/databases/oracle.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/secrets/databases/oracle.mdx @@ -180,6 +180,7 @@ database. Vault does not support dynamic roles/credentials with rootless DB connections. ## Setup + 1. Enable the database secrets engine if it is not already enabled: ```shell-session