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.
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 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 added using IAM database authentication loses access to the instance. For more
information, see
Configure 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:
- Create a new user or service account in the instance.
- 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:
- Authenticate to IAM using
gcloud auth login
. - Generate an access token using
gcloud auth print-access-token
. - 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
- For security, logins using IAM database authentication are only available on an SSL connection. Unencrypted connections are rejected.
- 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
- Learn how to configure instances for IAM database authentication.
- Learn how to create a user or service account that uses IAM database authentication.
- Learn how to grant login access to a user or service account.
- Learn how to log in to a Cloud SQL database.
- Learn how to manage users and service accounts for IAM database authentication.