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

先决条件

• 需要一个具有活动订阅的 Azure 帐户。 免费创建帐户。

配置网络要求

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

网络要求因拓扑而异：

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

若要在服务器预配期间设置 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 集成适用于标准 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 Cloud Shell
• Azure 虚拟机
• 本地计算机

登录到 Azure

首先使用 Azure CLI 通过 Microsoft Entra ID 进行身份验证。 在 Azure Cloud Shell 中无需执行此步骤。

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.windows.net

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

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.onmicrosoft.com dbname=postgres sslmode=require"

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

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

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

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

• user@tenant.onmicrosoft.com 是 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

使用 Azure CLI 向 Microsoft Entra ID 进行身份验证。 在 Azure Cloud Shell 中无需执行此步骤。 用户需要是 Microsoft Entra 组的成员。

az login

获取 Microsoft Entra 访问令牌

使用 Azure CLI 获取Microsoft Entra 经过身份验证的用户访问 Azure Database for PostgreSQL 的访问令牌。 下面是公有云的示例：

az account get-access-token --resource https://ossrdbms-aad.database.windows.net

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

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 服务器进行了身份验证。

相关内容

• 向 Azure Database for PostgreSQL 进行 Microsoft Entra 身份验证
• 在 Azure Database for PostgreSQL 中管理 Microsoft Entra 角色