Logging in to a database with IAM database authentication

This page describes how users and service accounts can log in to Cloud SQL databases using Cloud SQL IAM database authentication. To learn more about the Cloud SQL IAM integration, see Overview of Cloud SQL IAM database authentication.

Before you begin

Using IAM database authentication with the Cloud SQL Auth proxy

For the most secure and reliable experience, it is recommended that you connect to the database using the Cloud SQL Auth proxy when using IAM database authentication. IAM database authentication uses OAuth 2.0 access tokens, which are short-lived and only valid for one hour. The Cloud SQL Auth proxy is able to request and refresh these tokens, ensuring that long-lived process or applications that rely on connection pooling can have stable connections.

In this procedure, you configure the Cloud SQL Auth proxy to connect to an instance using IAM database authentication.

  1. When using the Cloud SQL Auth proxy with IAM database authentication, the GCP IAM account that you use to start the Cloud SQL Auth proxy must be the same account that authenticates to the database. For more information about authenticating the Cloud SQL Auth proxy, see Options for authenticating the Cloud SQL Auth proxy.

  2. Start the Cloud SQL Auth proxy with the -enable_iam_login flag.

    Replace the following:

    ./cloud-sql-proxy -enable_iam_login -instances=INSTANCE_CONNECTION_NAME=tcp:5432
    

    Proxy For more information on how to start the proxy, see Start the Cloud SQL Cloud SQL Auth proxy.

  3. When you are ready to connect to the Cloud SQL Auth proxy, you use the email address for the IAM user or service account as the database username. For a service account, this is the service account's email without the .gserviceaccount.com domain suffix.For the password, use either no password, or a blank password.

    For more information on how to connect to the Cloud SQL Auth proxy, see Connecting using the Cloud SQL Auth proxy.

Logging in with IAM database authentication without the Cloud SQL Auth proxy

Using the Cloud SDK, you can explicitly request an OAuth 2.0 token with the Cloud SQL Admin API scope that is used to log in to the database through the psql client. When you log in as a database user with IAM database authentication, you use your email address as the username and the access token as the password.

To use the Cloud SDK to generate this token and log in, use the following script:

  1. Authenticate and create the token.

    User

    Authenticate to IAM using gcloud auth login.

    For more information, see Authorizing with a user account.

    Service account

    Authenticate to IAM using gcloud auth activate-service-account.

    For more information, see Authorizing with a service account.

  2. Log in with a client using the saved access token.

    Warning: You can use your OAuth 2.0 token to make authenticated requests on your behalf. Make sure to keep it secure, and be careful where you store it or who has access to your instance.

    Replace the following:

    • HOSTNAME: The IP address of the instance, or 127.0.0.1 if using the Cloud SQL proxy.
    • EMAIL: The user email address to use to connect to the host machine. For a service account, this is the service account's email without the .gserviceaccount.com domain suffix.
    • DATABASE_NAME: The name of the database to connect to.
    PGPASSWORD=$(gcloud auth print-access-token) psql --host=HOSTNAME \
                                                    --username=EMAIL \
                                                    --dbname=DATABASE_NAME
    

What's next