Conectar usando uma conta do IAM

Esta página explica o processo de login em uma instância do AlloyDB para PostgreSQL usando uma conta preparada com o Identity and Access Management (IAM). Ele ilustra o processo mostrando como realizar um login baseado no IAM usando o cliente de linha de comando psql.

Para uma visão geral da conexão com instâncias do AlloyDB, consulte Visão geral da conexão.

Antes de começar

Seu projeto, cluster, instâncias e contas de usuário do IAM precisam de preparação antes de você fazer login em uma instância do AlloyDB usando credenciais do IAM.

Para mais informações, consulte Gerenciar a autenticação do IAM.

Autenticar com um token do OAuth 2.0

Um usuário ou aplicativo pode se autenticar com um banco de dados do AlloyDB seguindo estas etapas:

1. Se ainda não fez isso, autorize a Google Cloud CLI usando a mesma conta de usuário ou de serviço com que você quer fazer login na instância do AlloyDB.

2. Solicite um token OAuth 2.0 do Google Cloud usando o comando gcloud auth print-access-token:

   gcloud auth print-access-token

   O Google Cloud imprime um token OAuth 2.0 como a saída desse comando.

   Para mais segurança, você pode restringir o uso do token apenas à autenticação do AlloyDB seguindo estas etapas alternativas:

   1. Adicione o escopo alloydb.login às credenciais de acesso do seu ambiente atual usando o comando gcloud auth application-default login, se ainda não tiver feito isso:

      gcloud auth application-default login --scopes=https://www.googleapis.com/auth/alloydb.login,https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/userinfo.email,openid

   2. Imprima um token OAuth 2.0 restrito usando o comando gcloud auth application-default print-access-token, limitando o token apenas à autenticação do AlloyDB:

      gcloud auth application-default print-access-token –-scopes=https://www.googleapis.com/auth/alloydb.login
      

   Atenção: trate seu token OAuth 2.0 como informações sensíveis. Armazene de forma segura ou não armazene após o uso.

   O token OAuth 2.0 permite que você ou qualquer pessoa faça solicitações autenticadas para o Google Cloud em seu nome. Trate o token com o mesmo nível de segurança que uma senha. Armazene o token com segurança ou evite armazená-lo. O exemplo de uso de psql mais adiante nesta página demonstra uma maneira de solicitar, usar e descartar um token do OAuth 2.0 em uma única ação.

3. Faça login em uma instância do AlloyDB com técnicas PostgreSQL padrão usando estas credenciais:

   • Apresente o token de acesso que você adquiriu na etapa anterior como sua senha.

   • Para uma conta de usuário do IAM, o nome de usuário do banco de dados é o endereço de e-mail completo da conta.

   • Para uma conta de serviço do IAM, o nome de usuário do banco de dados é o endereço de e-mail da conta sem o sufixo .gserviceaccount.com.

O comando psql a seguir demonstra uma maneira de fazer login em um usuário do IAM na linha de comando. Ele atribui a saída de gcloud auth print-access-token à variável de ambiente PGPASSWORD, que psql subsequentemente usa como uma senha de login do banco de dados.

PGPASSWORD=$(gcloud auth print-access-token) psql \
  -h INSTANCE_ADDRESS \
  -U USERNAME \
  -d DATABASE

Substitua:

• INSTANCE_ADDRESS: o endereço IP da instância do AlloyDB a que você quer se conectar.

• USERNAME: um identificador para o usuário do IAM autenticação com a instância.

  Para uma conta de usuário do IAM, forneça o endereço de e-mail completo da conta de usuário. Por exemplo, [e-mail]

  Para uma conta de serviço do IAM, forneça o endereço da conta de serviço sem o sufixo .gserviceaccount.com. Por exemplo, para especificar a conta de serviço [e-mail], use o valor [e-mail] aqui.

• DATABASE: o nome do banco de dados a ser conectado.

O psql trunca senhas inseridas na linha de comando com mais de 100 caracteres. Para usar psql com um token OAuth 2.0 como uma senha de login, configure a variável de ambiente PGPASSWORD, conforme demonstrado neste exemplo, em vez de colá-la manualmente quando solicitado.

Autentique automaticamente usando o proxy de autenticação do AlloyDB ou os conectores de idioma do AlloyDB

É possível usar o proxy de autenticação do AlloyDB ou os conectores de linguagem do AlloyDB para autenticar automaticamente um usuário do AlloyDB baseado no IAM e se conectar a uma instância sem precisar fornecer um token OAuth 2.0.

O uso do proxy de autenticação do AlloyDB exige a execução do cliente do proxy de autenticação do AlloyDB com a flag --auto-iam-authn ativada, enquanto os conectores de idioma do AlloyDB exigem a ativação da autenticação do IAM de forma programática.

Ao usar os conectores de idioma, há uma opção correspondente para cada idioma. Consulte Configurar os conectores de linguagem do AlloyDB para mais detalhes.

A conta do IAM usada para executar o cliente de proxy ou os conectores de linguagem precisa ser a mesma conta adicionada como usuário do banco de dados. Por exemplo, se você executar sua carga de trabalho usando a conta de usuário [e-mail] do IAM, poderá usar o cliente de proxy ou os conectores de linguagem para autenticar automaticamente o usuário do banco de dados [e-mail] sem especificar um token OAuth 2.0. Neste exemplo, a autenticação automática não funciona com nenhum outro usuário do banco de dados, exceto [e-mail].

Para mais informações sobre como executar o proxy de autenticação, consulte Conectar-se usando o proxy de autenticação do AlloyDB.

Para mais informações sobre como executar os conectores de idioma, consulte Conectar usando os conectores de idioma do AlloyDB.

Resolver problemas de autenticação do IAM

Para determinar a causa de uma falha na tentativa de autenticação baseada no IAM, siga estas etapas:

1. No console do Google Cloud, acesse a página do Explorador de registros:

   Acessar o Explorador de registros

2. Em Tipo de recurso, clique em Instância do AlloyDB.

3. Em Gravidade, clique em Alerta.

   Se Alert não for uma opção, não haverá falhas de autenticação registradas na janela de tempo selecionada. Talvez seja necessário ajustar a janela usando os controles do Logs Explorer.

4. Em Resultados da consulta, verifique se há uma das seguintes mensagens nas entradas de registro:

   Request had invalid authentication credentials.

   O token de acesso é inválido.

   Caller does not have required permission to use project.

   O principal do IAM não tem os papéis do IAM necessários ou as permissões. A mensagem de erro completa especifica as funções ou permissões ausentes.

   IAM principal does not match database user.

   O principal do IAM autenticado especificado pelo token de acesso não corresponde ao usuário do banco de dados com que você quer se conectar.

   Para conferir o principal especificado pelo token, execute o seguinte comando:

   curl -H "Content-Type: application/x-www-form-urlencoded" -d "access_token=ACCESS_TOKEN" https://www.googleapis.com/oauth2/v1/tokeninfo
   

   Substitua ACCESS_TOKEN pelo token de acesso do OAuth 2.0.

   Request had insufficient scopes.

   O token de acesso não contém o escopo alloydb.login nem o cloud-platform. Pelo menos um desses escopos é obrigatório.