From fc3fb91a4063d94566e8305bddd28ced2c296862 Mon Sep 17 00:00:00 2001 From: hc-github-team-secure-vault-core <82990506+hc-github-team-secure-vault-core@users.noreply.github.com> Date: Fri, 8 Sep 2023 19:33:21 -0400 Subject: [PATCH] backport of commit 2b74a4826b09f716902485044986d1fd95ac77cf (#22953) Co-authored-by: vinay-gopalan <86625824+vinay-gopalan@users.noreply.github.com> --- .../api-docs/secret/databases/mysql-maria.mdx | 11 +++- .../api-docs/secret/databases/postgresql.mdx | 15 ++++-- .../content/docs/secrets/databases/index.mdx | 4 +- .../docs/secrets/databases/mysql-maria.mdx | 53 +++++++++++++++++++ .../docs/secrets/databases/postgresql.mdx | 51 ++++++++++++++++++ 5 files changed, 126 insertions(+), 8 deletions(-) diff --git a/website/content/api-docs/secret/databases/mysql-maria.mdx b/website/content/api-docs/secret/databases/mysql-maria.mdx index 685e4c3289..bdce2662bd 100644 --- a/website/content/api-docs/secret/databases/mysql-maria.mdx +++ b/website/content/api-docs/secret/databases/mysql-maria.mdx @@ -46,16 +46,23 @@ has a number of parameters to further configure a connection. - `password` `(string: "")` - The root credential password used in the connection URL. +- `auth_type` `(string: "")` - If set to `gcp_iam`, will enable IAM authentication to a Google + CloudSQL instance. For more information on authenticating to CloudSQL via IAM, please refer to + Google's official documentation [here.](https://cloud.google.com/sql/docs/postgres/authentication). + +- `service_account_json` `(string: "")` - JSON encoded credentials for a GCP Service Account to use + for IAM authentication. Requires `auth_type` to be `gcp_iam`. + - `tls_certificate_key` `(string: "")` - x509 certificate for connecting to the database. This must be a PEM encoded version of the private key and the certificate combined. - `tls_ca` `(string: "")` - x509 CA file for validating the certificate presented by the MySQL server. Must be PEM encoded. -- `tls_server_name` `(string: "")` - Specifies the subject alternative name should be present in the +- `tls_server_name` `(string: "")` - Specifies the subject alternative name should be present in the server's certificate. -- `tls_skip_verify` `(boolean: false)` - When set to true, disables the server certificate verification. +- `tls_skip_verify` `(boolean: false)` - When set to true, disables the server certificate verification. Setting this to true is not recommended for production. - `username_template` `(string)` - [Template](/vault/docs/concepts/username-templating) describing how diff --git a/website/content/api-docs/secret/databases/postgresql.mdx b/website/content/api-docs/secret/databases/postgresql.mdx index 636cd287a6..894fd81454 100644 --- a/website/content/api-docs/secret/databases/postgresql.mdx +++ b/website/content/api-docs/secret/databases/postgresql.mdx @@ -27,11 +27,11 @@ has a number of parameters to further configure a connection. - `connection_url` `(string: )` - Specifies the PostgreSQL DSN. This field can be templated and supports passing the username and password parameters in the following format `{{field_name}}`. Certificate authentication - can be used by setting `?sslmode=` to be any of the applicable values as outlined in + can be used by setting `?sslmode=` to be any of the applicable values as outlined in the [Postgres SQL documentation](https://www.postgresql.org/docs/11/libpq-ssl.html#LIBPQ-SSL-PROTECTION) - and giving the SSL credentials in the `sslrootcert`, `sslcert` and `sslkey` credentials. - A templated connection URL is required when using root credential rotation. This field - supports both format string types, URI and keyword/value. Both formats support multiple + and giving the SSL credentials in the `sslrootcert`, `sslcert` and `sslkey` credentials. + A templated connection URL is required when using root credential rotation. This field + supports both format string types, URI and keyword/value. Both formats support multiple host connection strings. Due to how `pgx` works, parameters such as `sslrootcert`, `sslcert`, `sslkey` are treated as paths on the Vault server. @@ -51,6 +51,13 @@ has a number of parameters to further configure a connection. - `password` `(string: "")` - The root credential password used in the connection URL. +- `auth_type` `(string: "")` - If set to `gcp_iam`, will enable IAM authentication to a Google + CloudSQL instance. For more information on authenticating to CloudSQL via IAM, please refer to + Google's official documentation [here.](https://cloud.google.com/sql/docs/postgres/authentication). + +- `service_account_json` `(string: "")` - JSON encoded credentials for a GCP Service Account to use + for IAM authentication. Requires `auth_type` to be `gcp_iam`. + - `username_template` `(string)` - [Template](/vault/docs/concepts/username-templating) describing how dynamic usernames are generated. diff --git a/website/content/docs/secrets/databases/index.mdx b/website/content/docs/secrets/databases/index.mdx index 8fdbc7d537..49427677d8 100644 --- a/website/content/docs/secrets/databases/index.mdx +++ b/website/content/docs/secrets/databases/index.mdx @@ -163,9 +163,9 @@ and private key pair to authenticate. | [MongoDB](/vault/docs/secrets/databases/mongodb) | Yes | Yes | Yes | Yes (1.7+) | password | | [MongoDB Atlas](/vault/docs/secrets/databases/mongodbatlas) | No | Yes | Yes | Yes (1.8+) | password, client_certificate | | [MSSQL](/vault/docs/secrets/databases/mssql) | Yes | Yes | Yes | Yes (1.7+) | password | -| [MySQL/MariaDB](/vault/docs/secrets/databases/mysql-maria) | Yes | Yes | Yes | Yes (1.7+) | password | +| [MySQL/MariaDB](/vault/docs/secrets/databases/mysql-maria) | Yes | Yes | Yes | Yes (1.7+) | password, gcp_iam | | [Oracle](/vault/docs/secrets/databases/oracle) | Yes | Yes | Yes | Yes (1.7+) | password | -| [PostgreSQL](/vault/docs/secrets/databases/postgresql) | Yes | Yes | Yes | Yes (1.7+) | password | +| [PostgreSQL](/vault/docs/secrets/databases/postgresql) | Yes | Yes | Yes | Yes (1.7+) | password, gcp_iam | | [Redis](/vault/docs/secrets/databases/redis) | Yes | Yes | Yes | No | password | | [Redis ElastiCache](/vault/docs/secrets/databases/rediselasticache) | No | No | Yes | No | password | | [Redshift](/vault/docs/secrets/databases/redshift) | Yes | Yes | Yes | Yes (1.8+) | password | diff --git a/website/content/docs/secrets/databases/mysql-maria.mdx b/website/content/docs/secrets/databases/mysql-maria.mdx index a101da85f6..becab0f2b7 100644 --- a/website/content/docs/secrets/databases/mysql-maria.mdx +++ b/website/content/docs/secrets/databases/mysql-maria.mdx @@ -166,3 +166,56 @@ API](/vault/api-docs/secret/databases/mysql-maria) page. For more information on the database secrets engine's HTTP API please see the [Database secrets engine API](/vault/api-docs/secret/databases) page. + +## Authenticating to Cloud DBs via IAM + +### Google Cloud + +Aside from IAM roles denoted by [Google's CloudSQL documentation](https://cloud.google.com/sql/docs/postgres/add-manage-iam-users#creating-a-database-user), +the following SQL privileges are needed by the service account's DB user for minimum functionality with Vault. +Additional privileges may be needed depending on the SQL configured on the database roles. + +```sql +-- Enable service account to create roles within DB +GRANT CREATEROLE ON . TO "test-user"@"%"; +``` + +### 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/ + ``` + + 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 Vault with the proper plugin and connection information. Here you can explicitly enable GCP IAM authentication + and use [Application Default Credentials](https://cloud.google.com/docs/authentication/provide-credentials-adc#how-to) to authenticate. + + ~> **Note**: For Google Cloud IAM, the Protocol is `cloudsql-mysql` instead of `tcp`. + + ```shell-session + $ vault write database/config/my-mysql-database \ + plugin_name="mysql-database-plugin" \ + allowed_roles="my-role" \ + connection_url="user@cloudsql-mysql(project:region:instance)/mysql" \ + auth_type="gcp_iam" + ``` + + You can also configure the connection and authenticate by directly passing in the service account credentials + as an encoded JSON string: + + ```shell-session + $ vault write database/config/my-mysql-database \ + plugin_name="mysql-database-plugin" \ + allowed_roles="my-role" \ + connection_url="user@cloudsql-mysql(project:region:instance)/mysql" \ + auth_type="gcp_iam" \ + service_account_json="@my_credentials.json" + ``` + +Once the connection has been configured and IAM authentication is complete, the steps to set up a role and generate +credentials are the same as the ones listed above. diff --git a/website/content/docs/secrets/databases/postgresql.mdx b/website/content/docs/secrets/databases/postgresql.mdx index c1bcb8b77d..70186f5c03 100644 --- a/website/content/docs/secrets/databases/postgresql.mdx +++ b/website/content/docs/secrets/databases/postgresql.mdx @@ -94,3 +94,54 @@ For more information on the database secrets engine's HTTP API please see the [pgxlib]: https://pkg.go.dev/github.com/jackc/pgx/stdlib [pg_conn_docs]: https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING + +## Authenticating to Cloud DBs via IAM + +### Google Cloud + +Aside from IAM roles denoted by [Google's CloudSQL documentation](https://cloud.google.com/sql/docs/postgres/add-manage-iam-users#creating-a-database-user), +the following SQL privileges are needed by the service account's DB user for minimum functionality with Vault. +Additional privileges may be needed depending on the SQL configured on the database roles. + +```sql +-- Enable service account to create roles within DB +ALTER USER "" WITH CREATEROLE; +``` + +### 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/ + ``` + + 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 Vault with the proper plugin and connection information. Here you can explicitly enable GCP IAM authentication + and use [Application Default Credentials](https://cloud.google.com/docs/authentication/provide-credentials-adc#how-to) to authenticate: + + ```shell-session + $ vault write database/config/my-postgresql-database \ + plugin_name="postgresql-database-plugin" \ + allowed_roles="my-role" \ + connection_url="host=project:us-west1:mydb user=test-user@project.iam dbname=postgres sslmode=disable" \ + auth_type="gcp_iam" + ``` + + You can also configure the connection and authenticate by directly passing in the service account credentials + as an encoded JSON string: + + ```shell-session + $ vault write database/config/my-postgresql-database \ + plugin_name="postgresql-database-plugin" \ + allowed_roles="my-role" \ + connection_url="host=project:region:instance user=test-user@project.iam dbname=postgres sslmode=disable" \ + auth_type="gcp_iam" \ + service_account_json="@my_credentials.json" + ``` + +Once the connection has been configured and IAM authentication is complete, the steps to set up a role and generate +credentials are the same as the ones listed above.