Share via

Usar o Microsoft Entra ID para autenticação com PostgreSQL

  • Artigo

APLICA-SE A: Banco de Dados do Azure para PostgreSQL - Servidor Único

Importante

O Banco de Dados do Azure para PostgreSQL - Servidor Único está no caminho da desativação. É altamente recomendável que você atualize para o Banco de Dados do Azure para PostgreSQL - Servidor Flexível. Para obter mais informações sobre como migrar para o Banco de Dados do Azure para PostgreSQL - Servidor Flexível, consulte O que está acontecendo com o Banco de Dados do Azure para Servidor Único PostgreSQL?.

Este artigo orientará você pelas etapas de como configurar o acesso ao Microsoft Entra ID com o Banco de Dados do Azure para PostgreSQL e como se conectar usando um token do Microsoft Entra.

Definindo o usuário administrador do Microsoft Entra

Somente usuários administradores do Microsoft Entra podem criar/habilitar usuários para autenticação baseada em ID do Microsoft Entra. Recomendamos não usar o administrador do Microsoft Entra para operações regulares de banco de dados, pois ele tem permissões de usuário elevadas (por exemplo, CREATEDB).

Para definir o administrador do Microsoft Entra (você pode usar um usuário ou um grupo), siga as seguintes etapas

  1. No portal do Azure, selecione a instância do Banco de Dados do Azure para PostgreSQL que você deseja habilitar para o Microsoft Entra ID.
  2. Em Configurações, selecione Administrador do Ative Directory:

definir administrador do Microsoft Entra

  1. Selecione um usuário válido do Microsoft Entra no locatário do cliente para ser administrador do Microsoft Entra.

Importante

Ao definir o administrador, um novo usuário é adicionado ao Banco de Dados do Azure para servidor PostgreSQL com permissões de administrador completas. O usuário Microsoft Entra Admin no Banco de Dados do Azure para PostgreSQL terá a função azure_ad_admin. Apenas um administrador do Microsoft Entra pode ser criado por servidor PostgreSQL e a seleção de outro substituirá o administrador existente do Microsoft Entra configurado para o servidor. Você pode especificar um grupo do Microsoft Entra em vez de um usuário individual para ter vários administradores.

Apenas um administrador do Microsoft Entra pode ser criado por servidor PostgreSQL e a seleção de outro substituirá o administrador existente do Microsoft Entra configurado para o servidor. Você pode especificar um grupo do Microsoft Entra em vez de um usuário individual para ter vários administradores. Observe que você entrará com o nome do grupo para fins de administração.

Conectando-se ao Banco de Dados do Azure para PostgreSQL usando a ID do Microsoft Entra

O diagrama de alto nível a seguir resume o fluxo de trabalho do uso da autenticação do Microsoft Entra com o Banco de Dados do Azure para PostgreSQL:

Fluxo de autenticação

Projetamos a integração do Microsoft Entra para trabalhar com ferramentas comuns do PostgreSQL, como o psql, que não são compatíveis com o Microsoft Entra e só suportam a especificação de nome de usuário e senha ao se conectar ao PostgreSQL. Nós passamos o token Microsoft Entra como a senha como mostrado na imagem acima.

Atualmente, testamos os seguintes clientes:

  • linha de comando psql (utilize a variável PGPASSWORD para passar o token, consulte a etapa 3 para obter mais informações)
  • Azure Data Studio (usando a extensão PostgreSQL)
  • Outros clientes baseados em libpq (por exemplo, estruturas de aplicação comuns e ORMs)
  • PgAdmin (desmarque conectar agora na criação do servidor. Consulte o passo 4 para obter mais informações)

Estas são as etapas que um usuário/aplicativo precisará fazer para autenticar com o Microsoft Entra ID descritas abaixo:

Pré-requisitos

Você pode acompanhar no Azure Cloud Shell, em uma VM do Azure ou em sua máquina local. Verifique se você tem a CLI do Azure instalada.

Autenticar com o Microsoft Entra ID como um único usuário

Etapa 1: Fazer logon na assinatura do Azure do usuário

Comece autenticando com a ID do Microsoft Entra usando a ferramenta CLI do Azure. Esta etapa não é necessária no Azure Cloud Shell.

az login

O comando iniciará uma janela do navegador para a página de autenticação do Microsoft Entra. Ele requer que você forneça seu ID de usuário do Microsoft Entra e a senha.

Etapa 2: Recuperar o token de acesso do Microsoft Entra

Invoque a ferramenta CLI do Azure para adquirir um token de acesso para o usuário autenticado do Microsoft Entra da etapa 1 para acessar o Banco de Dados do Azure para PostgreSQL.

Exemplo (para nuvem pública):

az account get-access-token --resource https://ossrdbms-aad.database.windows.net

O valor do recurso acima deve ser especificado exatamente como mostrado. Para outras nuvens, o valor do recurso pode ser pesquisado usando:

az cloud show

Para a CLI do Azure versão 2.0.71 e posterior, o comando pode ser especificado na seguinte versão mais conveniente para todas as nuvens:

az account get-access-token --resource-type oss-rdbms

Depois que a autenticação for bem-sucedida, o Microsoft Entra ID retornará um token de acesso:

{
  "accessToken": "TOKEN",
  "expiresOn": "...",
  "subscription": "...",
  "tenant": "...",
  "tokenType": "Bearer"
}

O token é uma cadeia de caracteres Base 64 que codifica todas as informações sobre o usuário autenticado e que é direcionada para o serviço Banco de Dados do Azure para PostgreSQL.

Etapa 3: Usar token como senha para fazer login com o cliente psql

Ao se conectar, você precisa usar o token de acesso como a senha de usuário do PostgreSQL.

Ao usar o cliente de linha de psql comando, o token de acesso precisa ser passado pela PGPASSWORD variável de ambiente, uma vez que o token de acesso excede o comprimento da senha que psql pode aceitar diretamente:

Exemplo do Windows:

set PGPASSWORD=<copy/pasted TOKEN value from step 2>

$env:PGPASSWORD='<copy/pasted TOKEN value from step 2>'

Exemplo de Linux/macOS:

export PGPASSWORD=<copy/pasted TOKEN value from step 2>

Agora você pode iniciar uma conexão com o Banco de Dados do Azure para PostgreSQL como faria normalmente:

psql "host=mydb.postgres... user=user@tenant.onmicrosoft.com@mydb dbname=postgres sslmode=require"

Passo 4: Utilizar o token como palavra-passe para iniciar sessão com o PgAdmin

Para se conectar usando o token Microsoft Entra com o pgAdmin, você precisa seguir as próximas etapas:

  1. Desmarque a opção conectar agora na criação do servidor.
  2. Insira os detalhes do servidor na guia conexão e salve.
  3. No menu do navegador, selecione conectar ao Banco de Dados do Azure para o servidor PostgreSQL
  4. Digite a senha do token do AD quando solicitado.

Considerações importantes ao conectar:

  • user@tenant.onmicrosoft.com é o nome do usuário do Microsoft Entra
  • Certifique-se de usar a maneira exata como o usuário do Azure é escrito - pois os nomes de usuário e grupo do Microsoft Entra diferenciam maiúsculas de minúsculas.
  • Se o nome contiver espaços, use \ antes de cada espaço para escapar dele.
  • A validade do token de acesso varia entre 5 minutos e 60 minutos. Recomendamos que você obtenha o token de acesso antes de iniciar o logon no Banco de Dados do Azure para PostgreSQL.

Agora você está autenticado no seu Banco de Dados do Azure para servidor PostgreSQL usando a autenticação do Microsoft Entra.

Autenticar com o Microsoft Entra ID como membro do grupo

Etapa 1: Criar grupos do Microsoft Entra no Banco de Dados do Azure para PostgreSQL

Para habilitar um grupo do Microsoft Entra para acessar seu banco de dados, use o mesmo mecanismo que para usuários, mas especifique o nome do grupo:

Exemplo:

CREATE USER <new_user> IN ROLE azure_ad_user;

Ao fazer login, os membros do grupo usarão seus tokens de acesso pessoais, mas assinarão com o nome do grupo especificado como nome de usuário.

Etapa 2: Fazer logon na Assinatura do Azure do usuário

Autentique-se com o Microsoft Entra ID usando a ferramenta CLI do Azure. Esta etapa não é necessária no Azure Cloud Shell. O usuário precisa ser membro do grupo Microsoft Entra.

az login

Etapa 3: Recuperar o token de acesso do Microsoft Entra

Invoque a ferramenta CLI do Azure para adquirir um token de acesso para o usuário autenticado do Microsoft Entra da etapa 2 para acessar o Banco de Dados do Azure para PostgreSQL.

Exemplo (para nuvem pública):

az account get-access-token --resource https://ossrdbms-aad.database.windows.net

O valor do recurso acima deve ser especificado exatamente como mostrado. Para outras nuvens, o valor do recurso pode ser pesquisado usando:

az cloud show

Para a CLI do Azure versão 2.0.71 e posterior, o comando pode ser especificado na seguinte versão mais conveniente para todas as nuvens:

az account get-access-token --resource-type oss-rdbms

Depois que a autenticação for bem-sucedida, o Microsoft Entra ID retornará um token de acesso:

{
  "accessToken": "TOKEN",
  "expiresOn": "...",
  "subscription": "...",
  "tenant": "...",
  "tokenType": "Bearer"
}

Etapa 4: Use o token como senha para fazer login com psql ou PgAdmin (veja as etapas acima para conexão do usuário)

Considerações importantes ao se conectar como membro do grupo:

  • groupname@mydb é o nome do grupo Microsoft Entra que você está tentando conectar como
  • Sempre acrescente o nome do servidor após o nome de usuário/grupo do Microsoft Entra (por exemplo, @mydb)
  • Certifique-se de usar a maneira exata como o nome do grupo Microsoft Entra está escrito.
  • Os nomes de usuário e grupo do Microsoft Entra diferenciam maiúsculas de minúsculas
  • Ao conectar-se como um grupo, use apenas o nome do grupo (por exemplo, GroupName@mydb) e não o alias de um membro do grupo.
  • Se o nome contiver espaços, utilize \ antes de cada espaço para escapar deste.
  • A validade do token de acesso varia entre 5 minutos e 60 minutos. Recomendamos que você obtenha o token de acesso antes de iniciar o logon no Banco de Dados do Azure para PostgreSQL.

Agora você está autenticado em seu servidor PostgreSQL usando a autenticação Microsoft Entra.

Criando usuários do Microsoft Entra no Banco de Dados do Azure para PostgreSQL

Para adicionar um usuário do Microsoft Entra ao seu banco de dados do Azure para PostgreSQL, execute as seguintes etapas após a conexão (consulte a seção posterior sobre como se conectar):

  1. Primeiro, verifique se o usuário <user>@yourtenant.onmicrosoft.com do Microsoft Entra é um usuário válido no locatário do Microsoft Entra.
  2. Entre em sua instância do Banco de Dados do Azure para PostgreSQL como o usuário Microsoft Entra Admin.
  3. Crie uma função <user>@yourtenant.onmicrosoft.com no Banco de Dados do Azure para PostgreSQL.
  4. Torne <user>@yourtenant.onmicrosoft.com um membro da função azure_ad_user. Isso só deve ser dado aos usuários do Microsoft Entra.

Exemplo:

CREATE USER "user1@yourtenant.onmicrosoft.com" IN ROLE azure_ad_user;

Nota

A autenticação de um usuário por meio da ID do Microsoft Entra não dá ao usuário nenhuma permissão para acessar objetos no Banco de Dados do Azure para banco de dados PostgreSQL. Você deve conceder ao usuário as permissões necessárias manualmente.

Validação de Token

A autenticação do Microsoft Entra no Banco de Dados do Azure para PostgreSQL garante que o usuário exista no servidor PostgreSQL e verifica a validade do token validando o conteúdo do token. As seguintes etapas de validação de token são executadas:

  • O token é assinado pelo ID do Microsoft Entra e não foi adulterado
  • O token foi emitido pelo ID do Microsoft Entra para o locatário associado ao servidor
  • O token não expirou
  • O token é para o recurso Banco de Dados do Azure para PostgreSQL (e não para outro recurso do Azure)

Migrando usuários existentes do PostgreSQL para a autenticação baseada em ID do Microsoft Entra

Você pode habilitar a autenticação do Microsoft Entra para usuários existentes. Há dois casos a considerar:

Caso 1: O nome de usuário do PostgreSQL corresponde ao Nome Principal do usuário do Microsoft Entra

No caso improvável de que seus usuários existentes já correspondam aos nomes de usuário do Microsoft Entra, você pode conceder a azure_ad_user função a eles para habilitá-los para autenticação do Microsoft Entra:

GRANT azure_ad_user TO "existinguser@yourtenant.onmicrosoft.com";

Eles agora poderão entrar com credenciais do Microsoft Entra em vez de usar sua senha de usuário PostgreSQL configurada anteriormente.

Caso 2: O nome de usuário do PostgreSQL é diferente do nome principal do usuário do Microsoft Entra

Se um usuário do PostgreSQL não existir no ID do Microsoft Entra ou tiver um nome de usuário diferente, você poderá usar grupos do Microsoft Entra para autenticar como esse usuário do PostgreSQL. Você pode migrar usuários existentes do Banco de Dados do Azure para PostgreSQL para a ID do Microsoft Entra criando um grupo do Microsoft Entra com um nome que corresponda ao usuário do PostgreSQL e, em seguida, concedendo azure_ad_user de função ao usuário existente do PostgreSQL:

GRANT azure_ad_user TO <new_user>;

Isso pressupõe que você tenha criado um grupo "DBReadUser" em sua ID do Microsoft Entra. Os usuários pertencentes a esse grupo agora poderão entrar no banco de dados como esse usuário.

Próximos passos