From c72192cb4d994ab1c0a528b899ab461e5cb3728b Mon Sep 17 00:00:00 2001 From: Jack Wotherspoon Date: Tue, 16 Jan 2024 12:29:51 -0500 Subject: [PATCH] docs: document auto IAM authn in README (#211) --- README.md | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/README.md b/README.md index 5e9a22f3..1d848b7c 100644 --- a/README.md +++ b/README.md @@ -25,6 +25,11 @@ Using an AlloyDB Connector provides the following benefits: * **Convenience:** removes the requirement to use and distribute SSL certificates, as well as manage firewalls or source/destination IP addresses. +* (optionally) **IAM DB Authentication:** provides support for + [AlloyDB’s automatic IAM DB AuthN][iam-db-authn] feature. + +[iam-db-authn]: https://cloud.google.com/alloydb/docs/manage-iam-authn + The AlloyDB Python Connector is a package to be used alongside a database driver. Currently supported drivers are: @@ -326,6 +331,40 @@ async def main(): await pool.dispose() ``` +### Automatic IAM Database Authentication + +The Python Connector supports [Automatic IAM database authentication][]. + +Make sure to [configure your AlloyDB Instance to allow IAM authentication][configure-iam-authn] +and [add an IAM database user][add-iam-user]. + +A `Connector` or `AsyncConnector` can be configured to connect to an AlloyDB instance using +automatic IAM database authentication with the `enable_iam_auth` argument set to `True`. + +When configuring the `connector.connect` call for IAM authentication, the `password` field can be +omitted and the `user` field should be formatted as follows: + +* 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. + +For example, to connect with IAM authentication using the +`test-sa@test-project.iam.gserviceaccount.com` service account: + +```python +connector.connect( + "projects//locations//clusters//instances/", + "pg8000", # asyncpg for AsyncConnector + user="test-sa@test-project.iam", + db="my-db-name", + enable_iam_auth=True, +) +``` + +[Automatic IAM database authentication]: https://cloud.google.com/alloydb/docs/manage-iam-authn +[configure-iam-authn]: https://cloud.google.com/alloydb/docs/manage-iam-authn#enable +[add-iam-user]: https://cloud.google.com/alloydb/docs/manage-iam-authn#create-user + ## Support policy ### Major version lifecycle