使用 Microsoft Entra ID 向 Azure Database for PostgreSQL 灵活服务器进行身份验证

适用于：Azure Database for PostgreSQL 灵活服务器

在本文中，你将配置 Microsoft Entra ID 访问权限，以用于向 Azure Database for PostgreSQL 灵活服务器进行身份验证。 你还将了解如何将 Microsoft Entra 令牌与 Azure Database for PostgreSQL 灵活服务器配合使用。

可以在服务器预配期间或之后配置适用于 Azure Database for PostgreSQL 灵活服务器的 Microsoft Entra 身份验证。 只有 Microsoft Entra 管理员用户才能为基于 Microsoft Entra ID 的身份验证创建或启用用户。 建议不要使用 Microsoft Entra 管理员进行常规数据库操作，因为该角色具有提升的用户权限（如 CREATEDB）。

Azure Database for PostgreSQL 灵活服务器可以有多个 Microsoft Entra 管理员用户。 Microsoft Entra 管理员用户可以是用户、组或服务主体。

先决条件

配置网络要求

Microsoft Entra ID 是多租户应用程序。 它需要使用出站连接才能执行某些操作（例如添加 Microsoft Entra 管理员组）。 此外，你需要使用网络规则才能使 Microsoft Entra 连接正常工作，具体取决于你的网络拓扑：

• 公共访问（允许的 IP 地址）：无需额外的网络规则。

• 非公开访问（虚拟网络集成）：

  • 需要使用出站网络安全组 (NSG) 规则以允许虚拟网络流量仅到达 AzureActiveDirectory 服务标记。
  • 如果你使用路由表，则需要创建包含目标服务标记 AzureActiveDirectory 和下一个跃点 Internet 的规则。
  • （可选）如果使用的是代理，可以添加新的防火墙规则以允许 HTTP/S 流量仅到达 AzureActiveDirectory 服务标记。

• 自定义 DNS：如果在虚拟网络 (VNET) 中使用自定义 DNS，则还有其他注意事项。 在这种情况下，必须确保以下终结点解析为其相应的 IP 地址：login.partner.microsoftonline.cn：此终结点用于身份验证。 验证自定义 DNS 设置是否允许将 login.partner.microsoftonline.cn 解析为其正确的 IP 地址 microsoftgraph.chinacloudapi.cn：此终结点用于访问 Microsoft Graph API。 确保自定义 DNS 设置允许将 microsoftgraph.chinacloudapi.cn 解析为正确的 IP 地址。

若要在服务器预配期间设置 Microsoft Entra 管理员，请执行以下步骤：

1. 在服务器预配期间，在 Azure 门户中选择“PostgreSQL 和 Microsoft Entra 身份验证”或“仅 Microsoft Entra 身份验证”作为身份验证方法。
2. 在“设置管理员”选项卡上，在客户租户中选择要成为 Microsoft Entra 管理员的有效 Microsoft Entra 用户、组、服务主体或托管标识。

如果希望使用“PostgreSQL 和 Microsoft Entra 身份验证”方法，还可选择添加本地 PostgreSQL 管理员帐户。

若要在创建服务器后设置 Microsoft Entra 管理员，请执行以下步骤：

1. 在 Azure 门户中，选择要为 Microsoft Entra ID 启用的 Azure Database for PostgreSQL 灵活服务器实例。
2. 在“安全”下，选择“身份验证”。 然后基于你的需求，选择“PostgreSQL 和 Microsoft Entra 身份验证”或“仅 Microsoft Entra 身份验证”作为身份验证方法。
3. 选择“添加 Microsoft Entra 管理员”。 然后，在客户租户中选择要成为 Microsoft Entra 管理员的有效 Microsoft Entra 用户、组、服务主体或托管标识。
4. 选择“保存”。

通过使用 Microsoft Entra ID 连接到 Azure Database for PostgreSQL

以下概要关系图概述了将 Microsoft Entra 身份验证与 Azure Database for PostgreSQL 配合使用的工作流：

Microsoft Entra 集成适用于标准 PostgreSQL 工具（例如 psql），这些工具并非可感知 Microsoft Entra 的工具，仅支持在连接到 PostgreSQL 时指定用户名和密码。 如上图所示，Microsoft Entra 令牌作为密码传递。

我们已测试以下客户端：

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

使用 Microsoft Entra ID 进行身份验证

按照下面的过程，以 Azure Database for PostgreSQL 灵活服务器用户的身份向 Microsoft Entra ID 进行身份验证。

登录到用户的 Azure 订阅

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

az login

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

检索 Microsoft Entra 访问令牌

使用 Azure CLI 为经过 Microsoft Entra 身份验证的用户获取访问令牌，以访问 Azure Database for PostgreSQL。

az account get-access-token --resource https://ossrdbms-aad.database.chinacloudapi.cn

上述资源值必须按所示方式指定。 对于其他云，可以使用以下命令查找资源值：

az cloud show

对于 Azure CLI 版本 2.0.71 和更高版本，可以在以下更为方便的版本中为所有云指定命令：

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

身份验证成功后，Microsoft Entra ID 将返回访问令牌：

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

令牌是 Base64 字符串。 它对有关经身份验证的用户的所有信息进行编码，针对的是 Azure Database for PostgreSQL 服务。

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

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

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

下面是一个 Windows 示例：

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

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

下面是一个 Linux/macOS 示例：

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

还可以使用命令替换将步骤 2 和步骤 3 组合在一起。 令牌检索可以封装到变量中，并作为 PGPASSWORD 环境变量的值直接传递：

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

现在，你可以像往常一样使用 Azure Database for PostgreSQL 启动连接：

psql "host=mydb.postgres... user=user@tenant.partner.onmschina.cn dbname=postgres sslmode=require"

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

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

1. 打开 Pgadmin，在左侧菜单中单击“注册”，然后选择“服务器”
2. 在“常规”选项卡中提供连接名称，并清除“立即连接”选项。
3. 单击“连接”选项卡，提供 Azure Database for PostgreSQL 灵活服务器实例的“主机名/地址”和“用户名”详细信息，然后保存。 用户名是你的 Microsoft Entra ID 或电子邮件
4. 在浏览器菜单中选择你的 Azure Database for PostgreSQL 灵活服务器连接，然后单击“连接服务器”
5. 出现提示时，请输入 Active Directory 令牌密码。

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

• user@tenant.partner.onmschina.cn 是 Microsoft Entra 用户的 userPrincipalName。
• 请确保使用 Azure 用户的准确拼写方式。 Microsoft Entra 的用户名和组名区分大小写。
• 如果名称包含空格，请在每个空格前使用反斜杠 (\) 以对空格进行转义。 可以使用 Azure CLI 获取登录用户并设置 PGUGSER 环境变量的值：

  export PGUSER=$(az ad signed-in-user show --query "[userPrincipalName]" -o tsv | sed 's/ /\\ /g')
  

• 访问令牌的有效期为 5 - 60 分钟。 建议在启动 Azure Database for PostgreSQL 登录之前获取访问令牌。

现在，你已通过 Microsoft Entra 身份验证方法向 Azure Database for PostgreSQL 服务器进行了身份验证。

以组成员身份向 Microsoft Entra ID 进行身份验证

在 Azure Database for PostgreSQL 灵活服务器中创建 Microsoft Entra 组

若要使 Microsoft Entra 组可以访问数据库，请使用你用于用户的同一机制，但需指定组名称。 例如：

select * from  pgaadauth_create_principal('Prod DB Readonly', false, false).

组成员登录时，他们使用其访问令牌，但将组名称指定为用户名。

登录到用户的 Azure 订阅

使用 Azure CLI 向 Microsoft Entra ID 进行身份验证。 用户需要是 Microsoft Entra 组的成员。

az login

检索 Microsoft Entra 访问令牌

使用 Azure CLI 为经过 Microsoft Entra 身份验证的用户获取访问令牌，以访问 Azure Database for PostgreSQL。

az account get-access-token --resource https://ossrdbms-aad.database.chinacloudapi.cn

必须完全按照所示方式指定初始资源值。 对于其他云，可以使用以下命令查找资源值：

az cloud show

对于 Azure CLI 版本 2.0.71 和更高版本，可以在以下更为方便的版本中为所有云指定命令：

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

身份验证成功后，Microsoft Entra ID 将返回访问令牌：

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

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

以组成员身份进行连接时，以下注意事项非常重要：

• 组名称是你尝试连接的 Microsoft Entra 组的名称。
• 请确保使用 Microsoft Entra 组名称的准确拼写方式。 Microsoft Entra 的用户名和组名区分大小写。
• 作为组进行连接时，请仅使用组名称，而不要使用组成员的别名。
• 如果名称包含空格，请在每个空格前使用反斜杠 (\) 以对空格进行转义。
• 访问令牌的有效期为 5 - 60 分钟。 建议在启动 Azure Database for PostgreSQL 登录之前获取访问令牌。

现在，你已通过 Microsoft Entra 身份验证方法向 PostgreSQL 服务器进行了身份验证。

后续步骤

• 查看向 Azure Database for PostgreSQL 灵活服务器进行 Microsoft Entra 身份验证的总体概念。
• 了解如何管理 Microsoft Entra 用户 - Azure Database for PostgreSQL 灵活服务器。