Conectar usando uma conta do IAM

Nesta página, explicamos o processo de fazer 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 fazer login com base 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 do OAuth 2.0

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

  1. Se ainda não tiver feito isso, autorize a Google Cloud CLI 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 do OAuth 2.0 de 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 deste comando.

    Para mais segurança, é possível restringir o uso do token apenas com a 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 restrito do OAuth 2.0 usando o comando gcloud auth application-default print-access-token, restringindo o token apenas à 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 do 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 como 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 posteriormente 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 autenticar com a instância.

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

    Para uma conta de serviço do IAM, forneça o endereço da conta sem o sufixo .gserviceaccount.com. Por exemplo, para especificar a conta de serviço [email protected], use o valor [email protected] 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 colar manualmente quando solicitado.

Autenticar automaticamente

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

A conta do IAM usada para executar o cliente proxy ou os Language Connectors 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 do IAM [email protected], poderá usar o cliente proxy ou os conectores de linguagem para autenticar automaticamente o usuário do banco de dados [email protected] 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 [email protected].

Proxy de autenticação

Para usar o proxy de autenticação, é necessário executar o cliente do 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

Para usar os conectores de linguagem, é necessário ativar a autenticação do IAM de forma 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 baseada no IAM com falha, siga estas etapas:

  1. No console Google Cloud , acesse a página "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 Alerta não for uma opção, não haverá falhas de autenticação registradas no período selecionado. Talvez seja necessário ajustar a janela usando os controles do Explorador 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 ou permissões necessários do IAM. A mensagem de erro completa especifica as funções ou permissões ausentes.
    IAM principal does not match database user.

    O principal autenticado do IAM especificado pelo token de acesso não corresponde ao usuário do banco de dados a 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. É necessário ter pelo menos um desses escopos.

A seguir