Troubleshoot IAM authentication

This page describes how to troubleshoot Identity and Access Management (IAM) authentication issues for AlloyDB for PostgreSQL.

To determine the cause of a failed IAM-based authentication attempt, follow these steps:

  1. In the Google Cloud console, go to the Logs Explorer page:

    Go to Logs Explorer

  2. In the All resources drop-down list, select AlloyDB instance.

  3. Under Severity, click Alert.

    If Alert isn't an option, then there are no authentication failures logged within the selected time window. You might need to adjust the window using the Logs Explorer controls.

  4. Under Query results, check the log entries for one of the following messages:

    Request had invalid authentication credentials.
    The access token is invalid.
    Caller does not have required permission to use project.
    The IAM principal doesn't have the necessary IAM roles or permissions. The full error message specifies the missing roles or permissions.
    IAM principal does not match database user.

    The authenticated IAM principal specified by the access token doesn't match the database user that you want to connect as.

    To view the principal specified by the token, run the following command:

    curl -H "Content-Type: application/x-www-form-urlencoded" \
    -d "access_token=ACCESS_TOKEN" \
    https://www.googleapis.com/oauth2/v1/tokeninfo

    Replace ACCESS_TOKEN with the OAuth 2.0 access token.

    This error also occurs if the shortened principal of the service account, which is the email address without the .gserviceaccount.com suffix, exceeds 63 characters.

    PostgreSQL has a limit of 63 characters for role and user identifiers. Although AlloyDB lets you create the user, PostgreSQL truncates the role name to 63 bytes in the internal catalog. During login, the IAM authentication layer of AlloyDB compares the full, untruncated principal from the OAuth token against the truncated database role, which results in a string mismatch.

    Workaround: Use service account impersonation

    If you can't shorten the service account name, you can bypass this limitation by using service account impersonation. This decouples the identity running the workload from the identity used to log in to the database:

    1. Create a proxy service account with a name whose shortened principal, excluding the .gserviceaccount.com suffix, is 63 characters or fewer, such as db-proxy@PROJECT_ID.iam.gserviceaccount.com.
    2. Add the proxy service account to the AlloyDB cluster as an IAM_BASED database user with the username db-proxy@PROJECT_ID.iam.
    3. In IAM, grant the original service account of the workload the Service Account Token Creator role (roles/iam.serviceAccountTokenCreator) on the proxy service account.
    4. Configure your application, connector, or Auth Proxy to connect using the proxy identity.

    For example, you can connect using the gcloud beta alloydb connect command with the --impersonate-service-account flag:

    gcloud beta alloydb connect INSTANCE_ID \
    --cluster=CLUSTER_ID \
    --region=REGION_ID \
    --impersonate-service-account=PROXY_SERVICE_ACCOUNT_EMAIL \
    --auto-iam-authn

    Replace the following:

    • INSTANCE_ID: the ID of the AlloyDB instance.
    • CLUSTER_ID: the ID of the cluster that contains the instance.
    • REGION_ID: the region where the cluster resides.
    • PROXY_SERVICE_ACCOUNT_EMAIL: the full email address of the proxy service account.

    Note: The original service account doesn't need direct login access to the database, only permission to impersonate the proxy account. The proxy service account holds the database privileges.

    Request had insufficient scopes.
    The access token doesn't contain either the alloydb.login scope or the cloud-platform scope. At least one of these scopes is required.