设置 Azure Database for MySQL 灵活服务器的 Microsoft Entra 身份验证

项目
11/26/2024

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

本教程介绍如何设置 Azure Database for MySQL 灵活服务器的 Microsoft Entra 身份验证。

本教程介绍如何执行下列操作：

配置 Microsoft Entra 管理员。
使用 Microsoft Entra ID 连接到 Azure Database for MySQL 灵活服务器。

先决条件

具有活动订阅的 Azure 帐户。
如果没有 Azure 订阅，可在开始前创建一个 Azure 试用帐户。
安装 Azure CLI 或将其升级到最新版本。请参阅安装 Azure CLI。

配置 Microsoft Entra 管理中心

若要创建 Microsoft Entra 管理员用户，请按照以下步骤操作。

在 Azure 门户中，选择要为 Microsoft Entra ID 启用的 Azure Database for MySQL 灵活服务器实例。
在“安全性”窗格下，选择“身份验证”：
共有三类身份验证：
- 仅 MySQL 身份验证 - 默认情况下，MySQL 使用内置的 mysql_native_password 身份验证插件，该插件使用原生密码哈希方法执行身份验证
- 仅 Microsoft Entra 身份验证 - 仅允许使用 Microsoft Entra 帐户进行身份验证。禁用 mysql_native_password 身份验证并启用服务器参数 aad_auth_only
- MySQL 和 Microsoft Entra 身份验证 - 允许使用本机 MySQL 密码或 Microsoft Entra 帐户进行身份验证。禁用服务器参数 aad_auth_only
选择标识 - 选择/添加用户分配的托管标识。需要以下权限，UMI 才能作为服务器标识从 Microsoft Graph 进行读取。或者，为用户分配的托管标识授予目录读取者角色。
- User.Read.All：允许访问 Microsoft Entra 用户信息。
- GroupMember.Read.All：允许访问 Microsoft Entra 组信息。
- Application.Read.ALL：允许访问 Microsoft Entra 服务主体（应用程序）信息。

重要

只有至少具有特权角色管理员角色的用户才能授予这些权限。

在客户租户中选择有效的 Microsoft Entra 用户或 Microsoft Entra 组作为 Microsoft Entra 管理员。启用 Microsoft Entra 身份验证支持后，可以将 Microsoft Entra 管理员添加为有权将 Microsoft Entra 用户添加到 MySQL 服务器的的安全主体。

注意

每个 MySQL 服务器只能创建一个 Microsoft Entra 管理员，选择另一个管理员将覆盖为服务器配置的现有 Microsoft Entra 管理员。

向用户分配的托管标识授予权限

以下示例 PowerShell 脚本为 UMI 授予必要的权限。此示例将权限分配给 UMI umiservertest。

若要运行脚本，必须以“全局管理员”或“特权角色管理员”角色的用户身份登录。

该脚本向 UMI 授予访问 Microsoft Graph 的 User.Read.All、GroupMember.Read.All 和 Application.Read.ALL 权限。

# Script to assign permissions to the UMI "umiservertest"

import-module AzureAD
$tenantId = '<tenantId>' # Your Azure AD tenant ID

Connect-AzureAD -TenantID $tenantId -Environment AzureChinaCloud
# Log in as a user with a "Global Administrator" or "Privileged Role Administrator" role
# Script to assign permissions to an existing UMI 
# The following Microsoft Graph permissions are required: 
#   User.Read.All
#   GroupMember.Read.All
#   Application.Read.ALL

# Search for Microsoft Graph
$AAD_SP = Get-AzureADServicePrincipal -SearchString "Microsoft Graph";
$AAD_SP
# Use Microsoft Graph; in this example, this is the first element $AAD_SP[0]

#Output

#ObjectId                             AppId                                DisplayName
#--------                             -----                                -----------
#47d73278-e43c-4cc2-a606-c500b66883ef 00000003-0000-0000-c000-000000000000 Microsoft Graph
#44e2d3f6-97c3-4bc7-9ccd-e26746638b6d 0bf30f3b-4a52-48df-9a82-234910c4a086 Microsoft Graph #Change 

$MSIName = "<managedIdentity>";  # Name of your user-assigned
$MSI = Get-AzureADServicePrincipal -SearchString $MSIName 
if($MSI.Count -gt 1)
{ 
Write-Output "More than 1 principal found, please find your principal and copy the right object ID. Now use the syntax $MSI = Get-AzureADServicePrincipal -ObjectId <your_object_id>"

# Choose the right UMI

Exit
} 

# If you have more UMIs with similar names, you have to use the proper $MSI[ ]array number

# Assign the app roles

$AAD_AppRole = $AAD_SP.AppRoles | Where-Object {$_.Value -eq "User.Read.All"}
New-AzureADServiceAppRoleAssignment -ObjectId $MSI.ObjectId -PrincipalId $MSI.ObjectId -ResourceId $AAD_SP.ObjectId -Id $AAD_AppRole.Id 
$AAD_AppRole = $AAD_SP.AppRoles | Where-Object {$_.Value -eq "GroupMember.Read.All"}
New-AzureADServiceAppRoleAssignment -ObjectId $MSI.ObjectId -PrincipalId $MSI.ObjectId -ResourceId $AAD_SP.ObjectId -Id $AAD_AppRole.Id
$AAD_AppRole = $AAD_SP.AppRoles | Where-Object {$_.Value -eq "Application.Read.All"}
New-AzureADServiceAppRoleAssignment -ObjectId $MSI.ObjectId -PrincipalId $MSI.ObjectId -ResourceId $AAD_SP.ObjectId -Id $AAD_AppRole.Id

在该脚本的最后步骤中，如果具有类似名称的更多 UMI，则必须使用正确的 $MSI[ ]array 编号。例如 $AAD_SP.ObjectId[0]。

检查用户分配的托管标识的权限

若要检查 UMI 的权限，请转到 Azure 门户。在“Microsoft Entra ID”资源中，转到“企业应用程序”。针对“应用程序类型”选择“所有应用程序”，然后搜索已创建的 UMI。

选择 UMI，然后转到“安全”下的“权限”设置。

将权限授予 UMI 后，将为使用分配为服务器标识的 UMI 创建的所有服务器启用这些权限。

使用 Microsoft Entra ID 连接到 Azure Database for MySQL 灵活服务器

1 - 使用 Microsoft Entra ID 进行身份验证

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

使用 az login 命令登录到 Azure 帐户。请注意 ID 属性，它指的是 Azure 帐户的订阅 ID：
```
az login
```

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

如果你有多个订阅，请使用 az account set 命令选择相应订阅：
```
az account set --subscription \<subscription id\>
```

2 - 检索 Microsoft Entra 访问令牌

调用 Azure CLI 工具，获取在步骤 1 中经过 Microsoft Entra 身份验证的用户的访问令牌，以访问 Azure Database for MySQL 灵活服务器。

示例：

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
```

使用 PowerShell 时，可以使用以下命令获取访问令牌：

$accessToken = Get-AzAccessToken -ResourceUrl https://ossrdbms-aad.database.chinacloudapi.cn 
$accessToken.Token | out-file C:\temp\MySQLAccessToken.txt

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

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

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

访问令牌的有效期为 5 - 60 分钟。建议在启动 Azure Database for MySQL 灵活服务器登录之前获取访问令牌。

可以使用以下 Powershell 命令查看令牌有效性。

   $accessToken.ExpiresOn.DateTime

3 - 使用令牌作为密码以使用 MySQL 登录

在连接时，需要将访问令牌用作 MySQL 用户密码。可以使用上述方法，通过 GUI 客户端（如 MySQL Workbench）来检索令牌。

使用 MySQL CLI 连接到 Azure Database for MySQL 灵活服务器

使用 CLI 时，可以使用下面的方法快速连接：

示例 (Linux/macOS)：

mysql -h mydb.mysql.database.chinacloudapi.cn \ 
  --user user@tenant.partner.onmschina.cn \ 
  --enable-cleartext-plugin \
  --password=`az account get-access-token --resource-type oss-rdbms --output tsv --query accessToken`

示例 (PowerShell)：

mysql -h mydb.mysql.database.chinacloudapi.cn \
  --user user@tenant.partner.onmschina.cn \
  --enable-cleartext-plugin \
  --password=$(az account get-access-token --resource-type oss-rdbms --output tsv --query accessToken)


mysql -h mydb.mysql.database.chinacloudapi.cn \
  --user user@tenant.partner.onmschina.cn \
  --enable-cleartext-plugin \
  --password=$((Get-AzAccessToken -ResourceUrl https://ossrdbms-aad.database.chinacloudapi.cn).Token)

使用 MySQL Workbench 连接到 Azure Database for MySQL 灵活服务器

启动 MySQL Workbench 并选择“数据库”选项，然后选择“连接到数据库”。
在“主机名”字段中，输入 MySQL FQDN，例如 mysql.database.chinacloudapi.cn。
在“用户名”字段中，输入 MySQL Microsoft Entra 管理员名称。例如 user@tenant.partner.onmschina.cn。
在密码字段中，选择“在保管库中存储”，在其中粘贴文件中的访问令牌，例如 C:\temp\MySQLAccessToken.txt。
选择“高级”选项卡，确保选中“启用明文身份验证插件”。
选择“确定”，从而连接到数据库。

连接时的重要注意事项

user@tenant.partner.onmschina.cn 是你尝试要以其身份连接的 Microsoft Entra 用户或组的名称
请确保使用 Microsoft Entra 用户或组名称的准确拼写方式
Microsoft Entra 的用户名和组名区分大小写
在作为组进行连接时，请只使用组名称（例如 GroupName）
如果名称包含空格，请在每个空格前使用 \ 对该空格进行转义

注意

“enable-cleartext-plugin”设置 - 需要对其他客户端使用类似的配置，以确保令牌在不进行哈希处理的情况下发送到服务器。

现在，你已使用 Microsoft Entra 身份验证向 MySQL 灵活服务器进行身份验证。

其他 Microsoft Entra 管理中心命令

管理服务器的 Active Directory 管理员
```
az mysql flexible-server ad-admin
```
创建 Active Directory 管理员
```
az mysql flexible-server ad-admin create
```
示例：使用用户“john@contoso.com”、管理员 ID“00000000-0000-0000-0000-000000000000”和标识“test-identity”创建 Active Directory 管理员
```
az mysql flexible-server ad-admin create -g testgroup -s testsvr -u john@contoso.com -i 00000000-0000-0000-0000-000000000000 --identity test-identity
```

删除 Active Directory 管理员

az mysql flexible-server ad-admin delete

示例：删除 Active Directory 管理员

az mysql flexible-server ad-admin delete -g testgroup -s testsvr

列出所有 Active Directory 管理员

az mysql flexible-server ad-admin list

示例：列出 Active Directory 管理员

az mysql flexible-server ad-admin list -g testgroup -s testsvr

获取 Active Directory 管理员

az mysql flexible-server ad-admin show

示例：获取 Active Directory 管理员

az mysql flexible-server ad-admin show -g testgroup -s testsvr

等待 Active Directory 管理员满足某些条件

az mysql flexible-server ad-admin wait

示例：

等待创建 Active Directory 管理员

az mysql flexible-server ad-admin wait -g testgroup -s testsvr --exists

等待删除 Active Directory 管理员

az mysql flexible-server ad-admin wait -g testgroup -s testsvr –deleted

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

若要向 Azure Database for MySQL 数据库添加 Microsoft Entra 用户，请在连接后执行以下步骤：

首先确保 Microsoft Entra 用户 <user>@yourtenant.partner.onmschina.cn 是 Microsoft Entra 租户中的有效用户。
以 Microsoft Entra 管理员用户身份登录到 Azure Database for MySQL 实例。
在 Azure Database for MySQL 中创建用户 <user>@yourtenant.partner.onmschina.cn。

示例：

CREATE AADUSER 'user1@yourtenant.partner.onmschina.cn';

如果用户名超过 32 个字符，建议改用别名，以供连接时使用：

示例：

CREATE AADUSER 'userWithLongName@yourtenant.partner.onmschina.cn' as 'userDefinedShortName';

注意

MySQL 会忽略前导空格和尾随空格，因此用户名不应包含任何前导空格或尾随空格。
通过 Microsoft Entra ID 对用户进行身份验证时，不会向用户授予访问 Azure Database for MySQL 数据库中的对象的任何权限。必须手动向用户授予所需的权限。

在 Azure Database for MySQL 中创建 Microsoft Entra 组

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

示例：

CREATE AADUSER 'Prod_DB_Readonly';

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

与应用程序驱动程序的兼容性

大部分驱动程序均受支持，但请确保使用以明文形式发送密码的设置，这样，无需进行修改就能发送令牌。

C/C++
- libmysqlclient：支持
- mysql-connector-c++：支持
Java
- 连接器/J (mysql-connector-java)：支持，必须使用 useSSL 设置
Python
- 连接器/Python：支持
Ruby
- mysql2：支持
.NET
- mysql-connector-net：支持，需要为 mysql_clear_password 添加插件
- mysql-net/MySqlConnector：支持
Node.js
- mysqljs：不支持（不以明文形式发送无修补程序的令牌）
- node-mysql2：支持
Perl
- DBD::mysql：支持
- Net::MySQL：不支持
Go
- go-sql-driver：支持，将 ?tls=true&allowCleartextPasswords=true 添加到连接字符串
PHP
- mysqli 扩展：支持
- PDO_MYSQL 驱动程序：支持

后续步骤

请查看使用 Azure Database for MySQL 灵活服务器进行 Microsoft Entra 身份验证的概念

通过

设置 Azure Database for MySQL 灵活服务器的 Microsoft Entra 身份验证

先决条件

配置 Microsoft Entra 管理中心

向用户分配的托管标识授予权限

检查用户分配的托管标识的权限

使用 Microsoft Entra ID 连接到 Azure Database for MySQL 灵活服务器

1 - 使用 Microsoft Entra ID 进行身份验证

2 - 检索 Microsoft Entra 访问令牌

3 - 使用令牌作为密码以使用 MySQL 登录

使用 MySQL CLI 连接到 Azure Database for MySQL 灵活服务器

使用 MySQL Workbench 连接到 Azure Database for MySQL 灵活服务器

连接时的重要注意事项

其他 Microsoft Entra 管理中心命令

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

在 Azure Database for MySQL 中创建 Microsoft Entra 组

与应用程序驱动程序的兼容性

后续步骤

其他资源