Cloud SQL IAM database authentication

This page describes how IAM database authentication works on Cloud SQL instances, how it affects the creation of users and service accounts, and logins from those accounts.

Introduction

Cloud SQL is integrated with Identity and Access Management (IAM) to help you better manage login access for users and service accounts to databases. This feature is called IAM database authentication.

Authentication is the process of verifying the identity of a user who is attempting to access an instance. Cloud SQL uses the following types of authentication for database users:

  • The database's built-in authentication uses a username and password to authenticate a database user.
  • IAM database authentication uses IAM to authenticate a user by using an access token.

IAM authentication for Cloud SQL

When using IAM authentication, permission to access a resource (a Cloud SQL instance) isn't granted directly to the end user. Instead, permissions are grouped into roles, and roles are granted to principals. For more information, see the IAM overview.

Administrators who have users log in through IAM database authentication can use IAM to centrally manage access control to their instances using IAM policies. IAM policies involve the following entities:

  • Principals. In Cloud SQL, you can use two types of principals: A user account, and a service account (for applications). Other principal types, such as Google groups, Google Workspace domains, or Cloud Identity domains are not supported for IAM database authentication. For more information, see Concepts related to identity.
  • Roles. For IAM database authentication, a user requires the cloudsql.instances.login permission to log in to an instance. To get this permission, you bind the user or service account to either the predefined Cloud SQL Instance User role or a custom role that bundles the permission. For more information about IAM roles, see Roles.
  • Resource. The resources that principals access are Cloud SQL instances. By default, IAM policy bindings are applied at the project-level, such that principals receive role permissions for all Cloud SQL instances in the project.

IAM database authentication options

Cloud SQL for PostgreSQL has two options for IAM database authentication: automatic and manual.

Automatic IAM database authentication

Automatic IAM database authentication lets you hand off requesting and managing access tokens to an intermediary Cloud SQL connector, such as the Cloud SQL Auth Proxy. With automatic IAM database authentication, users need to pass only the IAM database username in a connection request from the client. The connector submits the access token information for the password attribute on behalf of the client.

Automatic IAM database authentication requires the use of a Cloud SQL connector. It's currently supported by the Cloud SQL Auth Proxy, the Go connector, the Java connector, and the Python connector.

For the most secure and reliable experience, we recommend you use automatic IAM database authentication. IAM database authentication uses OAuth 2.0 access tokens, which are short-lived and only valid for one hour. Cloud SQL connectors are able to request and refresh these tokens, ensuring that long-lived processes or applications that rely on connection pooling can have stable connections. Automatic IAM database authentication is strongly recommended over manual authentication.

For more information, see Log in with automatic IAM database authentication.

Manual IAM database authentication

Manual IAM database authentication requires the IAM principal to explicitly pass the access token for the password attribute in the client connection request. Principals must first log in to Google Cloud and explicitly request the access token from IAM.

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 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.

Logging in with IAM database authentication can only be performed over an SSL connection.

For more information, see Logging in with manual IAM database authentication.

User and service account administration

To provide users and service accounts access to databases on an instance using IAM database authentication, you need to add them to the instance. For more information, see Add a user or service account that uses IAM.

If you use the Google Cloud console to add users or service accounts, Cloud SQL asks you to add the "Cloud SQL User" role to the user. This role is required for users to log in to the instance.

If you add users using gcloud or the API, you need to grant login privileges manually. Use the PostgreSQL GRANT command to grant database privileges.

Instance configuration for Cloud SQL IAM database authentication

You can enable IAM database authentication on an instance using the cloudsql.iam_authentication flag. Once you enable this flag, the instance enables logins from accounts that are configured for IAM database authentication.

Setting the flag does not prevent existing, non-IAM users from using their usernames and passwords to log in. However, if you disable this flag on the instance, any user that you previously added using IAM database authentication loses access to the instance. For more information, see Configuring instances for IAM database authentication.

Cloud SQL IAM database authentication for different instance scenarios

Read replicas IAM database authentication is not enabled in a read replica automatically, even when it is enabled on the primary instance. After you create a read replica, you need to add IAM database authentication. For more information, see Configuring read replica logins for IAM database authentication.
Restored instances If an instance was previously backed up and later restored to the same or a different instance in the same project, the current user login authorizations apply. If you restore a backup to a new instance in another project, you need to set up the user authorizations for the new instance. For more information, see Adding a user or service account that uses IAM database authentication.

Work with Cloud Audit Logs

To keep records of data access, including logins, you can use audit logs. Cloud Audit Logs is turned off, by default. You need to turn on Data Access audit logs for login tracking. Using audit logging for this purpose incurs costs for data logging. For more information, see Audit Logs, Configuring Data Access audit logs and Pricing for logging data.

Restrictions

  1. For security, logins using IAM database authentication are only available on an SSL connection. Unencrypted connections are rejected.
  2. There is a per-minute login quota for each instance, which includes both successful and unsuccessful logins. When the quota is exceeded, logins are temporarily unavailable. We recommend that you avoid frequent logins and restrict logins using authorized networks. The quota for authorization of logins is 3000 per minute, per instance.

What's next