Mantenha tudo organizado com as coleções
Salve e categorize o conteúdo com base nas suas preferências.
Nesta página, você encontra uma visão geral do proxy de autenticação do AlloyDB, um conector que permite fazer conexões criptografadas e autorizadas com bancos de dados do AlloyDB.
Benefícios de usar o proxy de autenticação do AlloyDB
O proxy de autenticação oferece estas vantagens em relação à conexão direta de clientes aos bancos de dados do AlloyDB:
Autorização de conexão com base no IAM (AuthZ): o proxy de autenticação usa as credenciais e permissões de um principal do Identity and Access Management (IAM) para autorizar conexões com instâncias do AlloyDB.
Comunicação criptografada e segura:o proxy de autenticação cria, usa e mantém automaticamente uma conexão TLS 1.3 usando uma criptografia AES de 256 bits entre o cliente e uma instância do AlloyDB para verificar as identidades do cliente e do servidor e criptografar o tráfego de dados.
Para mais informações sobre como se conectar a instâncias do AlloyDB,
consulte Visão geral da conexão.
Como o proxy de autenticação do AlloyDB funciona
O proxy de autenticação do AlloyDB funciona com um cliente local em execução
no ambiente local. O aplicativo se comunica com o proxy de autenticação do AlloyDB
com o protocolo de banco de dados padrão usado por seu banco de dados.
O proxy de autenticação do AlloyDB usa um túnel seguro (TLS 1.3,
criptografia AES de 256 bits) para
se comunicar com o processo complementar
em execução no servidor. Cada conexão estabelecida pelo proxy de autenticação do AlloyDB cria
uma conexão com a instância do AlloyDB.
Quando um aplicativo se conecta ao proxy de autenticação do AlloyDB, ele verifica se uma
conexão entre ele e a instância de destino do AlloyDB está disponível.
Se não houver uma conexão, ela vai chamar as APIs AlloyDB Admin para receber
um certificado SSL temporário e usá-lo para se conectar ao AlloyDB.
Os certificados SSL temporários expiram em 24 horas. O proxy de autenticação do AlloyDB atualiza
esses certificados antes que eles expirem.
O proxy de autenticação do AlloyDB chama APIs pelo nome de domínio alloydb.googleapis.com usando HTTPS. Como resultado, todas as conexões TCP de saída na porta 443 (HTTPS) da máquina cliente precisam ser permitidas pelo firewall.
Embora o proxy de autenticação do AlloyDB possa fazer detecções em qualquer porta, ele cria conexões de entrada ou de saída
com a instância do AlloyDB somente na porta 5433. Se o host do cliente tiver um firewall de saída, ele precisará permitir conexões com a porta 5433 no endereço IP da instância do AlloyDB. O host do cliente também precisa permitir conexões à porta 443, que é a porta HTTPS padrão, para todos os endereços IP.
Como o proxy de autenticação do AlloyDB autoriza principais do IAM
Para autorizar a conexão de um cliente a uma instância do AlloyDB, o cliente do proxy de autenticação faz a autenticação em Google Cloud usando as credenciais do principal do IAM no cliente e valida se o principal do IAM tem os papéis do IAM de cliente do AlloyDB no Cloud (roles/alloydb.client) e consumidor de uso do serviço (roles/serviceusage.serviceUsageConsumer).
Para localizar as credenciais do IAM no cliente, o cliente do proxy de autenticação verifica cada um dos itens a seguir, usando o primeiro que encontra para tentar a autenticação no Google Cloud:
Credenciais fornecidas pela flag --credentials-file
Use uma conta de serviço para
criar e fazer o download do arquivo de chave JSON associado e defina a
flag --credentials-file para o caminho do arquivo ao iniciar
o cliente do proxy de autenticação.
A conta de serviço precisa ter os papéis do IAM Cliente do Cloud AlloyDB (roles/alloydb.client) e Consumidor do Service Usage (roles/serviceusage.serviceUsageConsumer) para a instância do AlloyDB.
Para usar essa opção na linha de comando, invoque o comando alloydb-auth-proxy com a flag --credentials-file definida para o caminho e o nome de um arquivo de credencial JSON. O caminho pode ser absoluto ou relativo ao diretório de trabalho atual.
Credenciais fornecidas pela flag --token
Crie um
token de acesso e invoque o comentário alloydb-auth-proxy com a
flag --token definida como um token de acesso do OAuth 2.0.
Credenciais fornecidas por uma variável de ambiente
Essa opção é semelhante a usar a flag --credentials-file, mas, neste caso você especifica
o arquivo de credencial JSON definido na variável de ambiente
GOOGLE_APPLICATION_CREDENTIALS em vez de usar a flag --credentials-file.
Credenciais de um cliente autenticado da Google Cloud CLI
Se você instalou a gcloud CLI
e autenticou com sua conta pessoal, o cliente do proxy de autenticação
poderá usar as mesmas credenciais de conta se você ativar a
flag --gcloud-auth. Esse método é especialmente útil para
colocar um ambiente de desenvolvimento em funcionamento.
Se nenhuma conta foi selecionada para gcloud auth login, o
cliente do proxy de autenticação verifica se há uma conta selecionada para gcloud
auth application-default login. Esse é o comportamento padrão quando você
não ativa a flag --gcloud-auth.
Credenciais associadas à instância do Compute Engine
Se você estiver usando uma instância do Compute Engine para se conectar ao AlloyDB, o
cliente do proxy de autenticação poderá usar a conta de serviço associada à instância do Compute Engine.
Se a conta de serviço tiver os papéis Identity and Access Management (IAM) Cliente do Cloud AlloyDB (roles/alloydb.client) e Consumidor de uso do serviço (roles/serviceusage.serviceUsageConsumer) para a instância do AlloyDB, o cliente do Auth Proxy será autenticado com êxito.
Se a instância do Compute Engine estiver no mesmo projeto que a instância do AlloyDB, a conta de serviço padrão da primeira terá as permissões necessárias para autenticar o AlloyDB.
Se as duas instâncias estiverem em projetos diferentes, adicione a conta de serviço da instância do Compute Engine ao projeto que contém a instância do AlloyDB.
Conta de serviço padrão do ambiente
Se o cliente do proxy de autenticação não conseguir encontrar credenciais em nenhum dos locais cobertos anteriormente, ele
seguirá a lógica documentada em
Autenticar como uma conta de serviço.
Alguns ambientes (como Compute Engine, App Engine e outros) fornecem uma conta de serviço padrão que o aplicativo pode usar para autenticar por padrão. Se você usar uma conta de serviço padrão, ela precisará ter os papéis do IAM Cliente do AlloyDB no Cloud (roles/alloydb.client) e Consumidor do Service Usage (roles/serviceusage.serviceUsageConsumer).
Para mais informações sobre a abordagem de autenticação do Google Cloud, consulte Visão geral da autenticação.
[[["Fácil de entender","easyToUnderstand","thumb-up"],["Meu problema foi resolvido","solvedMyProblem","thumb-up"],["Outro","otherUp","thumb-up"]],[["Difícil de entender","hardToUnderstand","thumb-down"],["Informações incorretas ou exemplo de código","incorrectInformationOrSampleCode","thumb-down"],["Não contém as informações/amostras de que eu preciso","missingTheInformationSamplesINeed","thumb-down"],["Problema na tradução","translationIssue","thumb-down"],["Outro","otherDown","thumb-down"]],["Última atualização 2025-08-25 UTC."],[[["\u003cp\u003eThe AlloyDB Auth Proxy enables secure, encrypted connections to AlloyDB databases using IAM-based authorization.\u003c/p\u003e\n"],["\u003cp\u003eIt provides advantages over direct connections by using IAM credentials for authorization and establishing TLS 1.3 encrypted connections with a 256-bit AES cipher.\u003c/p\u003e\n"],["\u003cp\u003eThe Auth Proxy runs a local client that communicates with the application using standard database protocols and establishes connections to AlloyDB via secure tunnels.\u003c/p\u003e\n"],["\u003cp\u003eThe Auth Proxy automatically manages and refreshes ephemeral SSL certificates, which expire every 24 hours.\u003c/p\u003e\n"],["\u003cp\u003eThe AlloyDB Auth Proxy supports various methods for locating IAM credentials, including service account JSON key files, OAuth 2.0 access tokens, environment variables, gcloud CLI credentials, and Compute Engine instance credentials.\u003c/p\u003e\n"]]],[],null,["# About the AlloyDB Auth Proxy\n\nThis page provides an overview of the AlloyDB Auth Proxy, a connector that lets you\nmake authorized, encrypted connections to AlloyDB\ndatabases.\n\nFor a step-by-step guide to using the Auth Proxy, see [Connect using the AlloyDB Auth Proxy](/alloydb/docs/auth-proxy/connect).\n\nBenefits of using the AlloyDB Auth Proxy\n----------------------------------------\n\nThe Auth Proxy provides these advantages over connecting clients directly to\nAlloyDB databases:\n\n- **IAM-based connection authorization (AuthZ):** The Auth Proxy uses\n the credentials and permissions of an Identity and Access Management (IAM) principal to authorize connections to\n AlloyDB instances.\n\n- **Secure, encrypted communication:** The Auth Proxy automatically\n creates, uses, and maintains a TLS 1.3 connection\n using a 256-bit AES cipher\n between your client and an AlloyDB instance to verify client\n and server identities and encrypt data traffic.\n\nFor more information about to connecting to AlloyDB instances,\nsee [Connection overview](/alloydb/docs/connection-overview).\n\nHow the AlloyDB Auth Proxy works\n--------------------------------\n\nThe AlloyDB Auth Proxy works by having a local client running\nin the local environment. Your application communicates with the AlloyDB Auth Proxy\nwith the standard database protocol used by your database.\n\nThe AlloyDB Auth Proxy uses a secure tunnel (TLS 1.3,\n256-bit AES cipher) to\ncommunicate with its companion process\nrunning on the server. Each connection established through the AlloyDB Auth Proxy creates\none connection to the AlloyDB instance.\n\nWhen an application connects to the AlloyDB Auth Proxy, it checks whether an existing\nconnection between it and the target AlloyDB instance is available.\nIf a connection does not exist, it calls AlloyDB Admin APIs to obtain\nan ephemeral SSL certificate and uses it to connect to AlloyDB.\nEphemeral SSL certificates expire in 24 hours. The AlloyDB Auth Proxy refreshes\nthese certificates before they expire.\n\nThe AlloyDB Auth Proxy calls APIs through the domain name `alloydb.googleapis.com`\nusing HTTPS. As a result, all egress TCP connections on port 443 (HTTPS) from\nthe client machine must be allowed by your firewall.\n\nWhile the AlloyDB Auth Proxy can listen on any port, it creates outgoing or egress\nconnections to your AlloyDB instance only on port 5433. If your client\nhost has an outbound firewall, it must allow connections to port 5433 on your\nAlloyDB instance's IP address. The client host must also allow\nconnections to port 443, which is the standard HTTPS port, to all IP addresses.\n\nHow the AlloyDB Auth Proxy authorizes IAM principals\n----------------------------------------------------\n\nTo authorize a client's connection to an AlloyDB instance, the\nAuth Proxy client authenticates to Google Cloud using IAM principal\ncredentials on the client, and then validates that the IAM principal has the\nCloud AlloyDB Client (`roles/alloydb.client`) and Service Usage Consumer\n(`roles/serviceusage.serviceUsageConsumer`) IAM roles.\n\nTo locate the IAM credentials on the client, the Auth Proxy client checks\nfor each of the following items, using the first one it\nfinds to attempt authentication to Google Cloud:\n\n1. **Credentials supplied by the --credentials-file flag**\n\n Use a [service account](/alloydb/docs/auth-proxy/best-practices#using-a-service-account) to\n create and download the associated JSON key file, and set the\n `--credentials-file` flag to the path of the file when you start\n the Auth Proxy client.\n The service account must have the Cloud AlloyDB Client\n (`roles/alloydb.client`) and Service Usage Consumer\n (`roles/serviceusage.serviceUsageConsumer`)\n IAM roles for the AlloyDB instance.\n\n To use this option on the command-line, invoke the `alloydb-auth-proxy` command with\n the `--credentials-file` flag set to the path and filename of a JSON credential\n file. The path can be absolute, or relative to the current working directory.\n2. **Credentials supplied by the --token flag**\n\n [Create an\n access token](https://developers.google.com/oauthplayground/) and invoke the `alloydb-auth-proxy` command with the\n `--token` flag set to an OAuth 2.0 access token.\n3. **Credentials supplied by an environment variable**\n\n This option is similar to using the `--credentials-file` flag, except you specify\n the JSON credential file you set in the `GOOGLE_APPLICATION_CREDENTIALS` environment\n variable instead of using the `--credentials-file` flag.\n4. **Credentials from an authenticated Google Cloud CLI client**\n\n If you installed the [gcloud CLI](/sdk/gcloud)\n and have authenticated with your personal account, the Auth Proxy client\n can use the same account credentials if you enable the\n `--gcloud-auth` flag. This method is especially helpful for\n getting a development environment up and running.\n | To enable the Auth Proxy client to use your gcloud CLI credentials, use the `gcloud auth login` command to authenticate the gcloud CLI. To determine your current gcloud CLI credentials, use the `gcloud auth list` command.\n\n If no account was selected for `gcloud auth login`, the\n Auth Proxy client checks for an account that was selected for `gcloud\n auth application-default login`. This is the default behavior when you\n don't enable the `--gcloud-auth` flag.\n5. **Credentials associated with the Compute Engine instance**\n\n If you are connecting to AlloyDB from a Compute Engine instance, the\n Auth Proxy client can use the service account associated with the Compute Engine instance.\n If the service account has the Cloud AlloyDB Client\n (`roles/alloydb.client`) and Service Usage Consumer\n (`roles/serviceusage.serviceUsageConsumer`)\n Identity and Access Management (IAM) roles for the AlloyDB instance, the Auth Proxy client\n authenticates successfully.\n\n If the Compute Engine instance is in the same project as the AlloyDB\n instance, the default service account for the Compute Engine instance has the\n necessary permissions for authenticating the AlloyDB.\n If the two instances are in different projects, you must add the Compute Engine\n instance's service account to the project containing the AlloyDB\n instance.\n6. **Environment's default service account**\n\n If the Auth Proxy client cannot find credentials in any of the places covered earlier, it\n follows the logic documented in\n [Authenticating as a service account](/docs/authentication/production).\n Some environment (such as Compute Engine, App Engine, and others) provide a\n default service account that your application can use to authenticate by default. If\n you use a default service account, it must have the Cloud AlloyDB Client\n (`roles/alloydb.client`) and Service Usage Consumer\n (`roles/serviceusage.serviceUsageConsumer`) IAM roles.\n\n For more information about Google Cloud's approach to authentication, see\n [Authentication overview](/docs/authentication).\n\nWhat's next\n-----------\n\n- [Connect using the AlloyDB Auth Proxy](/alloydb/docs/auth-proxy/connect).\n- [Explore the Google Cloud GitHub repository for the AlloyDB Auth Proxy](https://github.com/GoogleCloudPlatform/alloydb-auth-proxy)."]]
