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 Cloud SQL IAM database authentication.
Before you begin
- Configure an instance to use IAM database authentication. For more information, see Configure new instances for IAM database authentication.
- Add an IAM user or service account to the database. For more information, see Add an IAM user or service account to the database.
- Add the
roles/cloudsql.instanceUser
IAM role to your IAM user or service account. It's a predefined role that contains the necessary Cloud SQL IAMcloudsql.instances.login
permission. You need this permission to login to a database instance with IAM database authentication. For more information, see Roles and permissions. - When an IAM user is added to a database, the new database user has no privileges
to any database by default. You need to
use the
GRANT
command to give the IAM database user any required permissions. For more information, see Grant database privileges to the IAM User.
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 Go connector, 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 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
--auto-iam-authn
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 --auto-iam-authn INSTANCE_CONNECTION_NAME
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 Connect with the mysql client.
Go
Java JDBC
Java R2DBC
Python
Log in with manual IAM database authentication
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 CLI, 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 this procedure, 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.
For these steps, you must:
- Use the
--enable-cleartext-plugin
mysql
option. - Connect using SSL. See Connect to your Cloud SQL instance using SSL for more information about creating and downloading SSL certificate files.
Run the commands within the VPC for private IP.
To use the gcloud CLI to generate this token and log in:
gcloud
Authenticate to Google Cloud.
User
Authenticate to IAM using
gcloud auth login
. For more information, see Authorize with a user account.Service account
Authenticate to IAM using
gcloud auth activate-service-account
. For more information, see Authorize 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: For an IAM user account, this is the
user's email address, without the
@
or domain name. For example, fortest-user@gmail.com
, entertest-user
. For a service account, this is the service account's email address without the@project-id.iam.gserviceaccount.com
suffix.
MYSQL_PWD=`gcloud sql generate-login-token` mysql --enable-cleartext-plugin
--ssl-ca=server-ca.pem --ssl-cert=client-cert.pem
--ssl-key=client-key.pem --host=HOSTNAME
--user=USERNAME
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 add an IAM policy binding to a user or service account.
- Learn how to manage users and service accounts for IAM database authentication.