Manage IAM authentication

Stay organized with collections Save and categorize content based on your preferences.

This page explains how to prepare your AlloyDB for PostgreSQL instance to let database authentication through Identity and Access Management (IAM).

IAM authentication complements database authentication through standard PostgreSQL users, which every AlloyDB cluster supports. If you enable IAM authentication on your cluster, then you can use either IAM or PostgreSQL user roles to authenticate with that cluster.

By default, an AlloyDB instance does not have IAM authentication enabled. To enable IAM authentication, complete the following steps:

• Manually enable IAM authentication on every instance that IAM user or service accounts need to connect to.

• For every IAM user or service account that needs to sign in as a database user, complete the following steps:

  1. Using IAM administrator tools, grant that user or service account the alloydb.databaseUser and serviceusage.serviceUsageConsumer roles.

  2. Using the Google Cloud CLI, create a database user corresponding to that user or service account on your AlloyDB cluster.

  3. Using a database administrator account such as postgres, grant the new database user access privileges to the appropriate database tables.

You can repeat these steps whenever you need to add further IAM users to your AlloyDB cluster.

Enable or disable IAM authentication

To enable IAM authentication on an instance, set the alloydb.iam_authentication flag on that instance to on.

To disable IAM authentication on an instance, set alloydb.iam_authentication back to its default value, off.

For more information about setting flags on AlloyDB instances, see Configure an instance's database flags.

Grant an IAM user or service account access to an instance

Enabling IAM access to a new database user is a two-step process:

1. Update your project's IAM settings to grant AlloyDB database access to the appropriate IAM user or service account.

2. Create a new database user on your cluster, setting the username as the email address of the IAM user or service account.

You can repeat step two to give an IAM account access to other clusters inside your project.

Update an IAM account with the appropriate role

You can give IAM users or service accounts the ability to authenticate with AlloyDB instances by granting them the following IAM roles:

• alloydb.databaseUser: Lets the user connect to your AlloyDB instance.
• serviceusage.serviceUsageConsumer: Provides the user access to an API that checks permissions.

To do this, follow the instructions on Grant access to other users. In the step where you select a role to grant to the IAM principal, choose alloydb.databaseUser.

Add an IAM user or service account to a cluster

gcloud alloydb users create USERNAME \
--cluster=CLUSTER \
--region=REGION \
--type=IAM_BASED

Grant appropriate database permissions to IAM users

When an IAM user is added to a database instance, that new user is granted no privileges on any databases by default.

When a user or service account connects to a database, they can run queries against any database objects whose access has been granted to PUBLIC.

If they need additional access, more privileges can be granted using the GRANT PostgreSQL statement.

GRANT SELECT ON TABLE_NAME TO "USERNAME";

Replace the following variables:

• USERNAME: Email address for the user. You must include double quotes around the address.

• TABLE_NAME: Name of the table you want to give the user access to.

Remove an IAM user or service account from a cluster

gcloud alloydb users delete USERNAME \
--cluster=CLUSTER \
--region=REGION

What's next

• Connect using an IAM account