To authenticate to an AlloyDB for PostgreSQL instance by using Identity and Access Management (IAM) credentials instead of built-in database passwords, you can sign in with an OAuth 2.0 access token or configure automatic IAM authentication. You can also perform an IAM-based sign-in by using the `psql` command-line client. For an overview of connecting to AlloyDB instances, see [Connection overview](https://docs.cloud.google.com/alloydb/docs/connection-overview.md.txt). ## Before you begin Your project, cluster, instances, and IAM user accounts all require preparation before you can sign in to an AlloyDB instance using IAM credentials. > [!CAUTION] > **Caution:** There is a per-minute sign-in quota for each instance, which includes both successful and unsuccessful sign-ins. When the quota is exceeded, sign-ins are temporarily unavailable. Avoid frequent sign-ins and restrict sign-ins by using authorized networks. For more information, see [Manage IAM authentication](https://docs.cloud.google.com/alloydb/docs/database-users/manage-iam-auth.md.txt). ## Authenticate with an OAuth 2.0 token A user or an application can authenticate with an AlloyDB database by following these steps: 1. If you haven't already done so, [authenticate for the Google Cloud CLI](https://docs.cloud.google.com/sdk/docs/authenticate.md.txt) using the same user or service account that you want to sign in to your AlloyDB instance with. 2. Request an OAuth 2.0 token from Google Cloud using [the `gcloud auth print-access-token` command](https://docs.cloud.google.com/sdk/gcloud/reference/auth/print-access-token): ```bash gcloud auth print-access-token ``` Google Cloud prints an OAuth 2.0 token as the output of this command. For additional security, you can restrict the token for use with only AlloyDB authentication by following these alternative steps: 1. Add the `alloydb.login` scope to your current environment's access credentials using [the `gcloud auth application-default login` command](https://docs.cloud.google.com/sdk/gcloud/reference/auth/application-default/login), if you haven't already done so: ```bash gcloud auth application-default login --scopes=https://www.googleapis.com/auth/alloydb.login,https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/userinfo.email,openid ``` 2. Print a restricted OAuth 2.0 token using [the `gcloud auth application-default print-access-token` command](https://docs.cloud.google.com/sdk/gcloud/reference/auth/application-default/print-access-token), scoping the token only to AlloyDB authentication: ```bash gcloud auth application-default print-access-token --scopes=https://www.googleapis.com/auth/alloydb.login ``` > [!CAUTION] > **Caution:** Treat your OAuth 2.0 token as sensitive information. Either store it securely, or don't store it at all after use. The OAuth 2.0 token lets you---or anyone---make authenticated requests to Google Cloud on your behalf. Treat the token with the same level of security as a password. Either store the token securely, or avoid storing it at all. The example use of `psql` later on this page demonstrates a way to request, use, and discard an OAuth 2.0 token in a single action. 3. Sign in to an AlloyDB instance with standard PostgreSQL techniques, using these credentials: - Present the access token you acquired in the previous step as your password. - For an IAM user account, the database username is the account's full email address. - For an IAM service account, the database username is the account's email address without the `.gserviceaccount.com` suffix. The following `psql` command demonstrates one way to sign in to an IAM user on the command line. It assigns the output of `gcloud auth print-access-token` to the `PGPASSWORD` environment variable, which `psql` subsequently uses as a database login password. ```bash PGPASSWORD=$(gcloud auth print-access-token) psql \ -h INSTANCE_ADDRESS \ -U USERNAME \ -d DATABASE ``` Replace the following: - `INSTANCE_ADDRESS`: the IP address of the AlloyDB instance to connect to. - `USERNAME`: an identifier for the IAM user to authenticate with the instance. For an IAM user account, supply the user account's full email address. For example, `kai@example.com`. For an IAM service account, supply the service account's address *without* the `.gserviceaccount.com` suffix. For example, to specify the service account `my-service@my-project.iam.gserviceaccount.com`, you would use the value `my-service@my-project.iam` here. - `DATABASE`: the name of the database to connect to. Note that `psql` truncates passwords entered on the command line that are longer than 100 characters. To use `psql` with an OAuth 2.0 token as a login password, you must set the `PGPASSWORD` environment variable as demonstrated in this example, rather than manually paste it when prompted. ## Authenticate automatically To automatically authenticate an IAM-based AlloyDB user without the need for an OAuth 2.0 token, you have two options: [AlloyDB Auth Proxy](https://docs.cloud.google.com/alloydb/docs/auth-proxy/connect.md.txt) and [AlloyDB Language Connectors](https://docs.cloud.google.com/alloydb/docs/connect-language-connectors.md.txt). The IAM account that you use to run the proxy client or Language Connectors must be the same account that you added as a database user. For example, if you run your workload using the IAM user account `kai@example.com`, then you can use the proxy client or Language Connectors to automatically authenticate the `kai@example.com` database user without specifying an OAuth 2.0 token. In this example, automatic authentication does not work with any other database user except for `kai@example.com`. ### Auth Proxy Using the Auth Proxy requires running the Auth Proxy client with the `--auto-iam-authn` flag enabled. For more information about running the Auth Proxy, see [Connect using the AlloyDB Auth Proxy](https://docs.cloud.google.com/alloydb/docs/auth-proxy/connect.md.txt). ### Language Connectors Using Language Connectors requires enabling IAM authentication programmatically. For the AlloyDB Python Connector, automatic IAM authentication (`enable_iam_auth=True`) is supported with the `pg8000` and `asyncpg` drivers. There is a corresponding option for each language on [Configure the AlloyDB Language Connectors](https://docs.cloud.google.com/alloydb/docs/connect-language-connectors.md.txt#configure-connectors). ## What's next - [Manage your IAM authentication](https://docs.cloud.google.com/alloydb/docs/database-users/manage-iam-auth.md.txt) - [Troubleshoot IAM authentication](https://docs.cloud.google.com/alloydb/docs/troubleshoot/troubleshoot-iam-auth.md.txt)