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:
- Setup steps:
- Download the Auth Proxy client to your client host.
- 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.
- Gather connection URIs for the AlloyDB instances you want to connect to.
- Start the Auth Proxy client on your client host.
- 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 port443
(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)
Download the Auth Proxy client:
wget https://storage.googleapis.com/alloydb-auth-proxy/v1.11.0/alloydb-auth-proxy.linux.amd64 -O alloydb-auth-proxy
Make the Auth Proxy client executable:
chmod +x alloydb-auth-proxy
32-bit (AMD)
Download the Auth Proxy client:
wget https://storage.googleapis.com/alloydb-auth-proxy/v1.11.0/alloydb-auth-proxy.linux.386 -O alloydb-auth-proxy
Make the Auth Proxy client executable:
chmod +x alloydb-auth-proxy
64-bit (ARM)
Download the Auth Proxy client:
wget https://storage.googleapis.com/alloydb-auth-proxy/v1.11.0/alloydb-auth-proxy.linux.arm64 -O alloydb-auth-proxy
Make the Auth Proxy client executable:
chmod +x alloydb-auth-proxy
32-bit (ARM)
Download the Auth Proxy client:
wget https://storage.googleapis.com/alloydb-auth-proxy/v1.11.0/alloydb-auth-proxy.linux.arm -O alloydb-auth-proxy
Make the Auth Proxy client executable:
chmod +x alloydb-auth-proxy
macOS
M1
Download the Auth Proxy client:
curl -o alloydb-auth-proxy https://storage.googleapis.com/alloydb-auth-proxy/v1.11.0/alloydb-auth-proxy.darwin.arm64
Make the Auth Proxy client executable:
chmod +x alloydb-auth-proxy
64-bit
Download the Auth Proxy client:
curl -o alloydb-auth-proxy https://storage.googleapis.com/alloydb-auth-proxy/v1.11.0/alloydb-auth-proxy.darwin.amd64
Make the Auth Proxy client executable:
chmod +x alloydb-auth-proxy
32-bit
Download the Auth Proxy client:
curl -o alloydb-auth-proxy https://storage.googleapis.com/alloydb-auth-proxy/v1.11.0/alloydb-auth-proxy.darwin.386
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.0/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.0/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.
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.
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 port5432
when listening for local TCP connections.Optional:
LOCAL_LISTENER_ADDRESS
: The listener address to use instead of the default127.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 is5432
.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
.
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.
Java
To see this snippet in the context of a web application, view the README on GitHub.
Node.js
To see this snippet in the context of a web application, view the README on GitHub.
Go
To see this snippet in the context of a web application, view the README on GitHub.
C#
To see this snippet in the context of a web application, view the README on GitHub.
Ruby
To see this snippet in the context of a web application, view the README on GitHub.
PHP
To see this snippet in the context of a web application, view the README on GitHub.