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

项目
04/26/2024

适用于：Azure Database for PostgreSQL 单一服务器

重要

Azure Database for PostgreSQL - 单一服务器即将停用。强烈建议升级到 Azure Database for PostgreSQL 灵活服务器。有关迁移到 Azure Database for PostgreSQL 灵活服务器的详细信息，请参阅 Azure Database for PostgreSQL 单一服务器的最新动态。

本文将介绍如何配置 Azure Database for PostgreSQL 的 Microsoft Entra ID 访问，以及如何使用 Microsoft Entra 令牌进行连接。

设置 Microsoft Entra 管理员用户

只有 Microsoft Entra 管理员用户才能为基于 Microsoft Entra ID 的身份验证创建/启用用户。我们建议不要使用 Microsoft Entra 管理员进行常规数据库操作，因为它具有提升的用户权限（如 CREATEDB）。

要设置 Microsoft Entra 管理员（可以使用用户或组），请遵循以下步骤

在 Azure 门户中，选择要启用 Microsoft Entra ID 的 Azure Database for PostgreSQL 实例。
在“设置”下，选择“Active Directory 管理员”：

设置 Microsoft Entra 管理员

在客户租户中选择有效的 Microsoft Entra 用户成为 Microsoft Entra 管理员。

重要

设置管理员时，将向具有完全管理员权限的 Azure Database for PostgreSQL 服务器添加新用户。 Azure Database for PostgreSQL 中的 Microsoft Entra 管理员用户将拥有“azure_ad_admin”角色。每个 PostgreSQL 服务器只能创建一个 Microsoft Entra 管理员，选择另一个管理员后，将覆盖为服务器配置的现有 Microsoft Entra 管理员。可以指定 Microsoft Entra 组（而不是单个用户）来拥有多个管理员。

每个 PostgreSQL 服务器只能创建一个 Microsoft Entra 管理员，选择另一个管理员后，将覆盖为服务器配置的现有 Microsoft Entra 管理员。可以指定 Microsoft Entra 组（而不是单个用户）来拥有多个管理员。请注意，你随后将用该组名称登录，以进行管理。

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

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

身份验证流

我们将 Microsoft Entra 集成设计为可与常见 PostgreSQL 工具（例如 psql）结合使用，这些工具并非 Microsoft Entra 感知工具，并且在连接到 PostgreSQL 时仅支持指定用户名和密码。我们将 Microsoft Entra 令牌作为密码传递，如上图所示。

目前已测试以下客户端：

psql 命令行（利用 PGPASSWORD 变量传递令牌，有关详细信息，请参阅步骤 3）
Azure Data Studio（使用 PostgreSQL 扩展）
其他基于 libpq 的客户端（例如常见的应用程序框架和 ORM）
PgAdmin（在创建服务器时取消选中“连接”。有关详细信息，请参阅步骤 4）

以下是用户/应用程序使用 Microsoft Entra ID 进行身份验证所需的步骤：

先决条件

请确保已安装 Azure CLI。

以单个用户身份向 Microsoft Entra ID 进行身份验证

首先使用 Azure CLI 工具向 Microsoft Entra ID 进行身份验证。

az login

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

步骤 2：检索 Microsoft Entra 访问令牌

调用 Azure CLI 工具，获取步骤 1 中经过 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"
}

该令牌是一个 Base 64 字符串，该字符串对有关经过身份验证的用户的所有信息进行编码，并且针对的是 Azure Database for PostgreSQL 服务。

步骤 3：使用令牌作为密码以使用客户端 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>

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

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

步骤 4：使用令牌作为密码以使用 PgAdmin 登录

要使用 Microsoft Entra 令牌和 pgAdmin 进行连接，需要执行以下步骤：

创建服务器时取消选中“立即连接”选项。
在“连接”选项卡中输入服务器详细信息并保存。
在浏览器菜单中，选择“连接到 Azure Database for PostgreSQL 服务器”
出现提示时，输入 AD 令牌。

连接时的重要注意事项如下：

user@tenant.partner.onmschina.cn 是 Microsoft Entra 用户的名称
由于 Microsoft Entra 用户和组名称区分大小写，因此请确保使用 Azure 用户的准确拼写方式。
如果名称包含空格，请在每个空格前使用 \ 以对空格进行转义。
访问令牌的有效期介于 5 分钟到 60 分钟之间。建议你就在启动 Azure Database for PostgreSQL 登录之前获取访问令牌。

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

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

步骤 1：在 Azure Database for PostgreSQL 中创建 Microsoft Entra 组

要启用 Microsoft Entra 组以访问数据库，请使用与用户相同的机制，只不过要指定组名称：

示例：

CREATE USER <new_user> IN ROLE azure_ad_user;

登录时，组成员将使用其个人访问令牌，但使用指定为用户名的组名称进行签名。

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

az login

步骤 3：检索 Microsoft Entra 访问令牌

调用 Azure CLI 工具，获取步骤 2 中经过 Microsoft Entra 身份验证的用户的访问令牌，以访问 Azure Database for PostgreSQL。

示例：

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

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

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

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

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

步骤 4：使用令牌作为密码通过 psql 或 PgAdmin 登录（请参阅上述用户连接步骤）

作为组成员进行连接时的重要注意事项：

groupname@mydb 是你尝试连接时所用的 Microsoft Entra 组的名称
始终在 Microsoft Entra 用户/组名称后面追加服务器名称（例如 @mydb)
请确保使用 Microsoft Entra 组名称的准确拼写方式。
Microsoft Entra 的用户名和组名区分大小写
在作为组进行连接时，请仅使用组名称（例如 GroupName@mydb），而不要使用组成员的别名。
如果名称包含空格，请在每个空格前使用 \ 以对空格进行转义。
访问令牌的有效期介于 5 分钟到 60 分钟之间。建议你就在启动 Azure Database for PostgreSQL 登录之前获取访问令牌。

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

在 Azure Database for PostgreSQL 中创建 Microsoft Entra 用户

要向 Azure Database for PostgreSQL 数据库添加 Microsoft Entra 用户，请在连接后执行以下步骤（请参阅后面有关如何连接的部分）：

首先确保 Microsoft Entra 用户 <user>@yourtenant.partner.onmschina.cn 是 Microsoft Entra 租户中的有效用户。
以 Microsoft Entra 管理员用户身份登录到 Azure Database for PostgreSQL 实例。
在 Azure Database for PostgreSQL 中创建角色 <user>@yourtenant.partner.onmschina.cn。
使 <user>@yourtenant.partner.onmschina.cn 成为角色 azure_ad_user 的成员。这必须只提供给 Microsoft Entra 用户。

示例：

CREATE USER "user1@yourtenant.partner.onmschina.cn" IN ROLE azure_ad_user;

注意

通过 Microsoft Entra ID 对用户进行身份验证时，不会向用户授予访问 Azure Database for PostgreSQL 数据库中的对象的任何权限。必须手动向用户授予所需的权限。

令牌验证

Azure Database for PostgreSQL 中的 Microsoft Entra 身份验证确保 PostgreSQL 服务器中存在用户，并通过验证令牌的内容来检查令牌的有效性。执行以下令牌验证步骤：

令牌由 Microsoft Entra ID 签名，并且未被篡改
令牌由 Microsoft Entra ID 为与服务器关联的租户颁发
令牌尚未过期
令牌用于 Azure Database for PostgreSQL 资源（而不是其他 Azure 资源）

将现有 PostgreSQL 用户迁移到基于 Microsoft Entra ID 的身份验证

可以为现有用户启用 Microsoft Entra 身份验证。有两种要考虑的事例：

案例 1：PostgreSQL 用户名与 Microsoft Entra 用户主体名称匹配

在极少数情况下，你的现有用户已与 Microsoft Entra 用户名匹配，则可以向他们授予 azure_ad_user 角色，从而为他们启用 Microsoft Entra 身份验证：

GRANT azure_ad_user TO "existinguser@yourtenant.partner.onmschina.cn";

他们现在可以使用 Microsoft Entra 凭据登录，而不是使用以前配置的 PostgreSQL 用户密码。

案例 2：PostgreSQL 用户名不同于 Microsoft Entra 用户主体名称

如果 PostgreSQL 用户不存在于 Microsoft Entra ID 中或具有其他用户名，则可以使用 Microsoft Entra 组作为此 PostgreSQL 用户进行身份验证。可以创建一个名称与 PostgreSQL 用户匹配的 Microsoft Entra 组，然后向现有的 PostgreSQL 用户授予角色 azure_ad_user，从而将现有 Azure Database for PostgreSQL 用户迁移到 Microsoft Entra ID 中：

GRANT azure_ad_user TO <new_user>;

这假定你已在 Microsoft Entra ID 中创建了组“DBReadUser”。属于该组的用户现在能够以此用户身份登录到数据库。

后续步骤

回顾向 Azure Database for PostgreSQL - 单一服务器进行 Microsoft Entra 身份验证的总体概念