使用 Microsoft Entra ID 和本机 PostgreSQL 角色向 Azure Cosmos DB for PostgreSQL 进行身份验证

适用对象：PostgreSQL 的 Azure Cosmos DB （由 PostgreSQL 的 Citus 数据库扩展提供支持）

在本文中，你将为 Azure Cosmos DB for PostgreSQL 配置身份验证方法。 你将管理 Microsoft Entra ID 管理员用户和本机 PostgreSQL 角色，以便向 Azure Cosmos DB for PostgreSQL 进行身份验证。 本文还介绍了如何将 Microsoft Entra ID 令牌与 Azure Cosmos DB for PostgreSQL 配合使用。

会创建一个 Azure Cosmos DB for PostgreSQL 群集，它具有名为“citus”的内置本机 PostgreSQL 角色。 完成群集预配后，可添加更多的本机 PostgreSQL 角色。

还可以为 Azure Cosmos DB for PostgreSQL 配置 Microsoft Entra ID（以前称为 Azure Active Directory）身份验证。 可以在群集上启用 Microsoft Entra ID 身份验证，也可以启用本机 PostgreSQL 身份验证。 预配群集后，可以随时更改在群集上启用的身份验证方法。 启用 Microsoft Entra ID 身份验证后，可以将多个 Microsoft Entra ID 用户添加到 Azure Cosmos DB for PostgreSQL 群集，并将其中的任何用户设为管理员。 Microsoft Entra ID 用户可以是用户，也可以是服务主体。

选择身份验证方法

你需要使用 Azure 门户在 Azure Cosmos DB for PostgreSQL 群集上配置身份验证方法。

在 Azure Cosmos DB for PostgreSQL 群集上完成以下各项，以启用或禁用 Microsoft Entra ID 身份验证和本机 PostgreSQL 身份验证。

1. 在群集页面的“群集管理”标题下，选择“身份验证”以打开身份验证管理选项。
2. 在“身份验证方法”部分，根据要求选择“仅限 PostgreSQL 身份验证”、“Microsoft Entra ID 身份验证”或“PostgreSQL 和 Microsoft Entra ID 身份验证”作为身份验证方法。

完成后，继续配置 Microsoft Entra ID 身份验证或在同一“身份验证”页面上添加本机 PostgreSQL 角色。

配置 Microsoft Entra ID 身份验证

先决条件

需要允许用户登录到 Microsoft Entra ID 租户中的 Azure Cosmos DB for PostgreSQL。 对于将用于 Azure Cosmos DB for PostgreSQL 群集身份验证的 Microsoft Entra ID 租户，应执行这些步骤一次。

az ad sp update --id b4fa09d8-5da5-4352-83d9-05c2a44cf431 --set accountEnabled=true

将 Microsoft Entra ID 管理员添加到 Azure Cosmos DB for PostgreSQL 群集

要在群集上添加或移除 Microsoft Entra ID 角色，请在“身份验证”页面上执行以下步骤：

1. 在“Microsoft Entra ID 身份验”部分中，选择“添加 Microsoft Entra ID 管理员”。
2. 在“选择 Microsoft Entra ID 管理员”面板中，选择当前 AD 租户中的一个或多个有效的 Microsoft Entra ID 用户或企业应用程序，从而将其设为 Azure Cosmos DB for PostgreSQL 群集上的 Microsoft Entra ID 管理员。
3. 单击“选择”以确认所做选择。
4. 在“身份验证”页面中，选择工具栏中的“保存”以保存所做更改，或继续添加本机 PostgreSQL 角色。

配置本机 PostgreSQL 身份验证

若要在群集上添加 Postgres 角色，请在“身份验证”页面上执行以下步骤：

1. 在“PostgreSQL 身份验证”部分中，选择“添加 PostgreSQL 角色”。
2. 输入角色名和密码。 选择“保存”。
3. 在“身份验证”页面中，选择工具栏中的“保存”以保存所做更改，或继续添加 Microsoft Entra ID 管理员用户。

系统将在群集的协调器节点上创建本机 PostgreSQL 用户，并将其传播到所有工作器节点。 通过 Azure 门户创建的角色具有 LOGIN 属性，这意味着他们是可以登录数据库的真实用户。

通过 Microsoft Entra ID 身份验证连接到 Azure Cosmos for PostgreSQL

Microsoft Entra ID 集成适用于标准 PostgreSQL 客户端工具（例如psql），这些工具并非可感知 Microsoft Entra ID 的工具，仅支持在连接到 PostgreSQL 时指定用户名和密码。 在这种情况下，Microsoft Entra ID 令牌将作为密码来进行传递。

我们已测试以下客户端：

• psql 命令行：使用 PGPASSWORD 变量传递令牌。
• 其他基于 libpq 的客户端：示例包括常见的应用程序框架和对象关系映射器 (ORM)。
• pgAdmin：在创建服务器时清除“立即连接”。

使用以下过程以 Azure Cosmos DB for PostgreSQL 用户的身份通过 Microsoft Entra ID 进行身份验证。 你可以在本地机器上跟随。

登录到用户的 Azure 订阅

首先使用 Azure CLI 通过 Microsoft Entra ID 进行身份验证。

az cloud set -n AzureChinaCloud
az login

该命令会打开浏览器窗口，以显示 Microsoft Entra ID 身份验证页。 它需要你提供 Microsoft Entra ID 用户名和密码。

用于身份验证的用户帐户名称（例如，user@tenant.partner.onmschina.cn）是下一步中将为其生成访问令牌的帐户名称。

检索 Microsoft Entra ID 访问令牌

使用 Azure CLI 获取经过 Microsoft Entra ID 身份验证的用户的访问令牌，以访问 Azure Cosmos for PostgreSQL。 下面是一个示例：

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

身份验证成功后，Microsoft Entra ID 将返回当前 Azure 订阅的访问令牌：

{
  "accessToken": "[TOKEN]",
  "expiresOn": "[expiration_date_and_time]",
  "subscription": "[subscription_id]",
  "tenant": "[tenant_id]",
  "tokenType": "Bearer"
}

该令牌是 Base64 形式的字符串。 它会对与经过身份验证的用户有关的所有信息进行编码，并且与 Azure Cosmos DB for PostgreSQL 服务相关联。 令牌的有效时长至少为 5 分钟，最多为 90 分钟。 expiresOn定义的是实际的令牌过期时间。

使用令牌作为密码以使用客户端 psql 登录

进行连接时，最好是将访问令牌用作 PostgreSQL 用户密码。

使用 psql 命令行客户端时，需要通过 PGPASSWORD 环境变量传递访问令牌。 原因是访问令牌超出了 psql 可以直接接受的密码长度。

下面是一个 Windows 示例：

set PGPASSWORD=<TOKEN value from the previous step>

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

下面是一个 Linux/macOS 示例：

export PGPASSWORD=<TOKEN value from the previous step>

还可通过命令替换，将前两个步骤合并在一起。 令牌检索可以封装到变量中，并作为 PGPASSWORD 环境变量的值直接传递：

export PGPASSWORD=$(az account get-access-token --resource https://token.postgres.cosmos.azure.cn --query "[accessToken]" -o tsv)

现在，可以使用为其生成访问令牌的 Microsoft Entra ID 用户帐户启动与 Azure Cosmos DB for PostgreSQL 的连接。 可以像通常使用用户帐户作为用户一样执行此操作，并在命令行中不使用“password”参数：

psql "host=mycluster.[uniqueID].postgres.cosmos.azure.cn user=user@tenant.partner.onmschina.cn dbname=[db_name] sslmode=require"

使用令牌作为密码以使用 PgAdmin 登录

要将 Microsoft Entra ID 令牌与 PgAdmin 配合使用以进行连接，请执行以下步骤：

1. 创建服务器时取消选中“立即连接”选项。
2. 在“连接”选项卡中输入服务器详细信息并保存。
   1. 确保在“用户名”中指定了有效的 Microsoft Entra ID 用户。
3. 在 pgAdmin 的“对象”菜单中，选择“连接服务器”。
4. 出现提示时，输入 Microsoft Entra ID 令牌密码。

下面是连接时的一些基本注意事项：

• user@tenant.partner.onmschina.cn是 Microsoft Entra ID 用户的名称。
• 请确保使用 Azure 用户的准确拼写方式。 Microsoft Entra ID 的用户名和组名区分大小写。
• 如果名称包含空格，请在每个空格前使用反斜杠 (\) 以对空格进行转义。
• 访问令牌的有效期为 5-90 分钟。 你应在启动 Azure Cosmos for PostgreSQL 登录之前获取访问令牌。

现在，可以通过 Microsoft Entra ID 身份验证方法向 Azure Cosmos for PostgreSQL 服务器进行身份验证。

管理本机 PostgreSQL 角色

在群集上启用本机 PostgreSQL 身份验证后，除了内置的“citus”角色外，还可以添加和移除 Postgres 角色。 还可以重置密码并修改本机角色的 Postgres 特权。

如何删除本机 PostgreSQL 用户角色或更改其密码

若要更新用户，请访问群集的“身份验证”页面，然后选择用户旁边的省略号 (...)。 单击省略号后会打开一个菜单，用于删除用户或重置其密码。

citus 角色具有特权，不能删除。 但是，如果为群集选择了“仅限 Microsoft Entra ID 身份验证”身份验证方法，系统将禁用citus角色。

如何修改用户角色的特权

新用户角色通常用于提供具有受限特权的数据库访问权限。 若要修改用户特权，请在 PgAdmin 或 psql 等工具中使用标准 PostgreSQL 命令。 有关详细信息，请参阅连接到群集。

例如，若要允许 PostgreSQL db_user 读取 mytable，请授予权限：

GRANT SELECT ON mytable TO db_user;

要向 Microsoft Entra ID 角色user@tenant.partner.onmschina.cn授予相同的权限，请使用以下命令：

GRANT SELECT ON mytable TO "user@tenant.partner.onmschina.cn";

Azure Cosmos DB for PostgreSQL 在整个群集中传播单表 GRANT 语句，将它们应用于所有工作器节点。 它还传播系统范围的 GRANT（例如，针对架构中的所有表）：

-- 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;

或者对于 Microsoft Entra ID 角色

-- applies to the coordinator node and propagates to worker nodes for Azure AD role user@tenant.partner.onmschina.cn
GRANT SELECT ON ALL TABLES IN SCHEMA public TO "user@tenant.partner.onmschina.cn";

后续步骤

• 了解 Azure Cosmos DB for PostgreSQL 中的身份验证
• 查看 Azure Cosmos DB for PostgreSQL 中的 Microsoft Entra ID 限制和局限性
• 查看Microsoft Entra ID 基础知识
• 详细了解 PostgreSQL 中的 SQL GRANT