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

2025-10-23

本文将配置 Microsoft Entra ID 访问，以便通过 Azure Database for PostgreSQL 进行身份验证。此外，还了解如何将 Microsoft Entra 令牌与 Azure Database for PostgreSQL 灵活服务器实例配合使用。

可以在服务器预配期间或稍后为 Azure Database for PostgreSQL 灵活服务器实例配置 Microsoft Entra 身份验证。只有Microsoft Entra 管理员用户可以创建或启用基于 entra ID 的身份验证Microsoft用户。请勿将 Microsoft Entra 管理员用于常规数据库操作，因为该角色具有提升的用户权限（例如 CREATEDB）。

可以在 Azure Database for PostgreSQL 中使用多位 Microsoft Entra 管理员用户。 Microsoft Entra 管理员用户可以是用户、组或服务主体。

先决条件

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

配置网络要求

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

网络要求因拓扑而异：

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

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

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

如果需要使用 PostgreSQL 和 Microsoft Entra 身份验证 方法，可以选择添加本地 PostgreSQL 管理员帐户。

注释

在服务器预配期间，只能添加一个Microsoft Entra 管理员。创建服务器后，可以添加多个Microsoft Entra 管理员用户。

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

在 Azure 门户中，选择要为 Microsoft Entra ID 启用的 Azure Database for PostgreSQL 灵活服务器的实例。
在 “安全性”下，选择“ 身份验证”。然后，根据要求，选择 PostgreSQL 和 Microsoft Entra 身份验证 或 Microsoft Entra 身份验证 作为身份验证方法。
选择 “添加Microsoft条目管理员。然后选择客户租户中的有效Microsoft Entra 用户、组、服务主体或托管标识，以成为 Microsoft Entra 管理员。
选择“保存”。

重要

设置管理员时，会将新用户添加到具有完全管理员权限的 Azure Database for PostgreSQL 灵活服务器实例。

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

Microsoft Entra 集成适用于标准 PostgreSQL 工具，如 psql，它们不Microsoft Entra 感知，并且仅支持在连接到 PostgreSQL 时指定用户名和密码。

我们测试了以下客户端：

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 配合使用进行连接，请执行以下步骤：

打开 PgAdmin 并选择 “注册>服务器”。
在常规选项卡上，输入连接名称并取消选中立即连接。
在 “连接 ”选项卡上，输入主机详细信息。将 用户名 设置为Microsoft Entra UPN（例如 user@tenant.partner.onmschina.cn）。保存。
在树中，选择服务器，然后选择 “连接服务器”。
出现提示时，请将访问令牌粘贴为密码。

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

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).

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

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

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

注释

支持将托管标识和服务主体用作组成员。

使用 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 分钟。在连接之前获取它;不要将令牌存储在脚本中。

小窍门

如果身份验证失败，请验证数据库角色是否存在（例如，使用 \du）并确认 pgaadauth.enable_group_sync 设置。

现已通过 Microsoft Entra 身份验证向 PostgreSQL 服务器进行身份验证。

通过

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

先决条件

配置网络要求

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

使用 Microsoft Entra ID 进行身份验证

登录到 Azure

获取 Microsoft Entra 访问令牌

将令牌用作使用客户端 psql 登录的密码

将令牌用作使用 PgAdmin 登录的密码

使用Microsoft Entra ID 作为组成员进行身份验证

创建组主体

登录到 Azure

获取 Microsoft Entra 访问令牌

将令牌用作使用 psql 或 PgAdmin 登录的密码

相关内容

其他资源