From fd0521780db745a6140ecbbafb2346ba227f7931 Mon Sep 17 00:00:00 2001 From: Jim Bishopp Date: Thu, 3 Feb 2022 13:55:07 -0800 Subject: [PATCH] [v8] Update Documentation for GCP Cloud SQL Client Authentication Update docs for #9991. --- .../database-access/guides/mysql-cloudsql.mdx | 19 ++++++-- .../guides/postgres-cloudsql.mdx | 48 ++++++++++++++----- 2 files changed, 53 insertions(+), 14 deletions(-) diff --git a/docs/pages/database-access/guides/mysql-cloudsql.mdx b/docs/pages/database-access/guides/mysql-cloudsql.mdx index 3d00fbddd7685..accdad31983e1 100644 --- a/docs/pages/database-access/guides/mysql-cloudsql.mdx +++ b/docs/pages/database-access/guides/mysql-cloudsql.mdx @@ -5,19 +5,23 @@ description: How to configure Teleport Database Access with GCP Cloud SQL MySQL. # GCP Cloud SQL MySQL -## Create service account for Teleport Database service +## Create a service account for the Teleport Database Service Teleport uses one-time passwords to authenticate with Cloud SQL MySQL. To be able to authenticate with a database instance, Teleport must run as a service account that has a few of the "Cloud SQL Admin" role permissions. You can create a new service account, or modify an existing one to add required permissions. +### Create a service account + If creating a new one, go to the [Service Accounts](https://console.cloud.google.com/iam-admin/serviceaccounts) page and create another service account: ![Create Service Account](../../../img/database-access/guides/cloudsql/service-account-db-service@2x.png) -Assign it the "Cloud SQL Admin" role: +### Grant permissions + +Assign the Service Account the "Cloud SQL Admin" role: ![Grant Cloud SQL Admin to Service Account](../../../img/database-access/guides/cloudsql/service-account-sql-admin-grant@2x.png) @@ -26,12 +30,21 @@ Assign it the "Cloud SQL Admin" role: database agent needs to generate one-time user passwords. To further restrict the service account, you can create a role that includes only the following permissions: - ```text + ```ini + # Used to download a list of database users. cloudsql.users.list + # Used to update a user with a one-time password. cloudsql.users.update + # Used to auto-download the instance's root CA certificate. + cloudsql.instances.get + # Used to generate an ephemeral client certificate when the GCP instance + # is configured to "Allow only SSL connections." (optional) + cloudsql.sslCerts.createEphemeral ``` +### Create a key for the service account + Once created, go to that service account's Keys tab and create a new key: ![Service Account Keys](../../../img/database-access/guides/cloudsql/service-account-keys@2x.png) diff --git a/docs/pages/database-access/guides/postgres-cloudsql.mdx b/docs/pages/database-access/guides/postgres-cloudsql.mdx index c02cd79887e9c..871616828ad77 100644 --- a/docs/pages/database-access/guides/postgres-cloudsql.mdx +++ b/docs/pages/database-access/guides/postgres-cloudsql.mdx @@ -26,10 +26,12 @@ If it isn't enabled, you can add this flag using the "Edit configuration" dialog at the bottom of the Configuration panel. Note, changing this setting may require a database instance reboot. -## Create service account for database +## Create a service account for the database Teleport uses service accounts to connect to Cloud SQL databases. +### Create a service account + Go to the IAM & Admin [Service Accounts](https://console.cloud.google.com/iam-admin/serviceaccounts) page and create a new service account: @@ -37,6 +39,8 @@ page and create a new service account: Press "Create". +### Grant permissions + On the second step grant this service account the "Cloud SQL Instance User" role which will allow it to connect to Cloud SQL instances using IAM token for authentication: @@ -45,6 +49,8 @@ authentication: Press "Done". +### Configure authentication for your service account + Now go back to the Users page of your Cloud SQL instance and add a new user account. In the sidebar, choose "Cloud IAM" authentication type and add the service account you've just created: @@ -58,38 +64,58 @@ Press "Add" and your Users table should look similar to this: See [Creating and managing IAM users](https://cloud.google.com/sql/docs/postgres/create-manage-iam-users) in Google Cloud documentation for more info. -## Create service account for Teleport Database service +## Create a service account for Teleport Database Service The final part of GCP configuration is to create a service account for the -Teleport Database service with the following IAM roles: +Teleport Database Service. -- "Service Account Token Creator": will allow Database service to generate - IAM auth tokens when connecting to the database as the service account user - we created above. -- "Cloud SQL Viewer": will allow Database service to automatically download - your Cloud SQL instance root CA certificate. + +### Create a service account If creating a new one, go to the [Service Accounts](https://console.cloud.google.com/iam-admin/serviceaccounts) page and create another service account: ![Create Service Account](../../../img/database-access/guides/cloudsql/service-account-db-service@2x.png) +### Grant permissions + +Assign the Service Account the following IAM roles: + +- "Service Account Token Creator" will allow the Database Service to generate + IAM authentication tokens when connecting to the database as the service account user + we created above. +- Either "Cloud SQL Viewer" or "Cloud SQL Admin": + - "Cloud SQL Viewer" will allow the Database Service to automatically download + your Cloud SQL instance's root CA certificate, but does not support client + certificate authentication. + - "Cloud SQL Admin" will allow the Database Service to automatically download + your Cloud SQL instance's root CA certificate and generate an + ephemeral client certificate when the GCP instance is configured to + "Allow only SSL connections." + Assign it the "Service Account Token Creator" role: ![Grant Service Account Token Creator to Service Account](../../../img/database-access/guides/cloudsql/service-account-db-service-grant@2x.png) - "Service Account Token Creator" and "Cloud SQL Viewer" IAM roles include more - permissions than the database agent needs. To further restrict the service - account, you can create a role that includes only the following permission: + "Service Account Token Creator", "Cloud SQL Viewer", and "Cloud SQL Admin" + IAM roles include more permissions than the database agent needs. To further + restrict the service account, you can create a role that includes only the + following permissions: ```ini # Used to generate IAM auth tokens when connecting to a database instance. iam.serviceAccounts.getAccessToken # Used to auto-download the instance's root CA certificate. cloudsql.instances.get + # Used to generate an ephemeral client certificate when the GCP instance + # is configured to "Allow only SSL connections." (optional) + cloudsql.sslCerts.createEphemeral ``` + +### Create a key for the service account + Once created, go to that service account's Keys tab and create a new key: ![Service Account Keys](../../../img/database-access/guides/cloudsql/service-account-keys@2x.png)