Manage IAM authentication

This page shows you how to prepare your AlloyDB for PostgreSQL resources to allow database authentication through Identity and Access Management (IAM).

This method complements database authentication through standard PostgreSQL user roles, which every AlloyDB cluster supports. If you enable IAM-based 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-based authentication enabled. You can take steps to enable IAM logins, and set up separate IAM-based database users:

• You must 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 log in as a database user, you must 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 the latter steps as often as necessary, whenever you need to add further IAM users to your AlloyDB cluster.

The rest of this page explains these steps in further detail.

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 of 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-authenticated 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 the second step as often as necessary to give an IAM-defined 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
• serviceusage.serviceUsageConsumer

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

Console

1. Go to the Clusters page.

   Go to Clusters

2. Click the name of the cluster that you want to add a user to.

3. Click Users.

4. Click Add user account.

5. Select Cloud IAM.

6. In the Principal field, enter the IAM principal.

   For an IAM user account, supply the user account's full email address. For example, [e-mail].

   For an IAM service account, supply the service account's address without the .gserviceaccount.com suffix. For example, to specify the service account [e-mail], you would use the value [e-mail] here.

7. Click Add.

gcloud

To create a PostgreSQL database user based on an IAM user or service account, use the gcloud alloydb users create command:

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

Replace the following:

• USERNAME: An identifier for the IAM user that you want to add as a new database user.

  For an IAM user account, supply the user account's full email address. For example, [e-mail].

  For an IAM service account, supply the service account's address without the .gserviceaccount.com suffix. For example, to specify the service account [e-mail], you would use the value [e-mail] here.

• CLUSTER: The ID of the cluster to create this database user account within.

• REGION: The ID of the region where the cluster resides. For example, us-central1.

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:

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

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

Remove an IAM user or service account from a cluster

Console

1. Go to the Clusters page.

   Go to Clusters

2. Click the name of the cluster you want to remove the user from.

3. Click Users.

4. On the row representing the user you want to remove, click Open actions for this user.

5. Select Remove.

6. In the Remove user account? dialog, click Remove.

gcloud

Use the gcloud alloydb users delete command:

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

Replace the following:

• USERNAME: The identifier of the IAM user that you want to remove from the cluster.

  For an IAM user account, supply the user account's full email address. For example, [e-mail].

  For an IAM service account, supply the service account's address without the .gserviceaccount.com suffix. For example, to specify the service account [e-mail], you would use the value [e-mail] here.

• CLUSTER: The ID of the cluster to remove this user from.

• REGION: The ID of the region where the cluster resides. For example, us-central1.

What's next

• Connect using an IAM account