From 02a23eea22f66a45b6525a945d8b10c6b46719bb Mon Sep 17 00:00:00 2001 From: kgala2 Date: Fri, 25 Apr 2025 09:41:31 -0700 Subject: [PATCH 1/4] chore: update README.md to add service account impersonation example --- README.md | 26 +++++++++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 5f4d8cb91..67da2505d 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ The Cloud SQL Auth Proxy has support for: - [Automatic IAM Authentication][iam-auth] (Postgres and MySQL only) - Metrics ([Cloud Monitoring][], [Cloud Trace][], and [Prometheus][]) - [HTTP Healthchecks][health-check-example] -- Service account impersonation +- [Service account impersonation](#configuring-service-account-impersonation) - Separate Dialer functionality released as the [Cloud SQL Go Connector][go connector] - Configuration with [environment variables](#config-environment-variables) - Fully POSIX-compliant flags @@ -343,6 +343,30 @@ query param: > ./cloud-sql-proxy --unix-socket C:\cloudsql myproject:my-region:mysql > ``` +### Configuring Service Account Impersonation + +The Proxy supports [service account impersonation](https://cloud.google.com/iam/docs/impersonating-service-accounts). +This allows the Proxy to act as a different service account, which can be useful +for granting access to resources that are not accessible to the default service +account. + +To use service account impersonation, you must have the +`iam.serviceAccounts.getAccessToken` permission on the service account you want +to impersonate. You can grant this permission by assigning the +`roles/iam.serviceAccountTokenCreator` role to the principal running the Proxy. + +Note: The service account must have Cloud SQL Instance User, Service Usage Consumer and Cloud SQL Client permissions. + +To impersonate a service account, use the `--impersonate-service-account` flag: + +```shell +# Starts a listener on localhost:5432 and impersonates the service account +# "my-other-sa@my-project.iam.gserviceaccount.com". +# The Proxy will use the credentials of the principal running the Proxy to +# generate a short-lived access token for the impersonated service account. +./cloud-sql-proxy --impersonate-service-account my-other-sa@my-project.iam.gserviceaccount.com +``` + ### Configuring IAM Database Authentication The Proxy supports [Automatic IAM Database Authentication][iam-auth] for MySQL From 1d157102a991fddd0842aa1f2ff349472621fd09 Mon Sep 17 00:00:00 2001 From: kgala2 Date: Fri, 25 Apr 2025 11:02:30 -0700 Subject: [PATCH 2/4] chore: rephrase notes section for service account impersonation --- README.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 67da2505d..ac43df1f2 100644 --- a/README.md +++ b/README.md @@ -347,18 +347,19 @@ query param: The Proxy supports [service account impersonation](https://cloud.google.com/iam/docs/impersonating-service-accounts). This allows the Proxy to act as a different service account, which can be useful -for granting access to resources that are not accessible to the default service -account. +for granting access to resources that are not accessible to the default IAM principal. To use service account impersonation, you must have the -`iam.serviceAccounts.getAccessToken` permission on the service account you want -to impersonate. You can grant this permission by assigning the -`roles/iam.serviceAccountTokenCreator` role to the principal running the Proxy. - -Note: The service account must have Cloud SQL Instance User, Service Usage Consumer and Cloud SQL Client permissions. +`iam.serviceAccounts.getAccessToken` permission on the IAM principal. You can grant this permission by assigning the +`roles/iam.serviceAccountTokenCreator` role to the IAM principal. To impersonate a service account, use the `--impersonate-service-account` flag: +> [!NOTE]: +> +> The service account must have `Cloud SQL Instance User`, `Service Usage Consumer` and `Cloud SQL Client permissions`. +> The `roles/iam.serviceAccountTokenCreator` role is not required on the impersonated service account but on the IAM principal impersonating the service account. + ```shell # Starts a listener on localhost:5432 and impersonates the service account # "my-other-sa@my-project.iam.gserviceaccount.com". From 1b6ec1c005beb04563dafb2b8e93142397bc794d Mon Sep 17 00:00:00 2001 From: kgala2 Date: Mon, 28 Apr 2025 11:34:17 -0700 Subject: [PATCH 3/4] chore: update service account impersonation section's notes --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index ac43df1f2..ed3ad0416 100644 --- a/README.md +++ b/README.md @@ -350,15 +350,15 @@ This allows the Proxy to act as a different service account, which can be useful for granting access to resources that are not accessible to the default IAM principal. To use service account impersonation, you must have the -`iam.serviceAccounts.getAccessToken` permission on the IAM principal. You can grant this permission by assigning the +`iam.serviceAccounts.getAccessToken` permission on the IAM principal impersonating another service account. You can grant this permission by assigning the `roles/iam.serviceAccountTokenCreator` role to the IAM principal. To impersonate a service account, use the `--impersonate-service-account` flag: > [!NOTE]: > -> The service account must have `Cloud SQL Instance User`, `Service Usage Consumer` and `Cloud SQL Client permissions`. -> The `roles/iam.serviceAccountTokenCreator` role is not required on the impersonated service account but on the IAM principal impersonating the service account. +> The impersonated service account must have the `Service Usage Consumer` and `Cloud SQL Client` permissions. Additionally, to use IAM Authenticated users, add the `Cloud SQL Instance User` permission. + ```shell # Starts a listener on localhost:5432 and impersonates the service account From 8af1b48ea4f61929e7881fbe7b703de9c61f830c Mon Sep 17 00:00:00 2001 From: kgala2 Date: Wed, 30 Apr 2025 11:26:02 -0700 Subject: [PATCH 4/4] chore: reformat line length --- README.md | 56 +++++++++++++++++++++++++++++++------------------------ 1 file changed, 32 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index ed3ad0416..6e2358dbd 100644 --- a/README.md +++ b/README.md @@ -343,30 +343,6 @@ query param: > ./cloud-sql-proxy --unix-socket C:\cloudsql myproject:my-region:mysql > ``` -### Configuring Service Account Impersonation - -The Proxy supports [service account impersonation](https://cloud.google.com/iam/docs/impersonating-service-accounts). -This allows the Proxy to act as a different service account, which can be useful -for granting access to resources that are not accessible to the default IAM principal. - -To use service account impersonation, you must have the -`iam.serviceAccounts.getAccessToken` permission on the IAM principal impersonating another service account. You can grant this permission by assigning the -`roles/iam.serviceAccountTokenCreator` role to the IAM principal. - -To impersonate a service account, use the `--impersonate-service-account` flag: - -> [!NOTE]: -> -> The impersonated service account must have the `Service Usage Consumer` and `Cloud SQL Client` permissions. Additionally, to use IAM Authenticated users, add the `Cloud SQL Instance User` permission. - - -```shell -# Starts a listener on localhost:5432 and impersonates the service account -# "my-other-sa@my-project.iam.gserviceaccount.com". -# The Proxy will use the credentials of the principal running the Proxy to -# generate a short-lived access token for the impersonated service account. -./cloud-sql-proxy --impersonate-service-account my-other-sa@my-project.iam.gserviceaccount.com -``` ### Configuring IAM Database Authentication @@ -406,6 +382,38 @@ and to [add your IAM principal as a database user][iam-auth-user]. > * For a service account, this is the service account's email address without > the `@project-id.iam.gserviceaccount.com` suffix. + +### Configuring Service Account Impersonation + +The Proxy supports [service account impersonation](https://cloud.google.com/iam/docs/impersonating-service-accounts). +This allows the Proxy to act as a different service account, which can be useful +for granting access to resources that are not accessible to the default IAM +principal. + +To use service account impersonation, you must have the +`iam.serviceAccounts.getAccessToken` permission on the IAM principal +impersonating another service account. You can grant this permission by assigning + the `roles/iam.serviceAccountTokenCreator` role to the IAM principal. + +To impersonate a service account, use the `--impersonate-service-account` flag: + +> [!NOTE] +> +> The impersonated service account must have the `Service Usage Consumer` and +`Cloud SQL Client` permissions. +> Additionally, to use IAM Authenticated users, add the `Cloud SQL Instance User` + permission. + + +```shell +# Starts a listener on localhost:5432 and impersonates the service account +# "my-other-sa@my-project.iam.gserviceaccount.com". +# The Proxy will use the credentials of the principal running the Proxy to +# generate a short-lived access token for the impersonated service account. +./cloud-sql-proxy --impersonate-service-account \ +my-other-sa@my-project.iam.gserviceaccount.com +``` + ### Configuring DNS domain names to identify instances The Proxy can be configured to use DNS to look up an instance. This would