Overview of Cloud SQL IAM database authentication

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

Introduction

Cloud SQL is integrated with IAM to help you better monitor and manage access for users and service accounts to databases. This feature is called IAM database authentication.

Authentication is a means of access control that verifies the identity of a user. For end users, authentication is achieved when the user enters credentials (a username and password). For applications, authentication is achieved when a user's credentials are assigned to a service account.

Differences between built-in authentication and IAM authentication

Cloud SQL uses two types of authentication for database users:

  • The database's built-in authentication that authenticates using a username and password.
  • IAM database authentication that uses IAM to authenticate a database user.

In IAM, you define who (identity) has what access (role) for which resource. 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 authenticated members. For more information, see the IAM overview.

For IAM database authentication, you are specifically working with the following:

  • Members. In Cloud SQL, you can use two types of IAM members: A user account, and a service account (for applications). Other member types, such as Google groups, G Suite 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 members access are Cloud SQL instances. Cloud SQL sets an IAM policy at the project level when you create your project. The policy applies to all instances and other resources in the project. For more information, see IAM policy.

Instance configuration for Cloud SQL IAM database authentication

You can enable IAM database authentication on an instance using the cloudsql.iam_authentication flag. This flag configures all the databases on the instance. 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 authorizations for the new instance. For more information, see Granting login access to a user or service account.

User and service account administration

To provide users and service accounts access to databases on an instance using IAM database authentication, you do the following:

  1. Create a new user or service account in the instance.
  2. Grant the IAM login permission to the user or service account to allow IAM database authentication.

Once created, you can use the PostgreSQL GRANT command to grant other database privileges.

For more information, see Creating a user or service account that uses IAM database authentication.

Cloud SQL logins for users and service accounts

When a user wants to log in to a database using Cloud SQL IAM database authentication, they must do the following:

  1. Authenticate to IAM:
  2. Generate an access token using gcloud auth print-access-token.
  3. Supply the access token as a password when logging in to the database.

The access token represents the account's IAM user credential and is valid for one hour. The token is proof of the user's identity. Cloud SQL uses the token to authenticate and authorize the user before allowing them to log in.

For more information, see Logging in to a database with 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.

What's next