Mit IAM-Datenbankauthentifizierung anmelden

MySQL | PostgreSQL | SQL Server

Auf dieser Seite wird beschrieben, wie sich Nutzer und Dienstkonten mithilfe der Cloud SQL-IAM-Datenbankauthentifizierung in Cloud SQL-Datenbanken anmelden können. Weitere Informationen finden Sie unter IAM-Authentifizierung.

Hinweise

Konfigurieren Sie die Instanz, um die IAM-Datenbankauthentifizierung zu verwenden. Weitere Informationen finden Sie unter Neue Instanzen für die IAM-Datenbankauthentifizierung konfigurieren.
Fügen Sie der Datenbank einen IAM-Nutzer, ein Dienstkonto oder eine Gruppe hinzu. Weitere Informationen finden Sie unter IAM-Nutzer oder Dienstkonto zur Datenbank hinzufügen und Gruppe zur Datenbank hinzufügen.
Fügen Sie Ihrem IAM-Nutzer, -Dienstkonto oder Ihrer Gruppe die IAM-Rolle roles/cloudsql.instanceUser hinzu. Dies ist eine vordefinierte Rolle, die die erforderliche Cloud SQL-IAM-Berechtigung cloudsql.instances.login enthält. Sie benötigen diese Berechtigung, um sich mit der IAM-Datenbankauthentifizierung bei einer Datenbankinstanz anzumelden. Weitere Informationen finden Sie unter Rollen und -Berechtigungen.
Wenn ein IAM-Nutzer einer Datenbank hinzugefügt wird, erhält dieser neue Nutzer standardmäßig keine Berechtigungen für Datenbanken. Sie müssen den Befehl GRANT verwenden, um dem IAM-Datenbanknutzer alle erforderlichen Berechtigungen zu erteilen. Weitere Informationen finden Sie unter IAM-Nutzer Datenbankberechtigungen erteilen und Einer Gruppe Datenbankberechtigungen erteilen.
Wenn Sie die IAM-Gruppenauthentifizierung verwenden, muss das IAM-Nutzerkonto oder -Dienstkonto Mitglied einer Gruppe sein, der eine IAM-Rolle oder Berechtigungen zum Anmelden in der Cloud SQL-Instanz gewährt wurden. Cloud SQL erstellt ein Konto, nachdem sich der Nutzer oder das Dienstkonto zum ersten Mal bei der Instanz angemeldet hat.

Mit automatischer IAM-Datenbankauthentifizierung anmelden

Sie können einen Cloud SQL-Connector so konfigurieren, dass die Authentifizierung bei der Cloud SQL-Instanz automatisch im Namen eines Nutzers oder einer Anwendung ausgeführt wird. Connectors umfassen den Cloud SQL-Auth-proxy, den Go-Connector, den Java-Connector und den Python-Connector, die alle die automatische IAM-Datenbankauthentifizierung unterstützen. Wenn Sie einen Cloud SQL-Connector mit der automatischen IAM-Datenbankauthentifizierung verwenden, muss das IAM-Konto, mit dem Sie den Connector starten, mit dem Konto übereinstimmen, mit dem Sie sich bei der Datenbank authentifizieren.

So melden Sie sich mit der automatischen IAM-Datenbankauthentifizierung an:

Cloud SQL Auth-Proxy

Authentifizieren Sie sich bei Google Cloud.

Nutzer

Authentifizieren Sie sich mit Standardanmeldedaten für Anwendungen bei Google Cloud.

Führen Sie den Befehl gcloud auth application-default login aus. Weitere Informationen finden Sie unter Standardanmeldedaten für Anwendungen einrichten.

Dienstkonto

Wenn Sie sich mit Standardanmeldedaten für Anwendungen und einem Dienstkonto bei Google Cloud authentifizieren möchten, können Sie die Identitätsübernahme des Dienstkontos oder einen Dienstkontoschlüssel verwenden. Wenn Sie die Identitätsübernahme des Dienstkontos verwenden möchten, ersetzen Sie SERVICE_ACCOUNT_EMAIL_ADDRESS und führen Sie den folgenden Befehl aus:
```
gcloud auth application-default login --impersonate-service-account SERVICE_ACCOUNT_EMAIL_ADDRESS
```
Weitere Informationen finden Sie unter Standardanmeldedaten für Anwendungen einrichten.
Starten Sie den Cloud SQL Auth-Proxy mit dem Flag --auto-iam-authn.

Ersetzen Sie Folgendes:
- INSTANCE_CONNECTION_NAME ist der Verbindungsstring zur Identifizierung einer Cloud SQL-Instanz. Wenn Sie einen anderen Port als den PostgreSQL-Standardport verwenden, geben Sie die Portnummer an. Informationen dazu, wie Sie diesen String ermitteln und erstellen, finden Sie unter Optionen für die Authentifizierung des Cloud SQL Auth-Proxys.
```
./cloud-sql-proxy --auto-iam-authn INSTANCE_CONNECTION_NAME
```
Weitere Informationen zum Starten des Proxys finden Sie unter Cloud SQL Auth-Proxy starten.

Warnung: Wenn Sie den Cloud SQL Auth-Proxy als Dienst ausführen, müssen Sie beachten, dass dieser die Zugriffstokens für Ihre Anwendungen anfordert. Sorgen Sie deshalb dafür, dass nur vertrauenswürdige Nutzer auf die Adresse und auf den Port oder auf den Unix-Socket zugreifen können, den der Cloud SQL Auth-Proxy überwacht.
Wenn Sie mithilfe des Cloud SQL Auth-Proxys eine Verbindung zur Instanz herstellen möchten, melden Sie sich mit dem psql-Client an.

Ersetzen Sie Folgendes:
- HOSTNAME: IP-Adresse, die vom Cloud SQL Auth-Proxy verwendet wird. Standardmäßig verwendet der Cloud SQL Auth-Proxy die localhost-Adresse 127.0.0.1. Sie können jedoch beim Starten des Cloud SQL Auth-Proxys eine andere IP-Adresse zuweisen.
- USERNAME: Bei einem IAM ist der Nutzername die vollständige E-Mail-Adresse des Nutzers. Bei einem Dienstkonto ist dies die E-Mail-Adresse des Dienstkontos ohne das Domain-Suffix .gserviceaccount.com.
- PORT_NUMBER: Optional. Wenn Sie im Instanzverbindungsstring einen anderen Port angegeben haben, geben Sie diese Portnummer an.
- DATABASE_NAME: Der Name der Datenbank, zu der eine Verbindung hergestellt werden soll.
Führen Sie dazu diesen Befehl aus:
```
psql -h HOSTNAME \
 -U USERNAME \
 --port PORT_NUMBER \
 --dbname=DATABASE_NAME
 
```
Weitere Informationen zum Herstellen einer Verbindung zum Cloud SQL-Authentifizierungsproxy finden Sie unter Verbindung mit dem psql-Client herstellen.

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

Mit manueller IAM-Datenbankauthentifizierung anmelden

Ein Nutzer oder eine Anwendung kann sich mithilfe von IAM bei der Datenbank authentifizieren und dafür manuell ein Zugriffstoken von Google Cloud anfordern und es an die Datenbank übergeben. Mit der gcloud CLI haben Sie die Möglichkeit, explizit ein OAuth 2.0-Token im Geltungsbereich der Cloud SQL Admin API anzufordern, das für die Anmeldung bei der Datenbank verwendet wird. Wenn Sie sich als Datenbanknutzer mit der manuellen IAM-Datenbankauthentifizierung anmelden, verwenden Sie Ihre E-Mail-Adresse als Nutzernamen und das Zugriffstoken als Passwort. Sie können diese Methode entweder mit einer direkten Verbindung zur Datenbank oder mit einem Cloud SQL-Connector verwenden.

In diesem Verfahren authentifizieren Sie sich bei Google Cloud, fordern ein Zugriffstoken an und stellen dann eine Verbindung zur Datenbank her. Dazu übergeben Sie das Token als Passwort für den IAM-Datenbanknutzer. Führen Sie die folgenden Schritte aus, um eine Verbindung ohne den Cloud SQL-Authentifizierungsproxy herzustellen.

Für diese Schritte müssen Sie Folgendes tun:

Wenn Sie eine Verbindung zu einer Instanz mit öffentlicher IP-Adresse herstellen, müssen Sie den externen Zugriff auf die Instanz autorisieren. Weitere Informationen finden Sie unter IP-Adresse Ihres Computers für öffentliche IP-Adressen autorisieren.

Wenn Sie eine Verbindung zu einer Instanz mit privater IP-Adresse herstellen, führen Sie den Befehl im VPC-Netzwerk (Virtual Private Cloud) aus.

Verwenden Sie den Befehl gcloud sql generate-login-token, um ein Authentifizierungstoken zu generieren.

So melden Sie sich mit der manuellen IAM-Datenbankauthentifizierung an:

gcloud

Authentifizieren Sie sich bei Google Cloud.

Nutzer

Authentifizieren Sie sich mit gcloud auth login bei IAM. Weitere Informationen finden Sie unter Mit Nutzerkonten autorisieren.

Dienstkonto

Authentifizieren Sie sich mit gcloud auth activate-service-account bei IAM. Weitere Informationen finden Sie unter Mit Dienstkonto autorisieren.
Fordern Sie das Zugriffstoken an und melden Sie sich bei einem Client an.

Warnung: Sie können Ihr OAuth 2.0-Token verwenden, um authentifizierte Anfragen in Ihrem Namen zu stellen. Bewahren Sie es sicher auf und achten Sie darauf, wo Sie es speichern.

Ersetzen Sie Folgendes:
- HOSTNAME: Die IP-Adresse der Instanz, entweder die öffentliche oder die private IP-Adresse.
- USERNAME: Bei einem IAM ist der Nutzername die vollständige E-Mail-Adresse des Nutzers. Bei einem Dienstkonto ist dies die E-Mail-Adresse des Dienstkontos ohne das Domain-Suffix .gserviceaccount.com.
- DATABASE_NAME: Der Name der Datenbank, zu der eine Verbindung hergestellt werden soll.
```
 PGPASSWORD=`gcloud sql generate-login-token` \
 psql "sslmode=require \
 hostaddr=HOSTNAME \
 user=USERNAME \
 dbname=DATABASE_NAME" \
 --no-password
 
```
Wenn ssl_mode auf Ihrer Cloud SQL-Instanz als TRUSTED_CLIENT_CERTIFICATE_REQUIRED konfiguriert ist, empfehlen wir, dass Sie sich mit der automatischen IAM-Datenbankauthentifizierung anmelden, um die Validierung der Clientidentität zu erzwingen.

Hinweis: Das OAuth 2.0-Token kann nicht in ein Passwortfeld eingegeben oder direkt eingefügt werden, da dieses Token die Maximalgröße des Felds überschreitet. Verwenden Sie eine Umgebungsvariable, um das Authentifizierungstoken an den Befehl zu übergeben. Der bereitgestellte Befehl gilt für Unix/Linux-Umgebungen. Wenn Sie Microsoft Windows verwenden, ersetzen Sie die Einstellungen für die Windows-Umgebungsvariablen.