diff --git a/README.md b/README.md index 5f4d8cb91..6e2358dbd 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,7 @@ query param: > ./cloud-sql-proxy --unix-socket C:\cloudsql myproject:my-region:mysql > ``` + ### Configuring IAM Database Authentication The Proxy supports [Automatic IAM Database Authentication][iam-auth] for MySQL @@ -381,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