Usar a ID do Microsoft Entra e funções nativas do PostgreSQL para autenticação com o Azure Cosmos DB para PostgreSQL

  • Artigo

APLICA-SE A: Azure Cosmos DB para PostgreSQL (alimentado pela extensão de banco de dados Citus para PostgreSQL)

Neste artigo, você configura métodos de autenticação para o Azure Cosmos DB para PostgreSQL. Você gerencia usuários administradores do Microsoft Entra ID e funções nativas do PostgreSQL para autenticação com o Azure Cosmos DB para PostgreSQL. Você também aprenderá a usar um token de ID do Microsoft Entra com o Azure Cosmos DB para PostgreSQL.

Um cluster do Azure Cosmos DB para PostgreSQL é criado com uma função PostgreSQL nativa interna 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 Ative Directory) para o Azure Cosmos DB para PostgreSQL. Você pode habilitar a autenticação de ID do Microsoft Entra além ou em vez da autenticação PostgreSQL nativa em 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 está habilitada, você pode adicionar vários usuários do Microsoft Entra ID a um cluster do Azure Cosmos DB para PostgreSQL e tornar qualquer um deles administrador. 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 para PostgreSQL.

Conclua os seguintes itens em seu cluster do Azure Cosmos DB para PostgreSQL para habilitar ou desabilitar a autenticação de ID do Microsoft Entra e a autenticação PostgreSQL nativa.

  1. Na página do cluster, sob o título Gerenciamento de cluster, escolha Autenticação para abrir as opções de gerenciamento de autenticação.
  2. Na seção Métodos de autenticação, escolha Somente autenticação PostgreSQL, Autenticação Microsoft Entra ID ou Autenticação PostgreSQL e Microsoft Entra ID como o método de autenticação baseado em seus requisitos.

Uma vez feito, prossiga com a configuração da autenticação do Microsoft Entra ID ou adicionando funções nativas do PostgreSQL na mesma página de 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 para 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 no Azure Cosmos DB para clusters 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 de permissões.

  1. Procure por 'Microsoft Entra ID' no portal do Azure.
  2. Abra o serviço 'Microsoft Entra ID'.
  3. Na página Visão geral do serviço Microsoft Entra ID na seção Visão geral, procure por ID do aplicativo 'b4fa09d8-5da5-4352-83d9-05c2a44cf431'.
  4. Escolha o aplicativo empresarial 'Azure Cosmos DB for PostgreSQL AAD Authentication' nos resultados da pesquisa.
  5. No aplicativo empresarial Azure Cosmos DB for PostgreSQL AAD Authentication, escolha a página Propriedades.
  6. Defina Habilitado para os usuários entrarem? como Sim e salve a alteração.

Nota

A edição das propriedades do aplicativo corporativo, como "Habilitado para os usuários entrarem", requer permissões concedidas às funções de Administrador Global, Administrador de Aplicativo na Nuvem ou Administrador de Aplicativo. Consulte a lista de funções internas do Microsoft Entra.

Adicionar administradores de ID do Microsoft Entra ao cluster do Azure Cosmos DB para PostgreSQL

Para adicionar ou remover funções de ID do Microsoft Entra no cluster, siga estas etapas na página Autenticação :

  1. Na seção Autenticação do Microsoft Entra ID, selecione Adicionar administradores do Microsoft Entra ID.
  2. No painel Selecionar Administradores de ID do Microsoft Entra, 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 em seu cluster do Azure Cosmos DB para PostgreSQL.
  3. Use Selecionar para confirmar sua escolha.
  4. 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 autenticação PostgreSQL nativa

Para adicionar funções do Postgres no cluster, siga estas etapas na página Autenticação :

  1. Na seção de autenticação do PostgreSQL, selecione Adicionar função do PostgreSQL.
  2. Introduza o nome da função e a palavra-passe. Selecione Guardar.
  3. 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 é criado no nó coordenador do cluster e propagado para todos os nós de trabalho. As funções criadas através do portal do Azure têm o atributo LOGIN, o que significa que são verdadeiros utilizadores que podem iniciar sessão na base de dados.

Conectar-se ao Azure Cosmos para PostgreSQL usando a autenticação de ID do Microsoft Entra

A integração do Microsoft Entra ID funciona com ferramentas de cliente PostgreSQL padrão, como psql, que não reconhecem o ID do Microsoft Entra e suportam apenas a especificação do nome de usuário e senha quando você está se conectando ao PostgreSQL. Nesses casos, o token Microsoft Entra ID é passado como a senha.

Testamos os seguintes clientes:

  • Linha de comando psql: use a PGPASSWORD variável para passar o token.
  • Outros clientes baseados em libpq: Os exemplos incluem estruturas de aplicativos comuns e mapeadores objeto-relacionais (ORMs).
  • pgAdmin: Limpe Conectar agora na criação do servidor.

Use os procedimentos a seguir para autenticar com o Microsoft Entra ID como um usuário do Azure Cosmos DB para PostgreSQL. Você pode acompanhar no Azure Cloud Shell, em uma máquina virtual do Azure ou em sua máquina local.

Iniciar sessão na subscrição do Azure do utilizador

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

az login

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

O nome da conta de usuário que você 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

Use a CLI do Azure para adquirir um token de acesso para o usuário autenticado pelo Microsoft Entra ID acessar o Azure Cosmos for PostgreSQL. Eis um exemplo:

az account get-access-token --resource https://token.postgres.cosmos.azure.com

Depois que a autenticação for bem-sucedida, a ID do Microsoft Entra retorna 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 Azure Cosmos DB para PostgreSQL. O token é válido por pelo menos 5 minutos com o máximo de 90 minutos. O expiresOn define o tempo real de expiração do token.

Use um token como senha para entrar com o cliente psql

Ao se conectar, é melhor 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 PGPASSWORD ambiente. O motivo é que o token de acesso excede o comprimento da senha que o psql pode aceitar diretamente.

Aqui está um exemplo do Windows:

set PGPASSWORD=<TOKEN value from the previous step>

$env:PGPASSWORD='<TOKEN value from the previous step>'

Aqui está um exemplo de Linux/macOS:

export PGPASSWORD=<TOKEN value from the previous step>

Você também pode combinar as duas etapas anteriores usando a substituição de comandos. A recuperação de token pode ser encapsulada em uma variável e passada diretamente como um valor para PGPASSWORD a variável de ambiente:

export PGPASSWORD=$(az account get-access-token --resource-type oss-rdbms --query "[accessToken]" -o tsv)

Nota

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 da função Postgres da mesma sessão, você pode definir PGPASSWORD para 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 no PGPASSWORD.

Agora você pode iniciar uma conexão com o Azure Cosmos DB para PostgreSQL usando a conta de usuário do Microsoft Entra ID para a qual o token de acesso foi gerado. Você faria isso como normalmente faria 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 senha para entrar com o PgAdmin

Para se conectar usando um token de ID do Microsoft Entra com PgAdmin, execute estas etapas:

  1. Desmarque a opção Conectar agora na criação do servidor.
  2. Introduza os detalhes do servidor no separador Ligação e guarde.
    1. Verifique se um usuário válido do Microsoft Entra ID está especificado em Nome de usuário.
  3. No menu Objeto pgAdmin, selecione Conectar servidor.
  4. Introduza a palavra-passe do token Microsoft Entra ID quando lhe for pedido.

Aqui estão algumas considerações essenciais quando você está se conectando:

  • user@tenant.onmicrosoft.com é o nome do usuário do Microsoft Entra ID.
  • Certifique-se de usar a maneira exata como o usuário do Azure está escrito. Os nomes de usuário e grupo 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 dele.
  • A validade do token de acesso é de 5 minutos a 90 minutos. Você deve obter o token de acesso antes de iniciar a entrada no Azure Cosmos para PostgreSQL.

Agora você está autenticado em seu servidor Azure Cosmos for PostgreSQL por meio da autenticação Microsoft Entra ID.

Gerenciar funções Nativas do PostgreSQL

Quando a autenticação PostgreSQL nativa está habilitada no cluster, você pode adicionar e excluir funções do Postgres, além da função 'citus' interna. Você também pode redefinir a senha e modificar os privilégios do Postgres para funções nativas.

Como excluir uma função de usuário nativo do 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 citus função é privilegiada e não pode ser excluída. No entanto, citus a função será desabilitada se o método de autenticação 'Somente autenticação do Microsoft Entra ID' for selecionado para o cluster.

Como modificar privilégios para funções de usuário

Novas funções de usuário são comumente usadas para fornecer acesso ao banco de dados com privilégios restritos. Para modificar os privilégios do usuário, use comandos padrão do PostgreSQL, usando uma ferramenta como PgAdmin ou psql. Para obter mais informações, consulte Conectar-se a um cluster.

Por exemplo, para permitir que o PostgreSQL db_user leia mytable, conceda a permissão:

GRANT SELECT ON mytable TO db_user;

Para conceder as mesmas permissões à função user@tenant.onmicrosoft.com ID do Microsoft Entra, use o seguinte comando:

GRANT SELECT ON mytable TO "user@tenant.onmicrosoft.com";

O Azure Cosmos DB para PostgreSQL propaga instruções GRANT de tabela única por todo o cluster, aplicando-as em todos os nós de trabalho. Ele também propaga GRANTs que são de todo o sistema (por exemplo, para todas as tabelas em 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 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";

Próximos passos