About the AlloyDB Auth Proxy

This page provides an overview of the AlloyDB Auth Proxy, a connector that lets you make authorized, encrypted connections to AlloyDB databases.

For a step-by-step guide to using the Auth Proxy, see Connect using the AlloyDB Auth Proxy.

Benefits of using the AlloyDB Auth Proxy

The Auth Proxy provides the following advantages over connecting clients directly to AlloyDB databases:

  • IAM-based connection authorization. The Auth Proxy uses the credentials and permissions of an Identity and Access Management (IAM) principal to authorize connections to AlloyDB instances.

  • Automated IAM authentication. The Auth Proxy can automatically authenticate database users based on the IAM principal running the proxy.

  • Secure, encrypted communication. The Auth Proxy automatically creates, uses, and maintains a mutual TLS (mTLS) 1.3 connection using a 256-bit AES cipher between your client and an AlloyDB instance to verify client and server identities and encrypt data traffic.

For more information about to connecting to AlloyDB instances, see Connection overview.

How the AlloyDB Auth Proxy works

The AlloyDB Auth Proxy works by having a local client running in the local environment. Your application communicates with the AlloyDB Auth Proxy with the standard database protocol used by your database.

The AlloyDB Auth Proxy uses a secure tunnel (mTLS 1.3, 256-bit AES cipher) to communicate with its companion process running on the server. Each connection established through the AlloyDB Auth Proxy creates one connection to the AlloyDB instance.

When an application connects to the AlloyDB Auth Proxy, it checks whether an existing connection between it and the target AlloyDB instance is available. If a connection does not exist, it calls AlloyDB Admin APIs to obtain an ephemeral SSL certificate and uses it to connect to AlloyDB. Ephemeral SSL certificates expire in 24 hours. The AlloyDB Auth Proxy refreshes these certificates before they expire.

The AlloyDB Auth Proxy calls APIs through the domain name alloydb.googleapis.com using HTTPS. As a result, all egress TCP connections on port 443 (HTTPS) from the client machine must be allowed by your firewall.

While the AlloyDB Auth Proxy can listen on any port, it creates outgoing or egress connections to your AlloyDB instance only on port 5433. If your client host has an outbound firewall, it must allow connections to port 5433 on your AlloyDB instance's IP address. The client host must also allow connections to port 443, which is the standard HTTPS port, to all IP addresses.

How the AlloyDB Auth Proxy authenticates and authorizes connections

To authorize a client's connection to an AlloyDB instance, the Auth Proxy client authenticates to Google Cloud using IAM principal credentials on the client, and then validates that the IAM principal has the Cloud AlloyDB Client (roles/alloydb.client) and Service Usage Consumer (roles/serviceusage.serviceUsageConsumer) IAM roles.

By default, the Auth Proxy client uses Application Default Credentials (ADC) to locate client credentials. This provides a unified, standard way for applications to authenticate automatically without editing or hardcoding configuration values.

Standard authentication

For standard development and production setups, you don't need to configure custom credentials or flags. The Auth Proxy client automatically resolves credentials using standard environment paths. Depending on the environment you use to run the Auth Proxy client, it locates credentials from the following sources:

  • Local development. When you develop locally, you can authenticate using your personal or corporate Google user account. The Auth Proxy client automatically detects and uses these credentials. This is the recommended approach for local development, avoiding the need to download service account key files locally.

  • Google-managed environments. When you run your application on a Google Cloud service—such as Compute Engine instances, Google Kubernetes Engine, Cloud Run, Cloud Run functions, or App Engine—credentials from the attached service account are automatically provided by the environment's metadata server. The Auth Proxy client automatically discovers and uses these credentials without extra configuration.

    • If the compute resource is in the same project as the AlloyDB instance, the default service account typically has the necessary permissions to authenticate.
    • If the compute resource and the AlloyDB instance are in different projects, you must add the compute resource's service account to the project containing the AlloyDB instance and grant it the required roles.

Override credentials

In specific scenarios—such as testing, running outside of Google Cloud, or when you want to bypass standard environment credentials—you can override the credentials using one of the following methods:

  • A service account key. Supply the key either through the GOOGLE_APPLICATION_CREDENTIALS environment variable or the --credentials-file flag. Service account keys are a security risk if they aren't managed correctly, so prefer one of the standard sources when you can.

  • An existing OAuth 2.0 access token. Supply the token through the --token flag.

  • gcloud CLI credentials. Supply these credentials through the --gcloud-auth flag. We don't recommend this flag. Run gcloud auth application-default login instead.

For more information about how to configure these credentials on the client, see Connect using the AlloyDB Auth Proxy. For general information about Google Cloud's approach to authentication, see Authentication overview.

What's next