Use o ID do Microsoft Entra 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á prestes a ser desativado. Recomendamos vivamente que atualize para a Base de Dados Azure para PostgreSQL – Servidor Flexível. Para obter mais informações sobre a migração para a Base de Dados Azure para PostgreSQL – Servidor Flexível, veja O que está acontecendo com a Base de Dados Azure para PostgreSQL Single Server?.

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

Como configurar o usuário Administrador do Microsoft Entra

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

Para configurar o administrador do Microsoft Entra (pode ser um usuário ou um grupo), siga as etapas a seguir

  1. No portal do Azure, selecione a instância do Banco de Dados do Azure para PostgreSQL que você quer habilitar para o Microsoft Entra ID.
  2. Em Configurações, selecione Administrador do Active 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 servidor do Banco de Dados do Azure para PostgreSQL com permissões de administrador completo. O usuário administrador do Microsoft Entra no Banco de Dados do Azure para PostgreSQL terá a função de azure_ad_admin. Somente um administrador do Microsoft Entra pode ser criado por servidor PostgreSQL, e a seleção de um outro substituirá o administrador do Microsoft Entra existente configurado para o servidor. Você pode especificar um grupo do Microsoft Entra em vez de um usuário individual para ter vários administradores.

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

Como se conectar ao Banco de Dados do Azure para PostgreSQL usando o Microsoft Entra ID

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 funcionar com ferramentas comuns do PostgreSQL, como a psql, que não estão cientes do Microsoft Entra e só dão suporte à especificação de nome de usuário e senha quando se conectam ao PostgreSQL. Transmitimos o token do Microsoft Entra como uma senha, conforme mostrado na imagem acima.

No momento, testamos os clientes a seguir:

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

Essas são as etapas que um usuário/aplicativo precisará executar para se autenticar no Microsoft Entra, descritas abaixo:

Pré-requisitos

Você pode acompanhar as etapas no Azure Cloud Shell, em uma VM do Azure ou no computador local. Garanta que você tem o CLI do Azure instalado.

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

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

Comece se autenticando com o Microsoft Entra ID usando a ferramenta de CLI do Azure. Essa etapa não é necessária para o Azure Cloud Shell.

az login

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

Etapa 2: Recuperar o token de acesso do Microsoft Entra

Invoque a ferramenta de 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 o mostrado. Para outras nuvens, é possível pesquisar o valor do recurso usando:

az cloud show

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

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

Após a autenticação ter sido 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 é direcionado para o serviço do Banco de Dados do Azure para PostgreSQL.

Etapa 3: Usar o token como senha para fazer logon 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 comando psql, o token de acesso precisa ser passado pela variável de ambiente PGPASSWORD, já 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 do 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"

Etapa 4: Usar o token como senha para fazer logon com o PgAdmin

Para se conectar usando o token do Microsoft Entra com o pgAdmin, siga as próximas etapas:

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

Considerações importantes durante a conexão:

  • user@tenant.onmicrosoft.com é o nome do usuário do Microsoft Entra
  • Certifique-se de usar o nome do usuário do Azure exatamente como está escrito — porque os nomes de usuários e grupos do Azure AD diferenciam maiúsculas de minúsculas.
  • Se o nome contiver espaços, use \ antes de cada espaço para fazer o escape dele.
  • A validade do token de acesso está entre 5 e 60 minutos. Recomendamos que você obtenha o token de acesso logo antes de iniciar o logon no Banco de Dados do Azure para PostgreSQL.

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

Autenticar-se com o Microsoft Entra ID como um membro de grupo

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

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

Exemplo:

CREATE USER <new_user> IN ROLE azure_ad_user;

Ao fazer logon, os membros do grupo usarão os tokens de acesso pessoal deles, mas assinarão com o nome do grupo especificado como o 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 de CLI do Azure. Essa etapa não é necessária para o Azure Cloud Shell. O usuário precisa ser membro do grupo do Microsoft Entra.

az login

Etapa 3: Recuperar o token de acesso do Microsoft Entra

Invoque a ferramenta de 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 o mostrado. Para outras nuvens, é possível pesquisar o valor do recurso usando:

az cloud show

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

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

Após a autenticação ter sido bem-sucedida, o Microsoft Entra ID retornará um token de acesso:

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

Etapa 4: Usar o token como senha para fazer logon com o psql ou o PgAdmin (confira as etapas acima para a conexão do usuário)

Considerações importantes durante a conexão como um membro do grupo:

  • groupname@mydb é o nome do grupo do Microsoft Entra com o qual você está tentando se conectar
  • Sempre acrescente o nome do servidor após o nome de usuário/grupo do Microsoft Entra (por exemplo, @mydb)
  • Certifique-se de usar o nome do grupo do Microsoft Entra exatamente como está escrito.
  • Os nomes de usuários e grupos do Microsoft Entra diferenciam maiúsculas de minúsculas
  • Ao se conectar como 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, use \ antes de cada espaço para fazer o escape dele.
  • A validade do token de acesso está entre 5 e 60 minutos. Recomendamos que você obtenha o token de acesso logo antes de iniciar o logon no Banco de Dados do Azure para PostgreSQL.

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

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

Para adicionar um usuário do Microsoft Entra ao banco de dados do seu Banco de Dados do Azure para PostgreSQL, execute as etapas a seguir após ter se conectado (confira a seção mais adiante sobre como se conectar):

  1. Primeiro, certifique-se de que o usuário <user>@yourtenant.onmicrosoft.com do Microsoft Entra é um usuário válido no locatário do Microsoft Entra.
  2. Entre na sua instância do Banco de Dados do Azure para PostgreSQL como o usuário Administrador do Microsoft Entra.
  3. Criar a 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 deve ser dado somente aos usuários do Microsoft Entra.

Exemplo:

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

Observação

A autenticação de um usuário por meio do Microsoft Entra não concede ao usuário nenhuma permissão para acessar objetos dentro do banco de dados do Banco de Dados do Azure para PostgreSQL. Você precisa 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 por meio da validação do conteúdo do token. As seguintes etapas de validação de token são executadas:

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

Como migrar usuários existentes do PostgreSQL para a autenticação baseada no Microsoft Entra ID

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

Caso 1: o nome de usuário do PostgreSQL corresponde ao nome UPN do Microsoft Entra

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

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

Agora eles poderão entrar com as credenciais do Microsoft Entra em vez de usar a senha de usuário do PostgreSQL configurada anteriormente.

Caso 2: o nome de usuário do PostgreSQL é diferente do nome UPN do Microsoft Entra

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

GRANT azure_ad_user TO <new_user>;

Isso pressupõe que você criou um grupo "DBReadUser" no seu Microsoft Entra ID. Os usuários que pertencerem a esse grupo agora poderão entrar no banco de dados como esse usuário.

Próximas etapas