Conectar usando uma conta do IAM

Nesta página, explicamos o processo de login em uma instância do AlloyDB para PostgreSQL usando uma conta preparada com 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 que você possa 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 OAuth 2.0

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

  1. Se você ainda não fez isso, autentique a CLI gcloud usando o mesmo usuário ou conta de serviço que você quer usar para fazer login na sua instância do AlloyDB.

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

    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 token para uso apenas com a autenticação do AlloyDB seguindo estas etapas alternativas:

    1. Adicione o escopo alloydb.login às credenciais de acesso do ambiente atual usando o gcloud auth application-default login comando, 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 gcloud auth application-default print-access-token comando, definindo o escopo do token apenas para a autenticação do AlloyDB:

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

    O token OAuth 2.0 permite que você ou qualquer pessoa faça solicitações autenticadas para Google Cloud em seu nome. Trate o token com o mesmo nível de segurança de 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 OAuth 2.0 em uma única ação.

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

    • Apresente o token de acesso adquirido 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 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 a ser autenticado 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, kai@altostrat.com.

    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 my-service@my-project.iam.gserviceaccount.com, você usaria o valor my-service@my-project.iam aqui.

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

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

Autenticar automaticamente

Para autenticar automaticamente um usuário do AlloyDB baseado no IAM sem a necessidade de um token OAuth 2.0, você tem duas opções: proxy de autenticação do AlloyDB e conectores de linguagem do AlloyDB.

A conta do IAM que você usa para executar o cliente de proxy ou os conectores de linguagem precisa ser a mesma que você adicionou como usuário do banco de dados. Por exemplo, se você executar sua carga de trabalho usando a conta de usuário do IAM kai@altostrat.com, poderá usar o cliente de proxy ou os conectores de linguagem para autenticar automaticamente o usuário do banco de dados kai@altostrat.com 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 kai@altostrat.com.

Proxy de autenticação

O uso do proxy de autenticação exige a execução do cliente de proxy de autenticação do AlloyDB com a flag --auto-iam-authn ativada.

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

Conectores de linguagem

O uso de conectores de linguagem exige a ativação da autenticação do IAM de maneira programática. Há uma opção correspondente para cada idioma em Configurar os conectores de linguagem do AlloyDB.

Resolver problemas de autenticação do IAM

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

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

    Acessar a Análise de registros

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

  3. Em Gravidade, clique em Alerta.

    Se Alerta 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 da Análise de registros.

  4. Em Resultados da consulta, verifique as entradas de registro de uma das seguintes mensagens:

    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 necessários do IAM ou permissões. A mensagem de erro completa especifica os papéis 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 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 escopo cloud-platform. Pelo menos um desses escopos é obrigatório.

A seguir