你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。
适用于:Azure SQL 数据库
数据库级托管标识为 Azure SQL 数据库 中的单个数据库赋予其自己的用户分配的托管标识(UAMI)。 具有标识的数据库会以自身身份向 Azure 存储 进行身份验证,而不是以托管它的逻辑服务器的身份。
如果没有数据库级标识,逻辑服务器上的每个数据库都会共享该服务器的托管标识,因此它们都会访问同一存储。 数据库级身份将访问权限缩小到单一数据库,因此你可以只为每个数据库提供它所需的存储空间。
你选择的是数据库范围的凭证,这也是数据虚拟化查询用来读取 Azure Blob 存储 或 Azure Data Lake Storage (ADLS) Gen2 中 Parquet、CSV 和 Delta 文件的同一凭证。 请在两个凭据标识值中选择:
| 凭据标识 | 在以下情况下使用 |
|---|---|
DATABASE MANAGED IDENTITY |
存储账户和数据库在同一个 Microsoft Entra 租户里。 |
DATABASE FEDERATED CLIENT IDENTITY |
存储账户属于另一个租户,通过联邦身份凭证(FIC)访问。 |
Note
作为预览版功能,本文中介绍的技术受制于 Microsoft Azure 预览版补充使用条款。
Prerequisites
- 一个运行在逻辑服务器上的 Azure SQL 数据库。 所有服务层级和所有 Azure 区域都支持此功能。
- 同一订阅中用户分配的托管身份。 背景请参见 Microsoft Entra for Azure SQL 中的 Managed identities。
- 在目标存储账户上分配角色的权限,如 所有者 或 用户访问管理员。
- 一个用于存放你想查询的文件的 Azure Blob 存储 或 ADLS Gen2 账户。
Important
数据库在数据库级别只能分配一个用户分配的托管标识,而逻辑服务器则可以有多个。 分配标识前,请按数据库规划好该标识。
如果数据库在 数据库层面使用客户管理的密钥,它已经拥有数据库级别的身份,对于跨租户密钥,则有联邦客户端ID。 这个功能使用了同样的两个设置。 授予现有身份或应用存储访问权限,而不是分配新的身份或应用。 如果你分配了不同的身份或应用,首先要让它访问加密密钥。 否则,更新可能失败,或者数据库可能失去对密钥的访问权限。
选择同租户或跨租户
两个教程都会创建数据库范围的凭证并查询外部数据。 二者的区别在于标识访问存储帐户的方式。
- 如果数据库和存储账户属于同一租户,请遵循“ 在同一租户中使用数据库级别身份”。
- 如果存储账户属于不同的租户,请遵循“ 跨租户使用联邦客户端身份”。
在同一租户中使用数据库级别的身份
步骤 1:创建用户分配的托管标识
创建身份,并记录其 资源ID 和 对象(主体)ID。 你需要资源 ID 才能将该标识分配给数据库。 你只需要对象(主)ID用于跨租户演练,其中它用于标识联邦身份凭证的主体。
az identity create \
--name <identity-name> \
--resource-group <resource-group> \
--location <region>
有关其他方法,请参见 “管理用户分配的托管标识”。
步骤2:将身份分配给数据库
把UAMI分配给 数据库,而不是逻辑服务器。 该任务使用与采用客户管理密钥的数据库级透明数据加密(TDE)相同的机制,详见 数据库级客户管理密钥。 完整的分配方法集,请参阅获取或设置数据库的托管标识。
要在 Azure 门户中分配标识:
- 进入你的SQL数据库。
- 在“安全性”下,选择“标识”。
- 在 User-Assigned 托管身份下,选择 添加。
- 选择你创建的身份,然后选择 添加。
- 选择“保存”。
要使用 Azure CLI 分配该标识,请使用 az sql db update:
az sql db update \
--resource-group <resource-group> \
--server <server-name> \
--name <database-name> \
--assign-identity \
--user-assigned-identity-id <identity-resource-id>
若要通过 PowerShell 分配该标识,请使用 Set-AzSqlDatabase:
Set-AzSqlDatabase -ResourceGroupName <ResourceGroupName> -ServerName <ServerName> -DatabaseName <DatabaseName> -AssignIdentity -UserAssignedIdentityId <UserAssignedIdentityId>
身份 资源ID 看起来像 /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identity-name>。 在 Azure 门户中的托管身份的属性下找到它。
步骤3:授予身份对存储的访问权限
赋予托管身份对存储账户的读取权限:
- 转到存储帐户。
- 选择“访问控制”(IAM)。
- 选择“添加”>“添加角色分配”。
- 选择 存储 Blob 数据读取者角色,然后选择 下一步。
- 在 分配访问权限给 中,选择 托管标识。
- 选择选择成员,选中你的用户分配托管标识,然后选择选择。
- 选择审核 + 分配。
对于ADLS Gen2的更细粒度访问,可以在特定目录上设置访问控制列表(ACL),而不是在账户级别分配角色。 欲了解更多信息,请参见 Azure Data Lake Storage 中的访问控制列表。
步骤4:创建数据库范围的凭据
连接到你的 用户数据库,而不是 master,并创建凭证:
CREATE DATABASE SCOPED CREDENTIAL MyDBIdentityCred
WITH IDENTITY = 'DATABASE MANAGED IDENTITY';
该凭据无需机密,也无需数据库主密钥。 该引擎在查询时解析分配给数据库的标识。
服务器级别的对应项使用不同的标识值。 比较:
-- Server-level identity: every database on the logical server shares this access
CREATE DATABASE SCOPED CREDENTIAL MyServerIdentityCred
WITH IDENTITY = 'MANAGED IDENTITY';
-- Database-level identity: only this database has this access
CREATE DATABASE SCOPED CREDENTIAL MyDBIdentityCred
WITH IDENTITY = 'DATABASE MANAGED IDENTITY';
完整语法请参见 CREATE DATABASE SCOPED CREDENTIAL。
步骤5:创建外部数据源
创建一个指向你的容器的外部数据源,并附加凭证。 使用与你存储类型相匹配的前缀:
| 存储类型 | 位置前缀 |
|---|---|
| Azure Blob 存储 | abs:// |
| ADLS Gen2 | adls:// |
CREATE EXTERNAL DATA SOURCE MyExternalStorage
WITH (
LOCATION = 'abs://<container>@<storage-account>.blob.core.windows.net',
CREDENTIAL = MyDBIdentityCred
);
步骤6:查询数据
用 ad hoc OPENROWSET查询文件:
SELECT TOP 100 *
FROM OPENROWSET(
BULK 'sales/2026/*.parquet',
DATA_SOURCE = 'MyExternalStorage',
FORMAT = 'parquet'
) AS externalData;
或者定义一个外部表用于重复查询:
CREATE EXTERNAL FILE FORMAT ParquetFormat
WITH (FORMAT_TYPE = PARQUET);
CREATE EXTERNAL TABLE dbo.Sales
(
OrderId int,
OrderDate date,
Amount decimal(10, 2)
)
WITH (
LOCATION = 'sales/2026/',
DATA_SOURCE = MyExternalStorage,
FILE_FORMAT = ParquetFormat
);
SELECT TOP 100 * FROM dbo.Sales;
跨租户使用联邦客户端身份
当你的数据库在一个租户里,存储账户在另一个租户时,使用这条路径。 多租户应用程序注册承载双方之间的信任关系:数据库的 UAMI 是该应用程序上联合标识凭据的主体,存储租户向该应用程序的服务主体授予数据访问权限。
该模式与透明数据加密的跨租户客户管理的密钥相匹配,因此如果你已使用该功能,会对这套设置比较熟悉。
步骤1:注册多租户应用
在承载数据库的租户中,在 Microsoft Entra ID 里注册一个多租户应用程序,并记下它的应用程序(客户端)ID。
有关详细信息,请参阅将应用程序注册到 Microsoft 标识平台。
步骤2:添加联邦身份凭证
给该应用程序添加一个联邦身份凭据,使其信任数据库的用户分配托管身份。 应用程序和托管身份必须属于同一个 Microsoft Entra 租户。
- 在应用注册中,依次选择证书&机密>联合凭据>添加凭据。
- 对于 联合凭证场景,选择 托管身份。
- 选择你在同租户演练的步骤 1中创建的托管身份。
- 验证自动填充的颁发者是否标识你的租户。 对于Azure公有云,颁发者是
https://login.microsoftonline.com/<tenant-id>/v2.0。 - 确保 Audience 是
api://AzureADTokenExchange,即 Azure 公有云的值。 - 输入一个唯一的凭证名称,然后保存。
凭据的主题是被管理身份的 对象(主体)ID,而不是其客户端 ID。 如果你手动配置凭据,请原样复制对象(主体)ID,因为主题区分大小写。 Microsoft Entra ID 在保存凭证时接受错误的发行者、主体或受众值,但令牌交换随后失败。
欲了解更多信息,请参见“配置应用以信任托管身份”。
步骤3:同意应用程序并授予存储访问权
在持有存储账户的租户中:
- 管理员对该多租户应用程序进行许可,由此在该租户中创建一个服务主体。
- 将 存储 Blob 数据读取器 角色分配给该服务主体,并在该存储帐户上进行分配。 按照 步骤 3:授予身份对存储的访问权限 操作,但对于 分配访问权限给,选择 用户、组或服务主体,然后选择应用程序的服务主体。
步骤4:在数据库中设置联邦客户端ID
在持有数据库的租户中,将用户分配的管理身份分配给数据库,并将步骤1中的应用程序(客户端)ID设置为 联邦客户端ID:
- 进入你的SQL数据库。
- 在“安全性”下,选择“标识”。
- 在 User-Assigned 托管身份下,检查同一租户流程的 步骤 1 中的身份是否被列出。 如果未添加,请选择添加,选中该标识,再选择添加。
- 在 联邦客户端身份下,选择应用,然后选择 保存。
用Azure CLI设置:
az sql db update \
--resource-group <resource-group> \
--server <server-name> \
--name <database-name> \
--assign-identity \
--user-assigned-identity-id <identity-resource-id> \
--federated-client-id <application-client-id>
用PowerShell设置:
Set-AzSqlDatabase -ResourceGroupName <ResourceGroupName> -ServerName <ServerName> -DatabaseName <DatabaseName> -AssignIdentity -UserAssignedIdentityId <UserAssignedIdentityId> -FederatedClientId <ApplicationClientId>
步骤5:创建凭据和查询
CREATE DATABASE SCOPED CREDENTIAL MyCrossTenantCred
WITH IDENTITY = 'DATABASE FEDERATED CLIENT IDENTITY';
CREATE EXTERNAL DATA SOURCE PartnerStorage
WITH (
LOCATION = 'adls://<container>@<storage-account>.dfs.core.windows.net',
CREDENTIAL = MyCrossTenantCred
);
然后创建外部表,或按照步骤 6:查询数据中的说明,针对 PartnerStorage 直接运行 OPENROWSET。
比较服务器级标识和数据库级标识
| 特性 | 服务器级托管身份 | 数据库级托管身份 |
|---|---|---|
| 标识范围 | 逻辑服务器 | 单一数据库 |
| 凭证语法 | IDENTITY = 'MANAGED IDENTITY' |
IDENTITY = 'DATABASE MANAGED IDENTITY' |
| 跨租户存储访问 | 不支持。 改用共享访问签名 | 在数据库上设置的联合客户端 ID,用于与 IDENTITY = 'DATABASE FEDERATED CLIENT IDENTITY' 一起使用 |
| 存储RBAC粒度 | 服务器上的每个数据库都有一个标识 | 每个数据库一个标识 |
| 暴露范围 | 服务器上的所有数据库都共享相同的访问设置 | 仅限于一个数据库 |
| 标识类型 | 系统分配的或用户分配的 | 仅限用户指定 |
| 需要数据库主密钥 | No | No |
这两种凭证可以共存于同一逻辑服务器及其数据库中。 选择最适合您安全需求的凭据。
地理复制与故障切换
你将标识分配给数据库,因此每个副本都带有自身的分配项。 在故障转移前,请按照主数据库的相同方式配置异地辅助数据库:
- 将主数据库使用的相同用户分配的托管标识分配给次级数据库。
- 授予该身份与步骤 3:授予该身份对存储的访问权限中所述相同的存储访问权限。
- 对于跨租户访问,在二级数据库上设置相同的 联邦客户端身份 。
当你这样配置两个副本时,使用数据库范围凭证的查询在故障切换后依然能正常工作。 该要求与数据库级客户管理的密钥一致,这类密钥同样需要在每个副本上预先配置好标识。
Limitations
- 仅限 Azure SQL 数据库。 Azure SQL 托管实例、SQL Server 和 Azure Synapse Analytics 不支持这些凭证身份。
- 仅限出站认证。 该功能不改变用户和应用程序向数据库进行身份验证的方式。
- 在
master数据库中不受支持。 在用户数据库中创建凭证。 - 仅限用户分配的托管身份。 系统分配的托管身份其作用域限定为逻辑服务器,因此不能作为数据库级身份。
- 每个数据库只有一个用户分配的托管身份。
- 此预览版仅支持数据虚拟化:
CREATE EXTERNAL TABLE和OPENROWSET搭配DATA_SOURCE使用。 其他出站功能,如sp_invoke_external_rest_endpoint,不在作用范围内。
Troubleshoot
创建数据库范围的凭证并不能确认数据库身份是否能获得令牌或访问存储。 错误在你创建外部数据源或运行使用凭证的查询时出现。
数据库身份未配置(错误15858)
你可以先使用 IDENTITY = 'DATABASE MANAGED IDENTITY' 创建凭据,再向数据库分配用户分配的托管标识。 如果查询使用了该凭证,而数据库没有可用于获取令牌的标识,查询将失败,并出现 15858 错误:
Cannot obtain a Microsoft Entra ID token to access storage. Error message: 'Azure SQL Server or Database identity is not configured. Please follow the steps in "Assign a Microsoft Entra managed identity to your Azure SQL" (https://aka.ms/SQLDBMSI)'.
按照 步骤2的描述,为数据库分配一个用户分配的管理身份,赋予其存储账户访问权限,然后重新尝试查询。 仅为逻辑服务器分配身份并不会配置数据库级身份。 如果数据库分配已生效且错误依旧,请联系 Microsoft 支持部门 调查数据库身份配置问题。
Note
追踪标志4675以及使用托管身份备份和恢复到URL中的删除并重建步骤,适用于Azure虚拟机上的SQL Server。 它们不适用于Azure SQL 数据库中的数据库级托管身份。
无法找到或引用凭证(错误46516)
当你创建外部数据源时,Azure SQL 数据库会检查该凭证是否存在于当前数据库中,并且你是否有权限引用它。 如果任一检查都失败,会出现错误46516:
The specified credential cannot be found or the user does not have permission to perform this action.
在包含外部数据源的数据库中创建凭据,检查凭证名称,并确保你有权限引用该凭据。
令牌获取失败(错误15858)
当数据库无法获得Microsoft Entra令牌,且令牌提供者返回理由时,错误15858包含了该理由:
Cannot obtain a Microsoft Entra ID token to access storage. Error message: '<details>'.
使用嵌套错误消息来找出令牌请求失败的原因。 对于跨租户访问,请按照配置应用程序以信任托管标识中的说明,检查应用程序、存储租户中的管理员同意以及联合标识凭据。
读取外部数据时,该标识还需要被授予存储数据角色。 对于同一租户访问,在容器或存储账户上将 Storage Blob Data Reader 授予数据库的用户分配托管身份。 对于跨租户访问,将访问权限授予该应用程序在存储租户中的服务主体。 有关详细信息,请参阅分配用于访问 Blob 数据的 Azure 角色。
文件不存在或无法访问(错误4860)
当文件缺失或无法读取时,会出现错误4860:
Cannot bulk load. The file "<path>" does not exist or you don't have file access rights. See https://go.microsoft.com/fwlink/?LinkId=2374938 for more information.
检查文件是否存在于配置位置。 然后检查请求所用标识是否可以访问该资源,可通过存储数据角色,或者对于 ADLS Gen2,通过路径上的访问控制列表 (ACL) 进行验证。
网络访问被阻断(错误42121和16539)
当逻辑服务器关联到不允许出站流量流向存储账户的网络安全边界时,会出现错误42121:
The operation could not be completed because attempts to connect were denied by the configured Network Security Perimeter.
在边界配置文件中添加存储账户主机名的出站访问规则,或者将存储账户关联到相同的边界。 欲了解更多信息,请参见 Azure SQL 数据库 的网络安全边界。
当逻辑服务器的出站网络被限制,且存储账户不在服务器的出站防火墙规则中时,会出现错误16539:
Operation failed since the external data source '<external-data-source>' has underlying storage account that is not in the list of Outbound Firewall Rules on the server. Please add this storage account to the list of Outbound Firewall Rules on your server and retry the operation.
为外部数据源位置对应的准确存储主机名添加出站防火墙规则。 欲了解更多信息,请参见Azure SQL 数据库 和 Azure Synapse Analytics 的出站防火墙规则。
跨租户配置缺失或错误(错误16561和16562)
跨租户查询可能因以下任一错误或错误 4860而失败:
External table '<table-name>' is not accessible because content of directory cannot be listed.
External table '<table-name>' is not accessible because location does not exist or it is used by another process.
这些错误表示查询无法访问文件。 身份可能没有所需的存储角色,网络访问可能被阻断,存储位置可能无法解析,或者令牌可能是属于错误的租户。 要修复此问题,请执行以下操作:
- 赋予相应的存储数据角色。
- 允许网络访问存储账户。
- 将容器包含在外部数据源位置。
- 使用
DATABASE FEDERATED CLIENT IDENTITY,并按照步骤4中的说明,在数据库上设置联邦客户端 ID。 - 确认联邦身份凭证的主体与托管身份的对象(主体)ID完全匹配。
故障切换后查询失败
如果故障切换后查询因令牌或授权错误而失败,新的主节点可能没有原主节点所用的用户分配的托管标识。 或者该标识可能在该存储帐户上没有角色分配。 为两个副本分配相同的身份并赋予其存储访问权限,如 地理复制和故障切换中所述。
常见问题解答
服务器级和数据库级凭证能否共存于同一服务器上?
是的,在同一个逻辑服务器和同一个数据库里。 每个凭据的 IDENTITY 值决定查询使用的身份:MANAGED IDENTITY 使用服务器身份,DATABASE MANAGED IDENTITY 使用数据库的身份。
我可以使用系统分配的托管身份吗?
No. 系统分配的托管身份属于逻辑服务器,所以你不能把它范围限定到一个数据库。 使用用户分配的托管标识。
哪些服务层级和地区支持这个预览?
所有Azure SQL 数据库服务层级,涵盖所有Azure区域。
我需要数据库主密钥吗?
No.
DATABASE MANAGED IDENTITY 和 DATABASE FEDERATED CLIENT IDENTITY 二者均不使用机密,因此无需主密钥。
这个功能能和 sp_invoke_external_rest_endpoint 一起使用吗?
不在此预览中。 预览内容涵盖了数据虚拟化。