Connect using the AlloyDB Auth Proxy

This page shows how to set up and use the AlloyDB Auth Proxy to make authorized, encrypted connections to AlloyDB instances. For a conceptual overview of the Auth Proxy, see About the AlloyDB Auth Proxy.

To use the AlloyDB Auth Proxy, you perform several one-time setup steps, then you start the Auth Proxy client, and then you connect to databases using it:

1. Setup steps:
   1. Download the Auth Proxy client to your client host.
   2. Choose the IAM principal to use for authorization, make sure it has the required permissions, and make its credentials are available on your client host.
   3. Gather connection URIs for the AlloyDB instances you want to connect to.
2. Start the Auth Proxy client on your client host.
3. Connect an application to a database by opening a local connection to the Auth Proxy client.

Before you begin

The client host must meet these requirements:

• It must have network visibility to the Virtual Private Cloud (VPC) network where the instances you want to connect to reside. Client hosts (like Compute Engine instances) in this Virtual Private Cloud (VPC) network inherently have this visibility. Client hosts in external networks (on-premises networks or different VPC networks) have this visibility if the AlloyDB instance's VPC network has been connected to the external network using a Cloud VPN tunnel or a VLAN attachment for Dedicated Interconnect or Partner Interconnect.

• If the client host has an outbound firewall policy, it must allow outgoing connections to port 5433 on your AlloyDB instances' IP addresses and allow outgoing connections to port 443 (the standard HTTPS port) to all IP addresses.

• If you are using a Compute Engine instance as the client host, it must have the https://www.googleapis.com/auth/cloud-platform access scope so that it can use the AlloyDB Admin API. If necessary, change its access scope to include this scope.

Download the Auth Proxy client

The machine that you download the Auth Proxy client to depends on whether you want to connect to your AlloyDB instances from within its VPC network, or from outside of it.

If you want to connect to your cluster using private services access, then you can download the Auth Proxy client onto a Compute Engine virtual machine (VM) instance running within the VPC network that has private services access to your cluster.

If you intend to connect to your cluster from outside the VPC, then the machine you install it on depends on which external connection strategy you use. For example, you can install the Auth Proxy client onto a macOS or Windows machine that's local to your application, and then use a SOCKS server running within your AlloyDB VPC network as a connection intermediary. For more information, see Connect to a cluster from outside its VPC.

Linux

64-bit (AMD)

1. Download the Auth Proxy client:

   wget https://storage.googleapis.com/alloydb-auth-proxy/v1.11.3/alloydb-auth-proxy.linux.amd64 -O alloydb-auth-proxy
   

2. Make the Auth Proxy client executable:

   chmod +x alloydb-auth-proxy
   

32-bit (AMD)

1. Download the Auth Proxy client:

   wget https://storage.googleapis.com/alloydb-auth-proxy/v1.11.3/alloydb-auth-proxy.linux.386 -O alloydb-auth-proxy
   

2. Make the Auth Proxy client executable:

   chmod +x alloydb-auth-proxy
   

64-bit (ARM)

1. Download the Auth Proxy client:

   wget https://storage.googleapis.com/alloydb-auth-proxy/v1.11.3/alloydb-auth-proxy.linux.arm64 -O alloydb-auth-proxy
   

2. Make the Auth Proxy client executable:

   chmod +x alloydb-auth-proxy
   

32-bit (ARM)

1. Download the Auth Proxy client:

   wget https://storage.googleapis.com/alloydb-auth-proxy/v1.11.3/alloydb-auth-proxy.linux.arm -O alloydb-auth-proxy
   

2. Make the Auth Proxy client executable:

   chmod +x alloydb-auth-proxy
   

macOS

M1

1. Download the Auth Proxy client:

   curl -o alloydb-auth-proxy https://storage.googleapis.com/alloydb-auth-proxy/v1.11.3/alloydb-auth-proxy.darwin.arm64
   

2. Make the Auth Proxy client executable:

   chmod +x alloydb-auth-proxy
   

64-bit

1. Download the Auth Proxy client:

   curl -o alloydb-auth-proxy https://storage.googleapis.com/alloydb-auth-proxy/v1.11.3/alloydb-auth-proxy.darwin.amd64
   

2. Make the Auth Proxy client executable:

   chmod +x alloydb-auth-proxy
   

32-bit

1. Download the Auth Proxy client:

   curl -o alloydb-auth-proxy https://storage.googleapis.com/alloydb-auth-proxy/v1.11.3/alloydb-auth-proxy.darwin.386
   

2. Make the Auth Proxy client executable:

   chmod +x alloydb-auth-proxy
   

Windows

64-bit

Right-click https://storage.googleapis.com/alloydb-auth-proxy/v1.11.3/alloydb-auth-proxy-x64.exe and select Save Link As to download the Auth Proxy client. Rename the file to alloydb-auth-proxy.exe.

32-bit

Right-click https://storage.googleapis.com/alloydb-auth-proxy/v1.11.3/alloydb-auth-proxy-x86.exe and select Save Link As to download the Auth Proxy client. Rename the file to alloydb-auth-proxy.exe.

Docker image

For convenience, several container images that contain the Auth Proxy client are available in the Container Registry.

You can pull the latest image to your local machine using Docker with the following command:

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

Other OS

For other operating systems not included here, you can compile the Auth Proxy client from source.

Choose the IAM principal and prepare it for authorization

The AlloyDB Auth Proxy supports the use of these types of IAM principals to authorize connections between your client and an AlloyDB instance:

• A user-managed service account. You can create an IAM service account for your application and then authorize connections using it.

  Google strongly recommends that you use a service account for authorization in production environments.

• Your user account. You can use your own IAM user account to authorize connections.

  Using your own user account is convenient in development environments where you are managing AlloyDB resources using the gcloud CLI, developing the database using a tool like psql, and developing application code all on the same host.

• The Compute Engine default service account. If the client host is a Compute Engine instance, you can use the Compute Engine default service account to authorize connections.

After choosing which IAM principal to use, you need to make sure it has the required IAM permissions and make its credentials are available on your client host.

Required IAM permissions

The IAM principal you use to authorize connections must have the permissions provided by the roles/alloydb.client (Cloud AlloyDB Client) and roles/serviceusage.serviceUsageConsumer (Service Usage Consumer) predefined roles.

Note: The roles/alloydb.admin (Cloud AlloyDB Admin) role also provides the required permissions.

In order to assign the Cloud AlloyDB Client role to an IAM principal:

• The Cloud Resource Manager API must be enabled in the Google Cloud project.

• You must have the roles/owner (Owner) basic IAM role in the Google Cloud project, or a role that grants these permissions:

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

  To gain these permissions while following the principle of least privilege, ask your administrator to grant you the roles/resourcemanager.projectIamAdmin (Project IAM Admin) role.

Make IAM credentials available on the client host

How you make IAM credentials available on the client host depends on which type of IAM principal you are using to authorize connections:

• User-managed service account

  To provide IAM credentials for a user-managed service account, create a JSON-format service account key and download it to your client host. When you start the Auth Proxy client, specify the location of the key file using the --credentials-file flag.

• Your user account

  To provide IAM credentials for your user account, install the Google Cloud CLI on your client host and then run the gcloud init command to initialize it using your user account. When you start the Auth Proxy client, it automatically discovers and uses your user account credentials if you don't provide user-managed service account credentials.

• Compute Engine default service account

  If you are using a Compute Engine instance as your client host, the credentials for Compute Engine default service account are already on the host. When you start the Auth Proxy client, it automatically discovers and uses these credentials if user-managed service account and user account credentials are unavailable.

Gather connection URIs for the AlloyDB instances

When you start the Auth Proxy client, you identify the AlloyDB instance or instances you want to connect to using this connection URI format:

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

To see a list of all of your instances' connection URIs, use the gcloud CLI alloydb instances list command.

Gather the instance connection URI for each instance you want to connect to.

Start the Auth Proxy client

When you start the Auth Proxy client, you provide it information about what AlloyDB instances to connect to and, if necessary, credential information to use when authorizing these connections.

When it starts, the Auth Proxy client:

• Authorizes connections to AlloyDB instances using the credentials and IAM permissions of the IAM principal you have configured. It looks for credentials by following a specific sequence of steps.
• Configures a private, TLS 1.3 connection to each instance's Auth Proxy server.
• Begins listening for local client connection requests.

By default, the Auth Proxy client listens for TCP connections on IP address 127.0.0.1, starting at port 5432 and incrementing by one port number for each AlloyDB instance beyond the first. You can specify a different listener address and different ports when you start the Auth Proxy client.

Warning: Be careful when binding the Auth Proxy client to an external interface. Anyone with access to that interface/port will be authorized to connect to your instance.

Note: Google recommends that you run the Auth Proxy client as a persistent service in production environments.

Command line

./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]

Replace the following:

• INSTANCE_URI: the instance connection URI of an AlloyDB instance to connect to, specified using this format:

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

  You can override the default local listener port that the Auth Proxy client will use for the instance by adding the port query parameter to the URI:

  "projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID?port=PORT"

• Optional: PATH_TO_KEY_FILE: The path to the JSON key file of the user-managed service account to use for connection authorization.

• Optional: OAUTH_ACCESS_TOKEN: An OAuth2 token value to use for connection authorization.

• Optional: INITIAL_PORT_NUMBER: The starting port number to use instead of the default port 5432 when listening for local TCP connections.

• Optional: LOCAL_LISTENER_ADDRESS: The listener address to use instead of the default 127.0.0.1 when listening for local TCP connections.

The optional --auto-iam-authn flag allows automatic authentication to the instance. This works only for the database user associated with the IAM account that is running the Auth Proxy client. For more information, see Authenticate automatically using the Auth Proxy.

The optional --psc flag allows the Auth Proxy to connect to an instance with Private Service Connect enabled. For more information about setting up DNS with Private Service Connect, see Configure a DNS managed zone and a DNS record.

The optional --public-ip flag allows the Auth Proxy to connect to an instance with Public IP enabled using the instance's Public IP address. For more information about Public IP, see Connect using Public IP.

Docker container

Start the Auth Proxy client using the docker run command.

If you are using the credentials provided by your Compute Engine instance, then you can use a command similar to the following:

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

Replace the following:

• PORT: The port to use for local connections to the Auth Proxy client. The default is 5432.

• INSTANCE_URI: The instance connection URI of an AlloyDB instance to connect to, specified using the following format:

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

  You can override the default local listener port that the Auth Proxy client uses for the instance by adding the port query parameter to the URI:

  "projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID?port=PORT"

Always specify 127.0.0.1 prefix in the --publish flag so that the Auth Proxy client is not exposed outside the local host.

The 0.0.0.0 value in the --address flag is required to make the listener accessible from outside of the Docker container.

To provide credentials that you have stored in a local JSON file, include --volume and --credentials-file flags when running the docker run command:

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

Replace PATH_TO_KEY_FILE with the path to the JSON key file of the user-managed service account to use for connection authorization.

Startup Examples

The following examples show various ways to start the Auth Proxy client. They use these example instance connection URIs:

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

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

Basic startup

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

In this example, the Auth Proxy client authorizes the connection by following its normal sequence of authorization steps and then starts listening for local connections to the myprimary instance on 127.0.0.1:5432.

Startup using a user-managed service account

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

In this example, the Auth Proxy client authorizes the connection using the user-managed service account's JSON key stored at myappaccount/key.json and then starts listening for local connections to the myprimary instance on 127.0.0.1:5432.

Startup connecting to multiple instances

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

In this example, the Auth Proxy client authorizes the connection by following its normal sequence of authorization steps and then starts listening for local connections to the myprimary instance on 127.0.0.1:5432 and to the myreadpool instance on 127.0.0.1:5433.

Startup listening on custom ports

Using custom ports for the Auth Proxy client can be useful when you need to reserve port 5432 for other PostgreSQL connections.

./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"

In this example, the Auth Proxy client authorizes the connection by following its normal sequence of authorization steps and then starts listening for local connections to the myprimary instance on 127.0.0.1:5000 and to the myreadpool instance on 127.0.0.1:5001.

Because these custom ports are sequential, the same effect can be achieved using this startup command:

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

Startup listening on a custom IP address

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

In this example, the Auth Proxy client authorizes the connection by following its normal sequence of authorization steps and then starts listening for local connections to the myprimary instance on 0.0.0.0:5432.

Connect an application to a database using the AlloyDB Auth Proxy

The following examples show how you can connect an application to a database using the AlloyDB Auth Proxy.

The psql example provides an example of connecting a command-line tool.

Connecting to an AlloyDB instance using the AlloyDB Auth Proxy is, for several programming languages, identical to connecting to a Cloud SQL for PostgreSQL using the Cloud SQL Auth proxy, so the language examples here are the same as those for Cloud SQL for PostgreSQL.

These examples are based on a default startup of the Auth Proxy client so that it is listening for local TCP connections on 127.0.0.1:5432.

Note: With a new cluster, you can connect as the postgres user, using the password that you specified when creating the cluster.

psql

psql -h 127.0.0.1 -p 5432 -U DB_USER

Replace DB_USER with the database user that you want to connect as—for example, postgres.

This prompts you to enter the password of the DB_USER user.

Python

To see this snippet in the context of a web application, view the README on GitHub.

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

Java

To see this snippet in the context of a web application, view the README on GitHub.

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);
  }
}

Node.js

To see this snippet in the context of a web application, view the README on GitHub.

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);
};

Go

To see this snippet in the context of a web application, view the README on GitHub.

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
}

C#

To see this snippet in the context of a web application, view the README on GitHub.

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;
        }
    }
}

Ruby

To see this snippet in the context of a web application, view the README on GitHub.

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 }%>

PHP

To see this snippet in the context of a web application, view the README on GitHub.

// $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);