Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore: add "Configuring IAM Database Authentication" to README #2353

Merged
merged 3 commits into from
Dec 18, 2024
Merged

chore: add "Configuring IAM Database Authentication" to README #2353

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
8f0944e
chore: add Configuring IAM Database Authentication to README
jackwotherspoon Dec 18, 2024
61abfc0
chore: Update README.md
jackwotherspoon Dec 18, 2024
6416d70
chore: add username character limits
jackwotherspoon Dec 18, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 41 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -338,6 +338,44 @@ 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
and Postgres instances, allowing IAM principal's to authenticate and connect
as database users.

Make sure to configure your [Cloud SQL instance to allow IAM authentication][iam-auth-config]
and to [add your IAM principal as a database user][iam-auth-user].

```shell
./cloud-sql-proxy --auto-iam-authn <INSTANCE_CONNECTION_NAME>
```

> [!IMPORTANT]
>
> Make sure to run the Proxy as the same IAM principal as the database user
> you want to log in as. Only the IAM principal that is attached to the
> [sourced credentials](#credentials) will be able to successfully log in
> via automatic IAM database authentication.
>
> When logging in using an IAM database user, Cloud SQL truncates usernames
> based on the engine type in order to not exceed character limits.
> PostgreSQL's username character limit is 63, while MySQL's is 32.
>
> Cloud SQL IAM database usernames are formatted in the following way:
>
> **Postgres**:
> * For an IAM user account, this is the user's email address.
> * For a service account, it is the service account's email without the
> `.gserviceaccount.com` domain suffix.
>
> **MySQL**:
> * For an IAM user account, this is the user's email address,
> without the `@` or domain name. For example, for `[email protected]`,
> the database user would be `test-user`.
> * For a service account, this is the service account's email address without
> the `@project-id.iam.gserviceaccount.com` suffix.

### Testing Connectivity

The Proxy includes support for a connection test on startup. This test helps
Expand Down Expand Up @@ -712,7 +750,9 @@ By participating in this project you agree to abide by its terms. See
[connection-overview]: https://cloud.google.com/sql/docs/mysql/connect-overview
[contributing]: CONTRIBUTING.md
[health-check-example]: https://github.com/GoogleCloudPlatform/cloudsql-proxy/tree/main/examples/k8s-health-check#cloud-sql-proxy-health-checks
[iam-auth]: https://cloud.google.com/sql/docs/postgres/authentication#automatic
[iam-auth]: https://cloud.google.com/sql/docs/postgres/iam-authentication#auto-iam-auth
[iam-auth-config]: https://cloud.google.com/sql/docs/postgres/create-edit-iam-instances#configure-iam-db-instance
[iam-auth-user]: https://cloud.google.com/sql/docs/postgres/add-manage-iam-users#creating-a-database-user
[pkg-badge]: https://pkg.go.dev/badge/github.com/GoogleCloudPlatform/cloudsql-proxy.svg
[pkg-docs]: https://pkg.go.dev/github.com/GoogleCloudPlatform/cloudsql-proxy
[private-ip]: https://cloud.google.com/sql/docs/mysql/private-ip#requirements_for_private_ip
Expand Down
Loading