You can configure Identity and Access Management (IAM) database authentication on new or
existing AlloyDB for PostgreSQL clusters to manage database sign-ins and permissions
using individual IAM accounts or IAM groups.

IAM authentication complements database authentication through
[standard PostgreSQL users](https://docs.cloud.google.com/alloydb/docs/database-users/manage-roles.md.txt), which
every AlloyDB cluster supports.

You can authenticate using individual accounts or groups:

- Individual accounts: you add each IAM user or service account
  to the cluster and manage permissions per account.

- Groups: you add an IAM group to the cluster so that all
  members (users and service accounts) inherit permissions to authenticate to
  primary instances, read pool instances, and AlloyDB Studio without
  adding each member individually.

IAM authentication is disabled on AlloyDB
instances by default.

To use IAM authentication, complete the following general steps:

1. [Enable IAM individual or group authentication](https://docs.cloud.google.com/alloydb/docs/database-users/manage-iam-auth.md.txt#enable) on your instance.
2. Grant the required roles to the account or group.
3. Add the account or group to your cluster.
4. Grant database privileges to the account or group.

## Enable and disable IAM authentication

To enable IAM authentication on an instance in a new or existing
cluster, set the required database flags:

- For individual authentication, set the
  [`alloydb.iam_authentication`](https://docs.cloud.google.com/alloydb/docs/reference/alloydb-flags.md.txt#alloydb.iam_authentication)
  database flag to `on`.

- For group authentication, set both the
  [`alloydb.iam_authentication`](https://docs.cloud.google.com/alloydb/docs/reference/alloydb-flags.md.txt#alloydb.iam_authentication)
  and
  [`alloydb.iam_group_authentication`](https://docs.cloud.google.com/alloydb/docs/reference/alloydb-flags.md.txt#alloydb.iam_group_authentication)
  database flags to `on`.

To disable IAM authentication, set the flags to `off`.

For more information about setting flags, see
[Configure an instance's database flags](https://docs.cloud.google.com/alloydb/docs/instance-configure-database-flags.md.txt).

> [!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.

## Grant access to an individual account

To enable IAM access to a new database user, follow these steps:

1. [Update your project's IAM settings](https://docs.cloud.google.com/alloydb/docs/database-users/manage-iam-auth.md.txt#enable) to grant
   AlloyDB database access to the appropriate IAM
   user or service account.

2. [Create a new database user on your cluster](https://docs.cloud.google.com/alloydb/docs/database-users/manage-iam-auth.md.txt#create-user), setting the
   username as the email address of the IAM user or service
   account.

To give an IAM account access to other
clusters in your project, repeat the last step.

### 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](https://docs.cloud.google.com/alloydb/docs/user-grant-access.md.txt#procedure). 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](https://console.cloud.google.com/alloydb/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, provide the full email address of the user account.
   For example, `dana@example.com`.

   For an IAM service account, provide the address of the service account
   *without* the `.gserviceaccount.com` suffix. For
   example, to specify the service account
   `my-service@my-project.iam.gserviceaccount.com`, you
   use the value `my-service@my-project.iam`.

   > [!NOTE]
   > **Note:** The shortened service account identifier, which is the email address without the `.gserviceaccount.com` suffix, must not exceed 63 characters. PostgreSQL truncates identifiers longer than 63 characters in the database catalog, which causes IAM authentication to fail. If the shortened address exceeds 63 characters, see the [service account impersonation workaround](https://docs.cloud.google.com/alloydb/docs/troubleshoot/troubleshoot-iam-auth.md.txt).
   >
   > <br />
   >
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 <kbd>Enter</kbd> or <kbd>Tab</kbd>.
   3. Select **x** for any role that you want to remove for that user.

      For more information, see [Predefined roles](https://docs.cloud.google.com/alloydb/docs/database-users/overview.md.txt#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`](https://docs.cloud.google.com/sdk/gcloud/reference/alloydb/users/create.md.txt) command.

```bash
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, provide the full email address of the user account.
  For example, `dana@example.com`.

  For an IAM service account, provide the address of the service account
  *without* the `.gserviceaccount.com` suffix. For
  example, to specify the service account
  `my-service@my-project.iam.gserviceaccount.com`, you
  use the value `my-service@my-project.iam`.

  > [!NOTE]
  > **Note:** The shortened service account identifier, which is the email address without the `.gserviceaccount.com` suffix, must not exceed 63 characters. PostgreSQL truncates identifiers longer than 63 characters in the database catalog, which causes IAM authentication to fail. If the shortened address exceeds 63 characters, see the [service account impersonation workaround](https://docs.cloud.google.com/alloydb/docs/troubleshoot/troubleshoot-iam-auth.md.txt).
  >
  > <br />
  >
- `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 you add an IAM user to an AlloyDB cluster, the user has
no privileges on any databases by default except for the database objects that
[PUBLIC](https://www.postgresql.org/docs/18/ddl-priv.html) can access.

If users need additional access, grant more privileges using the
[`GRANT` PostgreSQL statement](https://www.postgresql.org/docs/18/sql-grant.html):

```sql
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 that 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](https://console.cloud.google.com/alloydb/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](https://docs.cloud.google.com/sdk/gcloud/reference/alloydb/users/delete.md.txt).

```bash
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, provide the full email address of the user account.
  For example, `dana@example.com`.

  For an IAM service account, provide the address of the service account
  *without* the `.gserviceaccount.com` suffix. For
  example, to specify the service account
  `my-service@my-project.iam.gserviceaccount.com`, you
  use the value `my-service@my-project.iam`.

  > [!NOTE]
  > **Note:** The shortened service account identifier, which is the email address without the `.gserviceaccount.com` suffix, must not exceed 63 characters. PostgreSQL truncates identifiers longer than 63 characters in the database catalog, which causes IAM authentication to fail. If the shortened address exceeds 63 characters, see the [service account impersonation workaround](https://docs.cloud.google.com/alloydb/docs/troubleshoot/troubleshoot-iam-auth.md.txt).
  >
  > <br />
  >
- `CLUSTER`: ID of the cluster to remove this user from.

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

## Grant access to an IAM group

To use group authentication, you add an IAM group to the
AlloyDB cluster.

### Add an IAM group to a cluster

Before you add an IAM group to a cluster, note the following
requirements:

- A maximum of 200 IAM groups can exist on a cluster at any
  time. Inactive groups count toward this limit.

- IAM group names can't exceed 63 characters. If you have an
  IAM group with a name that exceeds 63 characters, then you
  can nest it under a parent group with a valid name. You must add the parent
  group to the cluster before you can use the nested group.

To add an IAM group to a cluster, follow these steps:

1. Assign the `roles/alloydb.databaseUser` and
   `roles/serviceusage.serviceUsageConsumer` roles to the group account. For
   more information about granting these roles, see
   [Update an IAM account with the appropriate role](https://docs.cloud.google.com/alloydb/docs/database-users/manage-iam-auth.md.txt#role).

2. To create a database user for the group, run the
   [`gcloud alloydb users create`](https://docs.cloud.google.com/sdk/gcloud/reference/alloydb/users/create.md.txt)
   command with the `--type=IAM_GROUP` flag:

   ```bash
   gcloud alloydb users create GROUP_EMAIL \
   --cluster=CLUSTER \
   --region=REGION \
   --type=IAM_GROUP
   ```

   Replace the following:
   - `GROUP_EMAIL`: the full email address of the
     IAM group---for example, `my-group@example.com`.

   - `CLUSTER`: the ID of the cluster to add the group
     to.

   - `REGION`: the ID of the region where the cluster
     resides---for example, `us-central1`.

   > [!NOTE]
   > **Note:** If you delete a group in Cloud Identity and immediately re-create that group, the group might not be usable right away. Group deletion and re-creation take time to propagate.

### Add members of a group automatically

When you add an IAM group to a cluster, all users and service
accounts in that group inherit permissions to authenticate. You don't need to
add the members individually. Group members can sign in directly to primary
instances, read pool instances, and AlloyDB Studio in the Google Cloud console,
including first-time sign-ins to read pool instances without connecting to the
primary instance first. When a member signs in for the first time,
AlloyDB creates a database account for that principal
automatically.

When you restore or migrate an AlloyDB cluster from a
Cloud SQL for PostgreSQL backup, AlloyDB maps and preserves
individual and IAM group user configurations. For more
information about migrating from a Cloud SQL for PostgreSQL backup, see
[Migrate from Cloud SQL for PostgreSQL to
AlloyDB](https://docs.cloud.google.com/alloydb/docs/migrate-cloud-sql-to-alloydb).

### Grant database privileges to an IAM group

You grant database privileges to groups instead of individual users.

Run the `GRANT` statement from the `psql` command line:

```sql
GRANT SELECT ON TABLE_NAME TO "GROUP_NAME";
```

Replace the following:

- `TABLE_NAME`: the name of the table that you want to
  grant the group access to.

- `GROUP_NAME`: the email address of the group. Include
  double quotes around the address because it contains special characters.

## Delete an IAM group from a cluster

To delete an IAM group from an AlloyDB cluster,
revoke the group permissions in the Google Cloud console and delete the
corresponding group user from the AlloyDB cluster.

1. Revoke IAM permissions:

   1. In the Google Cloud console, go to the **IAM** page.

      [Go to IAM](https://console.cloud.google.com/iam-admin/iam?supportedpurview=project)
   2. Find the IAM group from which you want to remove access.

   3. Remove the `roles/alloydb.databaseUser` role and any other
      AlloyDB-related roles that grant access to the cluster.
      This action prevents members of the group from authenticating.

2. Delete the group user from the AlloyDB cluster:

   Use the Google Cloud CLI to delete the user representing the
   IAM group from the AlloyDB cluster. The
   username is typically the email address of the IAM group:

   ```bash
   gcloud alloydb users delete GROUP_EMAIL_ADDRESS \
   --cluster=CLUSTER_ID \
   --region=REGION_ID
   ```

   Replace the following:
   - `GROUP_EMAIL_ADDRESS`: the full email address of
     the IAM group---for example, `my-group@example.com`.

   - `CLUSTER_ID`: the ID of your
     AlloyDB cluster.

   - `REGION_ID`: the region where your
     AlloyDB cluster is located---for example,
     `us-central1`.

3. Optional: Delete the group from Cloud Identity:

   > [!CAUTION]
   > **Caution:** Deleting a group is permanent and can't be undone. Members lose access to resources shared with the deleted group, and messages sent to the group's address aren't delivered.

   You need appropriate administrator privileges (like Groups Admin)
   in your Cloud Identity account to delete groups. Group owners can
   typically only delete groups that they own.

   Changes to IAM permissions and
   group memberships can take time to propagate, potentially 15 minutes or more.
   1. Make sure that you have [appropriate administrator privileges](https://knowledge.workspace.google.com/admin/users/view-role-assignments-and-privileges) like Groups Admin
      in your Cloud Identity account. Group owners can
      only delete the groups that they own. For more information, see
      [Prebuilt administrator roles](https://knowledge.workspace.google.com/admin/users/prebuilt-administrator-roles).

   2. Run the following Cloud Identity gcloud CLI command:

      ```bash
      gcloud identity groups delete GROUP_EMAIL_ADDRESS
      ```
   3. When you revoke the sign-in permission `alloydb.databaseUser` for an
      IAM group in Cloud Identity, you must also [delete the group from
      the AlloyDB cluster](https://docs.cloud.google.com/alloydb/docs/database-users/manage-iam-auth#remove-iam-group) to make sure that
      access is completely removed.

## Migrate existing users to IAM group authentication

Existing individual IAM users don't use group authentication.
You can migrate them by following these steps:

1. Add the users to an IAM group.
2. Add the group to your cluster.
3. Assign the group the required roles.
4. Assign database privileges to the group.
5. Delete the existing individual user from your cluster. Make sure that you transfer ownership if intended.

When the user signs in again, AlloyDB recreates the account as a group user.

## Troubleshoot group authentication

Use the following information to troubleshoot group authentication issues.

### An existing account isn't inheriting privileges

If an account isn't inheriting privileges from a group, follow these steps:

1. List the users on the cluster:

   ```bash
   gcloud alloydb users list \
       --cluster=CLUSTER \
       --region=REGION
   ```

   Replace the following:
   - `CLUSTER`: the ID of your AlloyDB
     cluster.

   - `REGION`: the ID of the region where your
     AlloyDB cluster resides---for example,
     `us-central1`.

2. If the account has the type `ALLOYDB_IAM_USER`,
   [remove the account from the cluster](https://docs.cloud.google.com/alloydb/docs/database-users/manage-iam-auth.md.txt#delete-user). Accounts with the type
   `ALLOYDB_IAM_USER` don't inherit group privileges.

3. To re-create the account with the group user type, sign in again to the
   instance with the user or service account. Signing in again to the instance
   re-creates the account with the account type `ALLOYDB_IAM_GROUP_USER` or
   `ALLOYDB_IAM_GROUP_SERVICE_ACCOUNT`.

## What's next

- [Connect using an IAM account](https://docs.cloud.google.com/alloydb/docs/connect-iam.md.txt)
- [Troubleshoot IAM authentication](https://docs.cloud.google.com/alloydb/docs/troubleshoot/troubleshoot-iam-auth.md.txt)