Manage IAM authentication

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:

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

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, kai@altostrat.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.

  7. To assign roles other than the default alloydbsuperuser to the user, follow these steps:

    1. Enter the name of the role in Roles.
    2. To add the role, press Enter or Tab.

    3. Select x for any role that you want to remove for that user.

      For more information, see Predefined roles

  8. 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 variables:

  • USERNAME: 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, kai@altostrat.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.

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

  • REGION: 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 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

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: 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, kai@altostrat.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.

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

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

What's next