Google Cloud offers Identity and Access Management (IAM), which lets you giveaccess to specific Google Cloud resources and prevent unwantedaccess to other resources. This page describes how Cloud SQL is integrated withIAM and how you can use IAM for managing access to Cloud SQLresources and for database authentication.For a detailed description of Google Cloud IAM, seeIAM documentation.

Cloud SQL provides a set ofpredefined rolesdesigned to help you control access to your Cloud SQL resources. You canalso create your owncustom 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 stillavailable to you, although they don't providethe same fine-grained control as the Cloud SQL roles. In particular, thebasic roles provide access to resources across Google Cloud, rather than justfor Cloud SQL. For more information about basic Google Cloud roles, seeBasic roles.

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

IAM references for Cloud SQL

• Required permissions for common tasks in the Google Cloud console
• Required permissions forgcloud sql commands
• Required permissions for Cloud SQL Admin API methods
• Predefined Cloud SQL IAM roles
• Permissions and their roles
• Custom roles

IAM authentication concepts

When using IAM authentication, permission to access a resource(a Cloud SQL instance) isn't granteddirectly to the end user. Instead,permissions are grouped intoroles, and roles are granted toprincipals. Formore information, see theIAM overview.

Administrators who have users log in through IAM database authentication can useIAM authentication to centrally manage access control to their instancesusing IAM policies.

IAM policies involve the following entities:

• Principals. In Cloud SQL, you can use severaltypes of principals: auser account, aservice account(for applications), or agroup.For more information, seeConcepts related to identity.
• Roles. A role is a collection of permissions. You can grant roles toprincipals to provide them with the privileges required to accomplishspecific tasks. For example, with IAM database authentication, a principal requiresthecloudsql.instances.login permission to log in to an instance, which isincluded in theCloud SQL Instance User role.To get the permission, you bind the user, service account,or group to the predefined Cloud SQL role or a custom role thatincludes the permission. For more information about IAM roles,seeRoles.
• Resource. The resources that principals access are Cloud SQLinstances. By default, IAM policy bindings are applied at theproject-level, such that principals receive role permissions for allCloud SQL instances in the project.

IAM database authentication

Database authentication is the process of verifying the identity of a user who isattempting to access databases. In Cloud SQL, you can use the followingtypes of database authentication for database users:

• The database'sbuilt-in authenticationuses a username and password to authenticate a database user.
• IAM database authentication uses IAM to authenticate a user by using an accesstoken.Note: If you're usingWorkforce Identity Federation,database authentication for user logins isn't supported forCloud SQL for PostgreSQLdatabases. For more information, seeIdentity federation limitations.

  Compare database authentication options

  The following table compares different database authentication methods forCloud SQL.

  Feature	Built-in database authentication	IAM database authentication (individual)	IAM group authentication
  Authentication method	Password	Temporary authentication token	Temporary authentication token
  Network traffic encryption	SSL not required	SSL required	SSL required
  User management	Manual	Centralized through IAM	Centralized through IAM and Cloud Identity groups

  IAM group authentication

  IAM group authentication lets you manage Cloud SQL users at a group level. An exampleof a group includes aCloud Identity group.This feature simplifies database user management. You can manage the Cloud SQLIAM role or permissions for multiple accounts at once instead ofhaving to update each user or service account individually. You can also grantand revoke the database privileges for a Cloud Identity group.Any new accounts that you add to the Cloud Identity group inherit theprivileges of that group.

  With IAM group authentication, you can do the following:

  • Add a user to a group and have the user inherit their IAM rolesand database privileges automatically.
  • Remove a user from a group to remove their login access and databaseprivileges from Cloud SQL databases.
  • Grant login or database privileges to a group a single time instead ofhaving to grant the same privileges multiple times to different users.
  • Remove login permissions or access to a database object for a group allat once.

  Even though IAM roles and permissions are assigned at thegroup level, users and service accounts use their individualIAM accounts and credentials and not a shared group account tolog in. Cloud SQL creates a database account on the instance for that useror service account after their first login.

  Individual login and databaseactivity for each user or service account appears in audit logs. Forauditing purposes, you get the benefit of viewing which account performed whichaction in your database.

  For more information about working with Cloud Identity groups, see theOverview of Cloud Identity.

  When you add a user or service account to a group, thefollowing changes in Cloud SQL occur:

  • If you have already given IAM login permissions to the group,then the user or service account gains the ability to log in to theCloud SQL instance because the user or service account belongs tothe group.
  • The user automatically inherits anydatabase privilegesthat have been granted to the group.
  Note: If you're adding an account that already has access to theinstance through individual IAM authentication, firstremove that IAM user or service account from the instance.Then add the user or service account to the group.

  When you remove a user or service account from the group, the followingchanges in Cloud SQL occur:

  • The user loses any database privileges that were previously inherited bybeing a member of the group.
  • The user might still be able login if they receive IAM loginpermissions for the Cloud SQL instance through other group memberships.However, the user won't have database privileges from their former groupmembership upon logging in.
  Note: Group membership changes take time to propagate. After a user has beenremoved from a group, it can take some time to revoke their inherited groupdatabase privileges.

  IAM group authentication best practices

  • When you revoke the login permission (cloudsql.instances.login)for an IAM group in Cloud Identity,make sure that you also delete the group from the Cloud SQL instance.
  • When you delete a group from a Cloud Identity, make sure that you alsodelete that group from the Cloud SQL instance.
  • Use groups to configure role-based access control in your database. Alwaysprovide the least required privileges to the group.
  • Don't grant IAM group authentication roles to built-in users. For example, if youhave a built-in user,user-a and create an IAM group authenticationuser,user-b@example.com, then don't grant theuser-b@example.com role touser-a.

  IAM group authentication restrictions

  • When using IAM group authentication, if you have a Cloud SQL instance with read replicas, then you must log in to the primary instance first before logging in to the read replica instance. After your first login to the primary instance, the group user information is replicated to the read replicas. For subsequent logins, you can log in directly to the read replica.
  • You can add a maximum of 200 IAM groups to an instance.
  • You can't add individual IAM user or service accountsthat belong to a group on the same instance. In other words, you can't add an account with the typeCLOUD_IAM_USER orCLOUD_IAM_SERVICE_ACCOUNT if an identical account with typeCLOUD_IAM_GROUP_USER orCLOUD_IAM_GROUP_SERVICE_ACCOUNT already exists.
  • If an individual account already exists on an instance with the typeCLOUD_IAM_USER orCLOUD_IAM_SERVICE_ACCOUNT, then the account can't be used for IAM group authentication. These user types don't inherit IAM roles and database privileges from a group.

    To fix this issue and use the account with IAM group authentication, remove the individual IAM user or service account.

    For more information, seeAn existing IAM user or service account isn't inheriting the database privileges granted to their group.
  • Changes to Cloud Identity group membership, such as the addition of an account, take about 15 minutes to propagate. This is in addition to thetime required for IAM changes.

  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 tokenstoan intermediaryCloud SQL connector,such as the Cloud SQL Auth Proxy or one of the Cloud SQL Language Connectors. With automaticIAM database authentication, users need to pass only theIAM database username in a connection request from the client.The connector submits the access token information for the password attribute onbehalf of the client.

  Automatic IAM database authentication requires the use of a Cloud SQL connector andis supported by theCloud SQL Auth Proxy, theGo connector, theJava connector, and thePython connector.

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

  For more information, seeLog in with automatic IAM database authentication.

  Manual IAM database authentication

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

  Using thegcloud CLI, you can explicitly request anOAuth 2.0 token with theCloud SQL Admin API scope that is used to log in to the database. When you log in as adatabase user with IAM database authentication, you use your email address as the username andthe access token as the password. You can use this method with either a directconnection to the database or with a Cloud SQL connector.

  Warning:OAuth 2.0 access tokens are short lived and are only valid for one hour. Any new connections or logins created after this time fail. For this reason, we recommend that you use automatic IAM database authentication for long-lived processes or applications that rely on connection pooling.

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

  For more information, seeLogging in with manual IAM database authentication.

  Context-aware access and IAM database authentication

  If you're usingcontext-aware accessin your IAM configuration, then you can't use aCloud SQL connector such as the Cloud SQL Auth Proxy or one of theCloud SQL Language Connectors with IAM database authentication. Attempts to login either manually orautomatically with IAM authentication will fail.Connect directly to the instance instead.

  User and service account administration

  To provide users and service accounts access to databases on an instance usingIAM database authentication, you need to add them to the instance or addthem to a group that has access to the instance. For more information,seeAdd a user or service account that uses IAM.

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

  If you add users usinggcloud or the API, you need to grant login privilegesmanually. Use the PostgreSQLGRANT commandtogrant database privileges.

  Instance configuration for Cloud SQL IAM database authentication

  You can enable IAM database authentication on an instance using thecloudsql.iam_authenticationflag. Once you enable this flag, the instance enables logins from accounts thatare configured for IAM database authentication.

  This flag is required for IAM group authentication and IAM database authentication.

  Note: If a Cloud SQL instance already has an IAM user (CLOUD_IAM_USER)or service account (CLOUD_IAM_SERVICE_ACCOUNT) and you want toswitch theaccount to use IAM group authentication (CLOUD_IAM_GROUP_USER orCLOUD_IAM_GROUP_SERVICE_ACCOUNT), then you mustremove the existing IAM user or service accountfrom the instance first.

  Setting the flag does not prevent existing, non-IAM users fromusing their usernames and passwords to log in. However, if you disable this flagon the instance, any user that you previously added using IAM database authentication losesaccess to the instance. For more information, seeConfiguring 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, seeConfigure 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, seeAdd a user or service account that uses IAM database authentication.

  About IAM Conditions

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

  For more information about IAM Conditions, seetheOverview of IAM Conditionspage. You can also learn more aboutUsing IAM Conditionswith 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. Youneed to turn onData Access audit logs forlogin tracking. Using audit logging for this purpose incurs costs for datalogging. For more information, seeAudit Logs,Configuring Data Access audit logsandPricing for logging data.

  Restrictions

  1. The login for an IAM database authentication user account must be all lowercase. For example,example-user@example.com.Example-User@example.comis not allowed.
  2. For security, logins using IAM database authentication are only available on an SSLconnection. Unencrypted connections are rejected.
  3. There is a per-minute login quota for each instance, which includes bothsuccessful and unsuccessful logins. When the quota is exceeded, logins aretemporarily unavailable. We recommend that you avoid frequent logins andrestrict logins usingauthorized networks.The quota for authorization of logins is 12,000 per minute, per instance.

  What's next

  • Learn how toconfigure instances for IAM database authentication.
  • Learn how toadd a user or service account that uses IAM database authentication to your database.
  • Learn how tolog in to a Cloud SQL database with IAM database authentication.
  • Learn how toview login information in audit logs.
  • Learn aboutWorkforce Identity Federation.