使用 IAM 数据库身份验证登录

MySQL | PostgreSQL | SQL Server

本页面介绍了用户和服务账号如何使用 Cloud SQL IAM 数据库身份验证登录 Cloud SQL 数据库。如需了解详情，请参阅 IAM 身份验证。

准备工作

将实例配置为使用 IAM 数据库身份验证。如需了解详情，请参阅配置新实例以使用 IAM 数据库身份验证。
将 IAM 用户、服务账号或群组添加到数据库。如需了解详情，请参阅将 IAM 用户或服务账号添加到数据库和将群组添加到数据库。
将 roles/cloudsql.instanceUser IAM 角色添加到您的 IAM 用户、服务账号或群组。这是一个预定义角色，其中包含必要的 Cloud SQL IAM cloudsql.instances.login 权限。您需要此权限才能使用 IAM 数据库身份验证登录数据库实例。如需了解详情，请参阅角色和权限。
默认情况下，将 IAM 用户添加到数据库时，新数据库用户无权访问任何数据库。您需要使用 GRANT 命令向 IAM 数据库用户授予任何必要的权限。如需了解详情，请参阅向 IAM 用户授予数据库权限和向群组授予数据库权限。
如果您使用的是 IAM 群组身份验证，则 IAM 用户或服务账号必须是已获授予 IAM 角色或权限以登录 Cloud SQL 实例的群组的成员。Cloud SQL 会在用户或服务账号首次登录实例后创建一个账号。

使用自动 IAM 数据库身份验证登录

您可以将 Cloud SQL 连接器配置为代表用户或应用自动处理向 Cloud SQL 实例进行身份验证的操作。连接器包括 Cloud SQL Auth 代理、Go 连接器、Java 连接器和 Python 连接器，所有这些连接器均支持自动 IAM 数据库身份验证。将 Cloud SQL 连接器与自动 IAM 数据库身份验证搭配使用时，用于启动连接器的 IAM 账号必须是向数据库进行身份验证的同一账号。

如需使用自动 IAM 数据库身份验证登录，请执行以下操作：

Cloud SQL Auth 代理

向 Google Cloud 进行身份验证。

用户

使用应用默认凭据 (ADC) 向 Google Cloud 进行身份验证。

使用 gcloud auth application-default login 命令。如需了解详情，请参阅设置应用默认凭据。

服务账号

如需使用服务账号通过 ADC 向 Google Cloud 进行身份验证，您可以使用服务账号模拟或使用服务账号密钥。如需使用服务账号模拟，请替换 SERVICE_ACCOUNT_EMAIL_ADDRESS 并运行以下命令：
```
gcloud auth application-default login --impersonate-service-account SERVICE_ACCOUNT_EMAIL_ADDRESS
```
如需了解详情，请参阅设置应用默认凭据。
使用 --auto-iam-authn 标志启动 Cloud SQL Auth 代理。

请替换以下内容：
- INSTANCE_CONNECTION_NAME：用于标识 Cloud SQL 实例的连接字符串。如果您不使用默认 PostgreSQL 端口，请指定端口号。如需详细了解如何找到并构建此字符串，请参阅用于对 Cloud SQL Auth 代理进行身份验证的选项。
```
./cloud-sql-proxy --auto-iam-authn INSTANCE_CONNECTION_NAME
```
如需详细了解如何启动代理，请参阅启动 Cloud SQL Auth 代理。

警告：如果您将 Cloud SQL Auth 代理作为服务运行，请注意它会代表您的应用请求访问令牌。因此，请确保只有受信任的用户才能访问 Cloud SQL Auth 代理正在侦听的地址和端口或 Unix 套接字。
当您准备好使用 Cloud SQL Auth 代理连接到实例时，请使用 psql 客户端登录。

替换以下内容：
- HOSTNAME：Cloud SQL Auth 代理使用的 IP 地址。默认情况下，Cloud SQL Auth 代理使用 127.0.0.1 的 localhost 地址，但您可以在启动 Cloud SQL Auth 代理时分配其他 IP 地址。
- USERNAME：对于 IAM，用户名是用户的完整电子邮件地址。对于服务账号，这是服务账号的电子邮件地址（不带 .gserviceaccount.com 域名后缀）。
- PORT_NUMBER：可选。如果您在实例连接字符串中指定了其他端口，请指定该端口号。
- DATABASE_NAME：要连接的数据库名称。
运行以下命令：
```
psql -h HOSTNAME \
 -U USERNAME \
 --port PORT_NUMBER \
 --dbname=DATABASE_NAME
 
```
如需详细了解如何连接到 Cloud SQL Auth 代理，请参阅使用 psql 客户端连接。

Go

import (
	"context"
	"database/sql"
	"fmt"
	"log"
	"net"
	"os"

	"cloud.google.com/go/cloudsqlconn"
	"github.com/jackc/pgx/v5"
	"github.com/jackc/pgx/v5/stdlib"
)

func connectWithConnectorIAMAuthN() (*sql.DB, error) {
	mustGetenv := func(k string) string {
		v := os.Getenv(k)
		if v == "" {
			log.Fatalf("Warning: %s environment variable not set.", k)
		}
		return v
	}
	// Note: Saving credentials in environment variables is convenient, but not
	// secure - consider a more secure solution such as
	// Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
	// keep secrets safe.
	var (
		dbUser                 = mustGetenv("DB_IAM_USER")              // e.g. 'service-account-name@project-id.iam'
		dbName                 = mustGetenv("DB_NAME")                  // e.g. 'my-database'
		instanceConnectionName = mustGetenv("INSTANCE_CONNECTION_NAME") // e.g. 'project:region:instance'
		usePrivate             = os.Getenv("PRIVATE_IP")
	)

	d, err := cloudsqlconn.NewDialer(context.Background(), cloudsqlconn.WithIAMAuthN())
	if err != nil {
		return nil, fmt.Errorf("cloudsqlconn.NewDialer: %w", err)
	}
	var opts []cloudsqlconn.DialOption
	if usePrivate != "" {
		opts = append(opts, cloudsqlconn.WithPrivateIP())
	}

	dsn := fmt.Sprintf("user=%s database=%s", dbUser, dbName)
	config, err := pgx.ParseConfig(dsn)
	if err != nil {
		return nil, err
	}

	config.DialFunc = func(ctx context.Context, network, instance string) (net.Conn, error) {
		return d.Dial(ctx, instanceConnectionName, opts...)
	}
	dbURI := stdlib.RegisterConnConfig(config)
	dbPool, err := sql.Open("pgx", dbURI)
	if err != nil {
		return nil, fmt.Errorf("sql.Open: %w", err)
	}
	return dbPool, nil
}

Java JDBC

import com.zaxxer.hikari.HikariConfig;
import com.zaxxer.hikari.HikariDataSource;
import javax.sql.DataSource;

public class ConnectorIamAuthnConnectionPoolFactory extends ConnectionPoolFactory {

  // Note: Saving credentials in environment variables is convenient, but not
  // secure - consider a more secure solution such as
  // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
  // keep secrets safe.
  private static final String INSTANCE_CONNECTION_NAME =
      System.getenv("INSTANCE_CONNECTION_NAME");
  private static final String DB_IAM_USER = System.getenv("DB_IAM_USER");
  private static final String DB_NAME = System.getenv("DB_NAME");

  public static DataSource createConnectionPool() {
    // The configuration object specifies behaviors for the connection pool.
    HikariConfig config = new HikariConfig();

    // The following URL is equivalent to setting the config options below:
    // jdbc:postgresql:///<DB_NAME>?cloudSqlInstance=<INSTANCE_CONNECTION_NAME>&
    // socketFactory=com.google.cloud.sql.postgres.SocketFactory&user=<DB_IAM_USER>&
    // password=password
    // See the link below for more info on building a JDBC URL for the Cloud SQL JDBC Socket Factory
    // https://github.com/GoogleCloudPlatform/cloud-sql-jdbc-socket-factory#creating-the-jdbc-url

    // Configure which instance and what database to connect with.
    config.setJdbcUrl(String.format("jdbc:postgresql:///%s", DB_NAME));

    config.addDataSourceProperty("socketFactory", "com.google.cloud.sql.postgres.SocketFactory");
    config.addDataSourceProperty("cloudSqlInstance", INSTANCE_CONNECTION_NAME);

    // If connecting using automatic database authentication, follow the instructions for
    // connecting using the connector, but set the DB_IAM_USER value to an IAM user or
    // service account that has been given access to the database.
    // See https://cloud.google.com/sql/docs/postgres/iam-logins for more details.
    config.addDataSourceProperty("enableIamAuth", "true");
    config.addDataSourceProperty("user", DB_IAM_USER);
    // Password must be set to a nonempty value to bypass driver validation errors.
    config.addDataSourceProperty("password", "password");
    // Explicitly set sslmode to disable to prevent driver from hanging.
    // The Java Connector will handle SSL so it is unneccesary to enable it at the driver level.
    config.addDataSourceProperty("sslmode", "disable");


    // ... Specify additional connection properties here.
    // ...

    // Initialize the connection pool using the configuration object.
    return new HikariDataSource(config);
  }
}

Java R2DBC

private static final String CONNECTION_NAME = System.getenv("POSTGRES_IAM_CONNECTION_NAME");
private static final String DB_NAME = System.getenv("POSTGRES_DB");
private static final String DB_USER = System.getenv("POSTGRES_IAM_USER");
  // Set up ConnectionFactoryOptions
  ConnectionFactoryOptions options =
      ConnectionFactoryOptions.builder()
          .option(DRIVER, "gcp")
          .option(PROTOCOL, "postgresql")
          // Password must be set to a nonempty value to bypass driver validation errors
          .option(PASSWORD, "password")
          .option(USER, DB_USER)
          .option(DATABASE, DB_NAME)
          .option(HOST, CONNECTION_NAME)
          .option(ENABLE_IAM_AUTH, true)
          .build();

  // Initialize connection pool
  ConnectionFactory connectionFactory = ConnectionFactories.get(options);
  ConnectionPoolConfiguration configuration =
      ConnectionPoolConfiguration.builder(connectionFactory).build();

  this.connectionPool = new ConnectionPool(configuration);

Python

import os

from google.cloud.sql.connector import Connector, IPTypes
import pg8000

import sqlalchemy


def connect_with_connector_auto_iam_authn() -> sqlalchemy.engine.base.Engine:
    """
    Initializes a connection pool for a Cloud SQL instance of Postgres.

    Uses the Cloud SQL Python Connector with Automatic IAM Database Authentication.
    """
    # Note: Saving credentials in environment variables is convenient, but not
    # secure - consider a more secure solution such as
    # Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
    # keep secrets safe.
    instance_connection_name = os.environ[
        "INSTANCE_CONNECTION_NAME"
    ]  # e.g. 'project:region:instance'
    db_iam_user = os.environ["DB_IAM_USER"]  # e.g. 'sa-name@project-id.iam'
    db_name = os.environ["DB_NAME"]  # e.g. 'my-database'

    ip_type = IPTypes.PRIVATE if os.environ.get("PRIVATE_IP") else IPTypes.PUBLIC

    # initialize Cloud SQL Python Connector object
    connector = Connector()

    def getconn() -> pg8000.dbapi.Connection:
        conn: pg8000.dbapi.Connection = connector.connect(
            instance_connection_name,
            "pg8000",
            user=db_iam_user,
            db=db_name,
            enable_iam_auth=True,
            ip_type=ip_type,
        )
        return conn

    # The Cloud SQL Python Connector can be used with SQLAlchemy
    # using the 'creator' argument to 'create_engine'
    pool = sqlalchemy.create_engine(
        "postgresql+pg8000://",
        creator=getconn,
        # ...
    )
    return pool

使用手动 IAM 数据库身份验证登录

用户或应用可以这样向数据库进行身份验证：使用 IAM，向 Google Cloud 手动请求访问令牌并将其提供给数据库。使用 gcloud CLI，您可以明确请求一个具有 Cloud SQL Admin API 范围的 OAuth 2.0 令牌，用于登录数据库。当您使用手动 IAM 数据库身份验证以数据库用户身份登录时，将您的电子邮件地址用作用户名，并将访问令牌用作密码。您可以将此方法与数据库的直接连接或 Cloud SQL 连接器搭配使用。

在此过程中，您将向 Google Cloud 进行身份验证，请求访问令牌，然后通过将该令牌作为 IAM 数据库用户的密码传入来连接到数据库。请按照以下步骤在不使用 Cloud SQL Auth 代理的情况下进行连接。

对于这些步骤，您必须执行以下操作：

如果您要连接到具有公共 IP 的实例，请授予对实例的外部访问权限。如需了解详情，请参阅授权您机器的 IP 地址用于公共 IP 地址。

如果要连接到具有专用 IP 的实例，请在 Virtual Private Cloud (VPC) 网络中运行该命令。

使用 gcloud sql generate-login-token 命令生成身份验证令牌。

如需使用手动 IAM 数据库身份验证登录，请执行以下操作：

gcloud

向 Google Cloud 进行身份验证。

用户

使用 gcloud auth login 向 IAM 进行身份验证。如需了解详情，请参阅使用用户账号进行授权。

服务账号

使用 gcloud auth activate-service-account 向 IAM 进行身份验证。如需了解详情，请参阅使用服务账号进行授权。
请求访问令牌并使用客户端登录。

警告：您可以使用 OAuth 2.0 令牌代表您发出经过身份验证的请求。请务必确保其安全性，并注意存储位置。

替换以下内容：
- HOSTNAME：实例的 IP 地址，即公共 IP 地址或专用 IP 地址。
- USERNAME：对于 IAM，用户名是用户的完整电子邮件地址。对于服务账号，这是服务账号的电子邮件地址（不带 .gserviceaccount.com 域名后缀）。
- DATABASE_NAME：要连接的数据库名称。
```
 PGPASSWORD=`gcloud sql generate-login-token` \
 psql "sslmode=require \
 hostaddr=HOSTNAME \
 user=USERNAME \
 dbname=DATABASE_NAME" \
 --no-password
 
```
如果 Cloud SQL 实例上的 ssl_mode 配置为 TRUSTED_CLIENT_CERTIFICATE_REQUIRED，我们建议您使用自动 IAM 数据库身份验证登录，以强制执行客户端身份验证。

注意：不能直接将 OAuth 2.0 令牌输入或粘贴到密码字段中，因为该令牌长度超过密码字段的最大大小。使用环境变量将身份验证令牌传递给命令。提供的命令适用于 Unix/Linux 环境。如果您使用的是 Microsoft Windows，请替换为 Windows 环境变量设置。