Logging in to a database with IAM database authentication

MySQL   |  PostgreSQL   |  SQL Server

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

• Configure an instance to use IAM database authentication. For more information, see Configuring IAM database authentication.
• Create and authorize an IAM database authentication user. For more information, see Creating a user that uses IAM database authentication and Granting login access to a user or service account.

Logging in as a user or service account with IAM database authentication

Warning: OAuth 2.0 access tokens are short lived and are only valid for one hour. Any new connections or logins created after this time will fail. For this reason, it's not recommended to use IAM database authentication with long-lived processes or applications that rely on connection pooling.

You log in as a database user with IAM database authentication using your email address as the username and an OAuth 2.0 access token with the Cloud SQL Admin API scope as the password.

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

1. Authenticate to IAM using gcloud auth login.

   gcloud auth login
   

2. Log in with the psql 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.
   • DATABASE_NAME: The name of the database to connect to.

   PGPASSWORD=$(gcloud auth print-access-token) psql --host=HOSTNAME \
                                                     --username=EMAIL \
                                                     --dbname=DATABASE_NAME
   

   Note: The OAuth 2.0 token can't be entered or pasted directly into a password field, because that token is longer than the field's buffer size (100 characters). Always use the PGPASSWORD environment variable.

What's next

• Learn more about IAM database authentication.
• Learn how to enable and view login information in audit logs.
• Learn how to create users and service accounts that use Cloud SQL IAM database authentication.
• Learn how to grant login access to a user or service account.
• Learn how to manage users and service accounts for IAM database authentication.