如何使用Microsoft Entra ID通过Azure Database for PostgreSQL进行身份验证

本文将配置Microsoft Entra ID access以使用 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 管理员用户可以是用户、组或服务主体。

先决条件

• 需要具有活动订阅的Azure帐户。 创建试用帐户。

配置网络要求

Microsoft Entra ID是多租户应用程序。 它需要出站连接以进行诸如添加 Microsoft Entra 管理员组等操作。

网络要求因拓扑而异：

• 公共访问（允许的 IP 地址），不需要额外的出站规则。
• 私密访问（虚拟网络集成）:
  • 添加仅允许流量到服务标签的 AzureActiveDirectory 出站 NSG 规则。
  • 如果使用路由表，请添加一个目的地为 AzureActiveDirectory 和下一跃点为 Internet 的路由。
  • 如果使用代理，则仅允许发往 AzureActiveDirectory 服务标签的 HTTPS 流量。
• 自定义 DNS：
  • 确保这些主机名能够在公共网络上解析：login.chinacloudapi.cn（authentication）和microsoftgraph.chinacloudapi.cn（Microsoft Graph API）。
  • 如果解析失败，管理员分配和令牌获取操作将失败。

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

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

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

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

1. 在Azure portal中，选择要为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 集成适用于标准 PostgreSQL 工具（例如 psql），这些工具并非可感知 Microsoft Entra 的工具，仅支持在连接到 PostgreSQL 时指定用户名和密码。

测试的客户端包括：

• PostgreSQL for Visual Studio Code 扩展：使用 AUTHENTICATION TYPE 将身份验证方法设置为 Entra Auth。
• psql 命令行：使用 PGPASSWORD 变量传递令牌。
• 其他基于 libpq 的客户端：示例包括常见的应用程序框架和对象关系映射器 (ORM)。
• PgAdmin：在创建服务器时取消选中“立即连接”。

使用 Microsoft Entra ID 进行身份验证

使用以下过程以Microsoft Entra ID作为Azure Database for PostgreSQL灵活服务器实例用户进行身份验证。

你可使用以下方法跟进：

• Azure虚拟机
• 本地计算机

登录到 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 登录

连接时，请使用 access 令牌作为 PostgreSQL 用户密码。

使用 psql 命令行客户端时，需要通过 PGPASSWORD 环境变量传递access令牌。 访问令牌长度超出了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. 在 “连接 ”选项卡上，输入主机详细信息。 将 用户名 设置为Microsoft Entra UPN（例如 user@tenant.partner.onmschina.cn）。 保存。
4. 在树中，选择服务器，然后选择 “连接服务器”。
5. 出现提示时，请将访问令牌粘贴为密码。

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

• user@tenant.partner.onmschina.cn 是 Microsoft Entra 用户的 userPrincipalName。

• 请务必使用Azure用户拼写的确切方式。 Microsoft Entra 的用户名和组名区分大小写。

• 如果名称包含空格，请在每个空格前使用反斜杠 (\) 对空格进行转义。 可以使用Azure CLI获取已登录用户，并为 PGUSER 环境变量设置值：

  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作为组成员进行身份验证

本部分介绍如何使用 Microsoft Entra 组进行连接。 你必须是组的成员，并且组必须在数据库中创建（即进行映射）。

创建组主体

在数据库中创建组主体（角色）（根据需要替换显示名称）：

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

如果禁用组同步，成员可以使用其access令牌登录，并将组名称指定为用户名。

如果启用组同步（通过设置为“ON”pgaadauth.enable_group_sync服务器参数），成员应使用其单独的Microsoft Entra ID凭据登录，但他们仍然可以使用组名称作为用户名登录。

• 由于兼容性原因，组登录仍然可用，但您可以通过使用 ALTER ROLE "ROLE_NAME" NOLOGIN; 将其禁用。
• 请勿删除组角色以保持同步。
• 每个组每 30 分钟自动同步一次。
• 可以使用： SELECT * FROM pgaadauth_sync_roles_for_group_members(); （pgaadauth.enable_group_sync 参数必须为“ON”）触发手动同步。
• 不会同步对组元数据（如组名称）的更改。
• 组成员身份更改已同步。

登录到 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 组显示名称（区分大小写）完全匹配。
• 仅使用组名称，而不是成员别名。
• 在需要时对空格进行转义（例如 Prod\ DB\ Readonly）。
• 令牌有效期为 5-60 分钟。 在连接之前获取它;不要将令牌存储在脚本中。

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

相关内容

• Microsoft使用 Azure Database for PostgreSQL
• 在 Azure 的 PostgreSQL 数据库中管理 Microsoft Entra 角色