This page describes how users and service accounts can log in to Cloud SQL databases using Cloud SQL IAM database authentication. For more information, see Overview of Cloud SQL IAM database authentication.
Before you begin
- Configure an instance to use IAM database authentication. For more information, see Configuring new instances for IAM database authentication.
- Add an IAM user or service account to the database. For more information, see Adding an IAM user or service account to the database.
- Add the
roles/cloudsql.instanceUser
IAM role on your user account to perform this task. It is a predefined role that contains the necessary Cloud SQL IAM permissioncloudsql.instances.login
. You need this permission to log in to a database instance.
Log in with automatic IAM database authentication
You can configure a Cloud SQL connector to automatically handle authentication to the Cloud SQL instance on behalf of a user or an application. Connectors include the Cloud SQL Auth proxy, the Java connector, and the Python connector, all of which support automatic IAM database authentication. When using a Cloud SQL connector with automatic IAM database authentication, the IAM account that you use to start the connector must be the same account that authenticates to the database. For more information, see Options for authenticating the Cloud SQL Auth proxy.
To log in using automatic IAM database authentication:
Cloud SQL Auth proxy
Start the Cloud SQL Auth proxy with the
-enable_iam_login
flag.Replace the following:
- INSTANCE_CONNECTION_NAME: The connection string to identify a Cloud SQL instance. For more information on how to find this string, see Options for authenticating the Cloud SQL Auth proxy.
./cloud_sql_proxy -enable_iam_login -instances=INSTANCE_CONNECTION_NAME=tcp:5432
For more information on how to start the proxy, see Start the Cloud SQL Auth proxy.
When you are ready for the client to connect to the Cloud SQL Auth proxy, 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 more information on how to connect to the Cloud SQL Auth proxy, see Connecting using the Cloud SQL Auth proxy.
Java JDBC
Java R2DBC
Python
Log in with manual IAM database authentication
Note: If you plan to use the Cloud SQL Auth proxy, the Java connector, or the Python connector, see Logging in with automatic.A user or an application can authenticate to the database using IAM by manually requesting an access token from Google Cloud and presenting it to the database. Using the gcloud, 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. When you log in as a database user with manual IAM database authentication, you use your email address as the username and the access token as the password. You can use this method with either a direct connection to the database or with a Cloud SQL connector.
In these steps, you authenticate to Google Cloud, request an access token, and then connect to the database by passing in the token as the password for the IAM database user. Use these steps to connect without the Cloud SQL Auth proxy.
To use the gcloud to generate this token and log in:
gcloud
Authenticate to Google Cloud.
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.Request the access token and log in with a client.
Replace the following:
- HOSTNAME: The IP address of the instance.
- USERNAME: The username is the email address to use for
connecting 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 sql generate-login-token) psql --host=HOSTNAME
--username=USERNAME
--dbname=DATABASE_NAME
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 manage users and service accounts for IAM database authentication.