Usar o Microsoft Entra ID e as funções nativas do PostgreSQL para autenticação com o Azure Cosmos DB for PostgreSQL
APLICA-SE AO: 
Azure Cosmos DB for PostgreSQL (da plataforma da extensão de dados Citus para PostgreSQL)
Neste artigo, você configurará métodos de autenticação para o Azure Cosmos DB for PostgreSQL. Você gerencia usuários administradores do Microsoft Entra ID e funções nativas do PostgreSQL para autenticação com o Azure Cosmos DB for PostgreSQL. Você também aprenderá a usar um token do Microsoft Entra ID com o Azure Cosmos DB for PostgreSQL.
Um cluster do Azure Cosmos DB for PostgreSQL é criado com uma função interna nativa do PostgreSQL chamada 'citus'. Você pode adicionar mais funções PostgreSQL nativas após a conclusão do provisionamento de cluster.
Você também pode configurar a autenticação do Microsoft Entra ID (anteriormente Azure Active Directory) para o Azure Cosmos DB for PostgreSQL. Você pode habilitar a autenticação do Microsoft Entra ID adicionalmente ou em vez da autenticação nativa do PostgreSQL no seu cluster. Você pode alterar os métodos de autenticação habilitados no cluster a qualquer momento após o provisionamento do cluster. Quando a autenticação do Microsoft Entra ID estiver habilitada, você poderá adicionar vários usuários do Microsoft Entra ID a um cluster do Azure Cosmos DB for PostgreSQL e tornar qualquer um deles administradores. O usuário do Microsoft Entra ID pode ser um usuário ou uma entidade de serviço.
Escolher método de autenticação
Você precisa usar o portal do Azure para configurar métodos de autenticação em um cluster do Azure Cosmos DB for PostgreSQL.
Conclua os itens a seguir no cluster do Azure Cosmos DB for PostgreSQL para habilitar ou desabilitar a autenticação do Microsoft Entra ID e a autenticação nativa do PostgreSQL.
- Na página do cluster, no título Gerenciamento de cluster, escolha Autenticação para abrir as opções de gerenciamento de autenticação.
- Na seção Métodos de autenticação, escolha Somente autenticação do PostgreSQL, Autenticação do Microsoft Entra ID ou Autenticação do PostgreSQL e do Microsoft Entra ID como o método de autenticação com base em seus requisitos.
Após concluir, prossiga com a configuração da autenticação do Microsoft Entra ID ou adição de funções nativas do PostgreSQL na mesma na página da Autenticação.
Configurar a autenticação do Microsoft Entra ID
Pré-requisitos
Os usuários precisam ter permissão para entrar no Azure Cosmos DB for PostgreSQL no locatário do Microsoft Entra ID. Essas etapas devem ser executadas uma vez para o locatário do Microsoft Entra ID que será usado para autenticação nos clusters do Azure Cosmos DB for PostgreSQL.
Importante
As permissões de administrador de locatário do Microsoft Entra ID são necessárias para fazer a alteração. Consulte as diretrizes para solucionar problemas com as permissões.
- Pesquise "Microsoft Entra ID" no portal do Azure.
- Abra o serviço "Microsoft Entra ID".
- Na página de Visão geral do serviço do Microsoft Entra ID na seção Visão geral, pesquise a ID do aplicativo "b4fa09d8-5da5-4352-83d9-05c2a44cf431".
- Escolha o aplicativo empresarial "Autenticação do AAD do Azure Cosmos DB for PostgreSQL" nos resultados da pesquisa.
- No aplicativo empresarial Autenticação do AAD do Azure Cosmos DB for PostgreSQL, clique na página de Propriedades.
- Defina Habilitar para os usuários entrarem? como Sim e salve a alteração.
Observação
Editar as propriedades do aplicativo empresarial, como “Habilitado para os usuários entrarem”, requer permissões concedidas às funções de Administrador Global, Administrador de Aplicativos de Nuvem ou Administrador de Aplicativos. Consulte a lista de funções internas do Microsoft Entra.
Adicionar administradores do Microsoft Entra ID ao cluster do Azure Cosmos DB for PostgreSQL
Para adicionar ou remover as funções do Microsoft Entra ID no cluster, siga essas etapas na página Autenticação:
- Na seção Autenticação do Microsoft Entra ID, selecione Adicionar administradores do Microsoft Entra ID.
- No painel Selecionar administradores do Microsoft Entra ID, selecione um ou mais usuários ou aplicativos empresariais válidos do Microsoft Entra ID no locatário atual do AD para ser um administrador do Microsoft Entra ID no cluster do Azure Cosmos DB for PostgreSQL.
- Para confirmar sua escolha, selecione Sim.
- Na página Autenticação, selecione Salvar na barra de ferramentas para salvar as alterações ou continuar com a adição de funções nativas do PostgreSQL.
Configurar a autenticação nativa do PostgreSQL
Para adicionar ou remover as funções do Postgres no cluster, siga essas etapas na página Autenticação:
- Na seção Autenticação do PostgreSQL, selecione Adicionar função do PostgreSQL.
- Digite o nome e a senha da função. Selecione Salvar.
- Na página Autenticação, selecione Salvar na barra de ferramentas para salvar as alterações ou continuar com a adição de usuários administradores do Microsoft Entra ID.
O usuário nativo do PostgreSQL será criado no nó coordenador do cluster e propagado para todos os nós de trabalho. As funções criadas no portal do Azure têm o atributo LOGIN, o que significa que elas são usuários verdadeiros que podem entrar no banco de dados.
Conectar-se ao Azure Cosmos for PostgreSQL usando a autenticação do Microsoft Entra ID
A integração do Microsoft Entra ID funciona com ferramentas padrão de cliente do PostgreSQL, como psql, que não reconhecem o Microsoft Entra ID e dão suporte somente para especificar o nome de usuário e a senha quando você se conecta ao PostgreSQL. Nesses casos, o token do Microsoft Entra ID é passado como a senha.
Os seguintes clientes foram testados:
- Linha de comando psql: use a variável
PGPASSWORDpara passar o token. - Outros clientes baseados em libpq: exemplos incluem estruturas de aplicativo comuns e ORMs (mapeadores relacionais de objetos).
- pgAdmin: limpe a opção Conectar agora durante a criação do servidor.
Use os procedimentos a seguir para autenticar com o Microsoft Entra ID como um usuário do Azure Cosmos DB for PostgreSQL. Você pode acompanhar as etapas no Azure Cloud Shell, em uma máquina virtual do Azure ou no computador local.
Entrar na assinatura de usuário do Azure
Comece se autenticando no Microsoft Entra ID usando a da CLI do Azure. Essa etapa não é necessária para o Azure Cloud Shell.
az login
O comando abre uma janela do navegador na página de autenticação do Microsoft Entra ID. Ele exige que você forneça o nome de usuário e a senha do Microsoft Entra ID.
O nome da conta de usuário o qual usa para autenticar (por exemplo, user@tenant.onmicrosoft.com) é aquele para o qual o token de acesso será gerado na próxima etapa.
Recuperar o token de acesso do Microsoft Entra ID
Usar a CLI do Azure para adquirir um token de acesso para o usuário autenticado do Microsoft Entra ID para acessar o Azure Cosmos for PostgreSQL. Veja um exemplo:
az account get-access-token --resource https://token.postgres.cosmos.azure.com
Depois que a autenticação for bem-sucedida, o Microsoft Entra ID retornará um token de acesso para a assinatura atual do Azure:
{
"accessToken": "[TOKEN]",
"expiresOn": "[expiration_date_and_time]",
"subscription": "[subscription_id]",
"tenant": "[tenant_id]",
"tokenType": "Bearer"
}
O TOKEN é uma cadeia de caracteres Base64. Ele codifica todas as informações sobre o usuário autenticado e está associado ao serviço do Azure Cosmos DB for PostgreSQL. O token é válido por pelo menos 5 minutos com o máximo de 90 minutos. O expiresOn define o tempo de expiração real do token.
Usar um token como uma senha para entrar no cliente psql
Ao se conectar, é melhor usar o token de acesso como a senha de usuário do PostgreSQL.
Enquanto estiver usando o cliente da linha de comando psql, o token de acesso precisará ser passado pela variável de ambiente PGPASSWORD. O motivo é que o token de acesso excede o comprimento da senha que o psql pode aceitar diretamente.
Este é um exemplo do Windows:
set PGPASSWORD=<TOKEN value from the previous step>
$env:PGPASSWORD='<TOKEN value from the previous step>'
Este é um exemplo do Linux/macOS:
export PGPASSWORD=<TOKEN value from the previous step>
Você também pode combinar as duas etapas anteriores usando a substituição de comando. A recuperação de token pode ser encapsulada em uma variável e passada diretamente como um valor para a variável de ambiente PGPASSWORD:
export PGPASSWORD=$(az account get-access-token --resource-type oss-rdbms --query "[accessToken]" -o tsv)
Observação
Verifique se a variável PGPASSWORD está definida como o token de acesso do Microsoft Entra ID para sua assinatura para autenticação do Microsoft Entra ID. Se você precisar fazer a autenticação de função do Postgres da mesma sessão, poderá definir PGPASSWORD como a senha da função Postgres ou limpar o valor da variável PGPASSWORD para inserir a senha interativamente. A autenticação falharia com o valor errado em PGPASSWORD.
Agora é possível iniciar uma conexão com o Azure Cosmos DB for PostgreSQL usando a conta de usuário do Microsoft Entra ID, para a qual o token de acesso foi gerado. Você faria isto como faria normalmente com a conta de usuário como o usuário e sem o parâmetro 'senha' na linha de comando:
psql "host=mycluster.[uniqueID].postgres.cosmos.azure.com user=user@tenant.onmicrosoft.com dbname=[db_name] sslmode=require"
Usar um token como uma senha para entrar no PgAdmin
Para se conectar usando um token do Microsoft Entra ID com o PgAdmin, siga essas etapas:
- Limpe a opção Conectar agora durante a criação do servidor.
- Insira os detalhes do servidor na guia Conexão e salve-os.
- Verifique se um usuário válido do Microsoft Entra ID está especificado em Nome de usuário.
- No menu objeto PgAdmin, selecione Conectar Servidor.
- Insira a senha do token do Microsoft Entra ID quando for solicitado.
Confira algumas considerações essenciais durante a conexão:
user@tenant.onmicrosoft.comé o nome do usuário do Microsoft Entra ID.- Use o nome do usuário do Azure exatamente como está escrito. Os nomes de usuários e grupos do Microsoft Entra ID diferenciam maiúsculas de minúsculas.
- Se o nome contiver espaços, use uma
\(barra invertida) antes de cada espaço para escapar deles. - A validade do token de acesso é de 5 a 90 minutos. Você deve obter o token de acesso antes de iniciar a entrada no Azure Cosmos for PostgreSQL.
Você já está autenticado no servidor do Azure Cosmos for PostgreSQL através da autenticação do Microsoft Entra ID.
Gerenciar funções nativas do PostgreSQL
Quando a autenticação nativa do PostgreSQL está habilitada no cluster, você pode adicionar e excluir funções do Postgres, além da função interna 'citus'. Você também pode redefinir a senha e modificar privilégios do Postgres para funções nativas.
Como excluir uma função de usuário nativo PostgreSQL ou alterar sua senha
Para atualizar um usuário, visite a página Autenticação do cluster e selecione as reticências … ao lado do usuário. As reticências abrem um menu para excluir o usuário ou redefinir sua senha.
A função citus é privilegiada e não pode ser excluída. No entanto, a função citus seria desabilitada se o método de autenticação "somente autenticação do Microsoft Entra ID" for selecionado no cluster.
Como modificar privilégios para funções de usuário
Novas funções de usuário normalmente são usadas para dar acesso ao banco de dados com privilégios restritos. Para modificar privilégios de usuário, use comandos PostgreSQL padrão, usando uma ferramenta como PgAdmin ou psql. Para saber mais, confira Conectar-se a um cluster.
Por exemplo, para permitir que db_user leia mytable, conceda a permissão:
GRANT SELECT ON mytable TO db_user;
Para conceder as mesmas permissões para a função user@tenant.onmicrosoft.com do Microsoft Entra ID, use o seguinte comando:
GRANT SELECT ON mytable TO "user@tenant.onmicrosoft.com";
O Azure Cosmos DB for PostgreSQL propaga instruções GRANT de tabela única em todo o cluster e as aplica em todos os nós de trabalho. Além de propagar GRANTs que são de todo o sistema (por exemplo, para todas as tabelas de um esquema):
-- applies to the coordinator node and propagates to worker nodes for Postgres role db_user
GRANT SELECT ON ALL TABLES IN SCHEMA public TO db_user;
Ou para a função do Microsoft Entra ID
-- applies to the coordinator node and propagates to worker nodes for Azure AD role user@tenant.onmicrosoft.com
GRANT SELECT ON ALL TABLES IN SCHEMA public TO "user@tenant.onmicrosoft.com";