IAM authentication

Google Cloud offers Identity and Access Management (IAM), which lets you give access to specific Google Cloud resources and prevent unwanted access to other resources. This page describes how Cloud SQL is integrated with IAM and how you can use IAM for database authentication. For a detailed description of Google Cloud IAM, see IAM documentation.

Cloud SQL provides a set of predefined roles designed to help you control access to your Cloud SQL resources. You can also create your own custom roles, if the predefined roles don't provide the sets of permissions you need. In addition, the legacy basic roles (Editor, Viewer, and Owner) are also still available to you, although they don't provide the same fine-grained control as the Cloud SQL roles. In particular, the basic roles provide access to resources across Google Cloud, rather than just for Cloud SQL. For more information about basic Google Cloud roles, see Basic roles.

You can set an IAM policy at any level in the resource hierarchy: the organization level, the folder level, or the project level. Resources inherit the policies of all of their parent resources.

IAM references for Cloud SQL

IAM authentication concepts

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

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.

Compare database authentication options

The following table compares different database authentication methods for Cloud SQL.

Feature Built-in database authentication IAM database authentication
Authentication method Password Temporary authentication token
Network traffic encryption SSL not required SSL required
User management Manual Centralized through IAM

Automatic versus manual IAM database authentication

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

About IAM Conditions

IAM Conditions lets you grant roles based on a variety of attributes. For example, you can allow access only at certain dates and times or grant access only to Cloud SQL resources with certain names.

For more information about IAM Conditions, see the Overview of IAM Conditions page. You can also learn more about Using IAM Conditions with Cloud SQL, including examples.

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 12,000 per minute, per instance.

What's next