Se connecter à l'aide du proxy d'authentification AlloyDB

Cette page explique comment configurer et utiliser le proxy d'authentification AlloyDB pour établir des connexions autorisées et chiffrées aux instances AlloyDB. Pour obtenir une présentation conceptuelle du proxy d'authentification, consultez À propos du proxy d'authentification AlloyDB.

Pour utiliser le proxy d'authentification AlloyDB, vous devez effectuer plusieurs étapes de configuration ponctuelles, puis démarrer le client du proxy d'authentification et vous connecter aux bases de données à l'aide de celui-ci :

1. Étapes de configuration :
   1. Téléchargez le client proxy d'authentification sur votre hôte client.
   2. Choisissez le compte principal Identity and Access Management (IAM) à utiliser pour l'autorisation, assurez-vous qu'il dispose des autorisations requises et que ses identifiants sont disponibles sur votre hôte client.
   3. Collectez les URI de connexion pour les instances AlloyDB auxquelles vous souhaitez vous connecter.
2. Démarrez le client proxy d'authentification sur votre hôte client.
3. Connectez une application à une base de données en ouvrant une connexion locale au client du proxy d'authentification.

Télécharger le client proxy d'authentification

La machine sur laquelle vous téléchargez le client Auth Proxy dépend de l'endroit depuis lequel vous souhaitez vous connecter à vos instances AlloyDB : depuis leur réseau VPC ou depuis l'extérieur.

Si vous souhaitez vous connecter à votre cluster à l'aide de l'accès aux services privés, vous pouvez télécharger le client Auth Proxy sur une instance de machine virtuelle (VM) Compute Engine s'exécutant dans le réseau VPC qui dispose d'un accès aux services privés à votre cluster.

Si vous prévoyez de vous connecter à votre cluster depuis l'extérieur du VPC, la machine sur laquelle vous l'installez dépend de la stratégie de connexion externe que vous utilisez. Par exemple, vous pouvez installer le client Auth Proxy sur une machine macOS ou Windows locale à votre application, puis utiliser un serveur SOCKS exécuté dans votre réseau VPC AlloyDB comme intermédiaire de connexion. Pour en savoir plus, consultez Se connecter à un cluster depuis l'extérieur de son VPC.

docker pull gcr.io/alloydb-connectors/alloydb-auth-proxy:latest

Choisir le compte principal IAM et le préparer pour l'autorisation

Le proxy d'authentification AlloyDB est compatible avec l'utilisation de ces types de principaux IAM pour autoriser les connexions entre votre client et une instance AlloyDB :

• Un compte de service géré par l'utilisateur. Vous pouvez créer un compte de service IAM pour votre application, puis autoriser les connexions à l'aide de ce compte.

  Google vous recommande vivement d'utiliser un compte de service pour l'autorisation dans les environnements de production.

• Votre compte utilisateur Vous pouvez utiliser votre propre compte utilisateur IAM pour autoriser les connexions.

  Il est pratique d'utiliser votre propre compte utilisateur dans les environnements de développement où vous gérez les ressources AlloyDB à l'aide de la gcloud CLI, développez la base de données à l'aide d'un outil tel que psql et développez le code d'application sur le même hôte.

• Compte de service Compute Engine par défaut : Si l'hôte client est une instance Compute Engine, vous pouvez utiliser le compte de service Compute Engine par défaut pour autoriser les connexions.

Après avoir choisi le compte principal IAM à utiliser, vous devez vous assurer qu'il dispose des autorisations IAM requises et que ses identifiants sont disponibles sur votre hôte client.

Autorisations IAM requises

Le compte principal IAM que vous utilisez pour autoriser les connexions doit disposer des autorisations fournies par les rôles prédéfinis roles/alloydb.client (client AlloyDB pour Cloud) et roles/serviceusage.serviceUsageConsumer (consommateur Service Usage).

Pour attribuer le rôle Client Cloud AlloyDB à un principal IAM :

• L'API Cloud Resource Manager doit être activée dans le projet Google Cloud .

• Vous devez disposer du rôle IAM de base roles/owner (propriétaire) dans le projetGoogle Cloud , ou d'un rôle qui vous accorde les autorisations suivantes :

  • resourcemanager.projects.get
  • resourcemanager.projects.getIamPolicy
  • resourcemanager.projects.setIamPolicy

  Pour obtenir ces autorisations tout en suivant le principe du moindre privilège, demandez à votre administrateur de vous attribuer le rôle roles/resourcemanager.projectIamAdmin (Administrateur IAM du projet).

Rendre les identifiants IAM disponibles sur l'hôte client

La façon dont vous mettez les identifiants IAM à disposition sur l'hôte client dépend du type de compte principal IAM que vous utilisez pour autoriser les connexions :

• Compte de service géré par l'utilisateur

  Pour fournir des identifiants IAM pour un compte de service géré par l'utilisateur, créez une clé de compte de service au format JSON et téléchargez-la sur votre hôte client. Lorsque vous démarrez le client Auth Proxy, spécifiez l'emplacement du fichier de clé à l'aide de l'option --credentials-file.

• Votre compte utilisateur

  Pour fournir des identifiants IAM pour votre compte utilisateur, installez Google Cloud CLI sur votre hôte client, puis exécutez la commande gcloud init pour l'initialiser à l'aide de votre compte utilisateur. Lorsque vous démarrez le client Auth Proxy, il découvre et utilise automatiquement les identifiants de votre compte utilisateur si vous ne fournissez pas d'identifiants de compte de service géré par l'utilisateur.

• Compte de service Compute Engine par défaut

  Si vous utilisez une instance Compute Engine comme hôte client, les identifiants du compte de service Compute Engine par défaut sont déjà présents sur l'hôte. Lorsque vous démarrez le client Auth Proxy, il découvre et utilise automatiquement ces identifiants si les identifiants de compte de service géré par l'utilisateur et de compte utilisateur ne sont pas disponibles.

Collecter les URI de connexion pour les instances AlloyDB

Lorsque vous démarrez le client Auth Proxy, vous identifiez la ou les instances AlloyDB auxquelles vous souhaitez vous connecter à l'aide de ce format d'URI de connexion :

projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID

Pour afficher la liste des URI de connexion de toutes vos instances, utilisez la commande alloydb instances list de la gcloud CLI.

Récupérez l'URI de connexion de chaque instance à laquelle vous souhaitez vous connecter.

Démarrer le client du proxy d'authentification

Lorsque vous démarrez le client Auth Proxy, vous lui fournissez des informations sur les instances AlloyDB auxquelles se connecter et, si nécessaire, des informations d'identification à utiliser lors de l'autorisation de ces connexions.

Lorsqu'il démarre, le client du proxy d'authentification :

• Autorise les connexions aux instances AlloyDB à l'aide des identifiants et des autorisations IAM du principal IAM que vous avez configuré. Il recherche les identifiants en suivant une séquence d'étapes spécifique.
• Autorise automatiquement les connexions à l'adresse IP publique au réseau source si l'adresse IP publique est activée pour l'instance.
• Configure une connexion privée TLS 1.3 au serveur proxy d'authentification de chaque instance.
• Commence à écouter les demandes de connexion des clients locaux.

Par défaut, le client Auth Proxy écoute les connexions TCP sur l'adresse IP 127.0.0.1, en commençant par le port 5432 et en incrémentant le numéro de port de un pour chaque instance AlloyDB au-delà de la première. Vous pouvez spécifier une autre adresse d'écouteur et d'autres ports lorsque vous démarrez le client Auth Proxy.

./alloydb-auth-proxy INSTANCE_URI... \
    [ --credentials-file PATH_TO_KEY_FILE \ ]
    [ --token OAUTH_ACCESS_TOKEN \ ]
    [ --port INITIAL_PORT_NUMBER \ ]
    [ --address LOCAL_LISTENER_ADDRESS \ ]
    [ --auto-iam-authn \ ]
    [ --psc \ ]
    [ --public-ip \ ]
    [ --disable-built-in-telemetry ]

docker run \
  --publish 127.0.0.1:PORT:PORT \
  gcr.io/alloydb-connectors/alloydb-auth-proxy:latest \
  --address 0.0.0.0 \
  --port PORT \
  INSTANCE_URI

docker run \
  --volume PATH_TO_KEY_FILE:/key.json \
  --publish 127.0.0.1:PORT:PORT \
  gcr.io/alloydb-connectors/alloydb-auth-proxy:latest \
  --address 0.0.0.0 \
  --port PORT \
  --credentials-file=/key.json \
  INSTANCE_URI

Exemples de start-up

Les exemples suivants montrent différentes façons de démarrer le client Auth Proxy. Ils utilisent les URI de connexion d'instance suivants :

projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary

projects/myproject/locations/us-central1/clusters/mycluster/instances/myreadpool

Démarrage de base

./alloydb-auth-proxy \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary"

Dans cet exemple, le client du proxy d'authentification autorise la connexion en suivant sa séquence normale d'étapes d'autorisation, puis commence à écouter les connexions locales à l'instance myprimary sur 127.0.0.1:5432.

Démarrage à l'aide d'un compte de service géré par l'utilisateur

./alloydb-auth-proxy \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary" \\
  --credentials-file "myappaccount/key.json"

Dans cet exemple, le client du proxy d'authentification autorise la connexion à l'aide de la clé JSON du compte de service géré par l'utilisateur stockée à l'emplacement myappaccount/key.json, puis commence à écouter les connexions locales à l'instance myprimary sur 127.0.0.1:5432.

Démarrage de la connexion à plusieurs instances

./alloydb-auth-proxy \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary" \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myreadpool"

Dans cet exemple, le client du proxy d'authentification autorise la connexion en suivant sa séquence normale d'étapes d'autorisation, puis commence à écouter les connexions locales à l'instance myprimary sur 127.0.0.1:5432 et à l'instance myreadpool sur 127.0.0.1:5433.

Démarrage de l'écoute sur des ports personnalisés

L'utilisation de ports personnalisés pour le client du proxy d'authentification peut être utile lorsque vous devez réserver le port 5432 pour d'autres connexions PostgreSQL.

./alloydb-auth-proxy \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary?port=5000" \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myreadpool?port=5001"

Dans cet exemple, le client du proxy d'authentification autorise la connexion en suivant sa séquence normale d'étapes d'autorisation, puis commence à écouter les connexions locales à l'instance myprimary sur 127.0.0.1:5000 et à l'instance myreadpool sur 127.0.0.1:5001.

Étant donné que ces ports personnalisés sont séquentiels, le même effet peut être obtenu à l'aide de cette commande de démarrage :

./alloydb-auth-proxy \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary" \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myreadpool" \
  --port 5000

Démarrage de l'écoute sur une adresse IP personnalisée

./alloydb-auth-proxy \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary" \
  --address "0.0.0.0"

Dans cet exemple, le client du proxy d'authentification autorise la connexion en suivant sa séquence normale d'étapes d'autorisation, puis commence à écouter les connexions locales à l'instance myprimary sur 0.0.0.0:5432.

Connecter une application à une base de données à l'aide du proxy d'authentification AlloyDB

Les exemples suivants montrent comment connecter une application à une base de données à l'aide du proxy d'authentification AlloyDB.

L'exemple psql montre comment connecter un outil de ligne de commande.

Pour plusieurs langages de programmation, la connexion à une instance AlloyDB à l'aide du proxy d'authentification AlloyDB est identique à la connexion à une instance Cloud SQL pour PostgreSQL à l'aide du proxy d'authentification Cloud SQL. Les exemples de langage présentés ici sont donc les mêmes que ceux pour Cloud SQL pour PostgreSQL.

Ces exemples sont basés sur un démarrage par défaut du client Auth Proxy afin qu'il écoute les connexions TCP locales sur 127.0.0.1:5432.

psql -h 127.0.0.1 -p 5432 -U DB_USER

import os

import sqlalchemy


# connect_tcp_socket initializes a TCP connection pool
# for an AlloyDB instance.
def connect_tcp_socket() -> sqlalchemy.engine.base.Engine:
    # 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_HOST = os.environ[
        "INSTANCE_HOST"
    ]  # e.g. '127.0.0.1' ('172.17.0.1' if deployed to GAE Flex)
    db_user = os.environ["DB_USER"]  # e.g. 'my-db-user'
    db_pass = os.environ["DB_PASS"]  # e.g. 'my-db-password'
    db_name = os.environ["DB_NAME"]  # e.g. 'my-database'
    db_port = os.environ["DB_PORT"]  # e.g. 5432

    pool = sqlalchemy.create_engine(
        # Equivalent URL:
        # postgresql+pg8000://<db_user>:<db_pass>@<INSTANCE_HOST>:<db_port>/<db_name>
        sqlalchemy.engine.url.URL.create(
            drivername="postgresql+pg8000",
            username=db_user,
            password=db_pass,
            host=INSTANCE_HOST,
            port=db_port,
            database=db_name,
        ),
        # ...
    )
    return pool

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

public class TcpConnectionPoolFactory 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 DB_USER = System.getenv("DB_USER");
  private static final String DB_PASS = System.getenv("DB_PASS");
  private static final String DB_NAME = System.getenv("DB_NAME");

  private static final String INSTANCE_HOST = System.getenv("INSTANCE_HOST");
  private static final String DB_PORT = System.getenv("DB_PORT");


  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://<INSTANCE_HOST>:<DB_PORT>/<DB_NAME>?user=<DB_USER>&password=<DB_PASS>l

    // Configure which instance and what database user to connect with.
    config.setJdbcUrl(String.format("jdbc:postgresql://%s:%s/%s", INSTANCE_HOST, DB_PORT, DB_NAME));
    config.setUsername(DB_USER); // e.g. "root", "postgres"
    config.setPassword(DB_PASS); // e.g. "my-password"



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

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

const Knex = require('knex');
const fs = require('fs');

// createTcpPool initializes a TCP connection pool for an AlloyDB cluster.
const createTcpPool = async config => {
  // 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.
  const dbConfig = {
    client: 'pg',
    connection: {
      host: process.env.INSTANCE_HOST, // e.g. '127.0.0.1'
      port: process.env.DB_PORT, // e.g. '5432'
      user: process.env.DB_USER, // e.g. 'my-user'
      password: process.env.DB_PASS, // e.g. 'my-user-password'
      database: process.env.DB_NAME, // e.g. 'my-database'
    },
    // ... Specify additional properties here.
    ...config,
  };
  // Establish a connection to the database.
  return Knex(dbConfig);
};

package alloydb

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

	// Note: If connecting using the App Engine Flex Go runtime, use
	// "github.com/jackc/pgx/stdlib" instead, since v4 requires
	// Go modules which are not supported by App Engine Flex.
	_ "github.com/jackc/pgx/v5/stdlib"
)

// connectTCPSocket initializes a TCP connection pool for an AlloyDB cluster.
func connectTCPSocket() (*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_USER")       // e.g. 'my-db-user'
		dbPwd     = mustGetenv("DB_PASS")       // e.g. 'my-db-password'
		dbTCPHost = mustGetenv("INSTANCE_HOST") // e.g. '127.0.0.1' or IP Address of Cluster
		dbPort    = mustGetenv("DB_PORT")       // e.g. '5432'
		dbName    = mustGetenv("DB_NAME")       // e.g. 'my-database'
	)

	dbURI := fmt.Sprintf("host=%s user=%s password=%s port=%s database=%s",
		dbTCPHost, dbUser, dbPwd, dbPort, dbName)

	// dbPool is the pool of database connections.
	dbPool, err := sql.Open("pgx", dbURI)
	if err != nil {
		return nil, fmt.Errorf("sql.Open: %v", err)
	}

	// ...

	return dbPool, nil
}

using Npgsql;
using System;

namespace CloudSql
{
    public class PostgreSqlTcp
    {
        public static NpgsqlConnectionStringBuilder NewPostgreSqlTCPConnectionString()
        {
            // Equivalent connection string:
            // "Uid=<DB_USER>;Pwd=<DB_PASS>;Host=<INSTANCE_HOST>;Database=<DB_NAME>;"
            var connectionString = new NpgsqlConnectionStringBuilder()
            {
                // 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.
                Host = Environment.GetEnvironmentVariable("INSTANCE_HOST"),     // e.g. '127.0.0.1'
                // Set Host to 'cloudsql' when deploying to App Engine Flexible environment
                Username = Environment.GetEnvironmentVariable("DB_USER"), // e.g. 'my-db-user'
                Password = Environment.GetEnvironmentVariable("DB_PASS"), // e.g. 'my-db-password'
                Database = Environment.GetEnvironmentVariable("DB_NAME"), // e.g. 'my-database'

                // The Cloud SQL proxy provides encryption between the proxy and instance.
                SslMode = SslMode.Disable,
            };
            connectionString.Pooling = true;
            // Specify additional properties here.
            return connectionString;
        }
    }
}

development:
  adapter: postgresql
  # Configure additional properties here.
  username: <%= ENV["DB_USER"] %>  # e.g. "my-database-user"
  password: <%= ENV["DB_PASS"] %> # e.g. "my-database-password"
  database: <%= ENV.fetch("DB_NAME") { "vote_development" } %>
  host: <%= ENV.fetch("DB_HOST") { "127.0.0.1" }%> # '172.17.0.1' if deployed to GAE Flex
  port: <%= ENV.fetch("DB_PORT")  { 5432 }%>

// $username = 'your_db_user';
// $password = 'yoursupersecretpassword';
// $dbName = 'your_db_name';
// $dbHost = "127.0.0.1";

// Connect using TCP
$dsn = sprintf('pgsql:dbname=%s;host=%s', $dbName, $dbHost);

// Connect to the database
$conn = new PDO($dsn, $username, $password, $connConfig);