联合标识凭据的重要注意事项和限制
本文介绍 Microsoft Entra 应用和用户分配的托管标识中有关联合标识凭据的重要注意事项、限制和局限性。
有关联合标识凭据实现的方案的详细信息，请参阅工作负载标识联合概述。
一般联合标识凭据注意事项
适用于：应用程序和用户分配的托管标识
有权创建应用注册和添加机密或证书的任何人都可以向应用添加联合标识凭据。 如果 Microsoft Entra 管理中心的“用户”->“用户设置”边栏选项卡中的“用户可以注册应用程序”开关设置为“否”，你将无法创建应用注册或配置联合标识凭据。 查找可代表你配置联合标识凭据的管理员，即某个充当应用程序管理员或应用程序所有者角色的人员。
联合标识凭据不会占用 Microsoft Entra 租户服务主体对象配额。
最多可以向应用程序或用户分配的托管标识添加 20 个联合标识凭据。
配置联合标识凭据时，需要提供几条重要信息：
issuer 和 subject 是建立信任关系所需的关键信息 。
issuer和subject的组合在应用中必须唯一。 当外部软件工作负载请求 Microsoft 标识平台来交换访问令牌的外部令牌时，将针对外部令牌中提供的issuer和subject声明来检查联合标识凭据的 issuer 和 subject 值 。 如果该验证检查通过，Microsoft 标识平台会向外部软件工作负载发出访问令牌。issuer 是外部身份提供商的 URL，必须与要交换的外部令牌的
issuer声明相匹配。 必需。 如果issuer声明具有值中的前导或尾随空格，则会阻止令牌交换。 此字段的字符限制为 600 个字符。subject 是外部标识提供者的标识符，必须与要交换的外部令牌的
sub(subject) 声明相匹配。 subject 没有固定格式，因为每个 IdP 都使用自己的格式，格式有时是 GUID，有时是冒号分隔的标识符，有时是任意字符串。 此字段的字符限制为 600 个字符。重要
“subject”设置值必须与 GitHub 工作流配置中的配置完全匹配。 否则，Microsoft 标识平台将查看传入的外部令牌，并拒绝交换访问令牌。 你不会收到错误消息，交换失败且没有错误。
重要
如果在 subject 设置中意外添加了不正确的外部工作负载信息，则已成功创建联合标识凭据，且未出现错误。 在令牌交换失败之前，此错误不会变得明显。
audiences 列出了可出现在外部令牌中的受众。 必需。 必须添加一个受众值，该值限制为 600 个字符。 建议的值为“api://AzureADTokenExchange”。 它表示 Microsoft 标识平台必须接受传入令牌中的
aud声明。name 是联合标识凭据的唯一标识符。 必需。 此字段的字符限制为 3-120 个字符，并且必须对 URL 友好。 支持字母数字、短划线或下划线字符，第一个字符必须是字母数字字符。 它在创建后就不可变。
description 是用户提供的联合标识凭据的说明。 可选。 Microsoft Entra ID 不会验证或检查说明。 此字段的上限为 600 个字符。
任何联合标识凭据属性值都不支持通配符。
支持的签名算法和颁发者
适用于：应用程序和用户分配的托管标识
只有提供以 RS256 算法签名的令牌的颁发者才支持使用工作负载标识联合来交换令牌。 也许可以交换以其他算法签名的令牌，但此功能尚未经过测试。
不支持 Microsoft Entra 颁发者
适用于：应用程序和用户分配的托管标识
不支持在来自相同或不同租户的两个 Microsoft Entra 标识之间创建联合。 创建联合标识凭据时，不支持使用以下值配置颁发者（外部标识提供者的 URL）：
- *.login.partner.microsoftonline.cn
- *.login.chinacloudapi.cn
- *.login.microsoft.com
- *.sts.chinacloudapi.cn
虽然可以使用 Microsoft Entra 颁发者创建联合标识凭据，但尝试将其用于授权会失败并出现错误“AADSTS700222: AAD-issued tokens may not be used for federated identity flows”。
传播联合凭据更改的时间
适用于：应用程序和用户分配的托管标识
在完成初始配置后，在整个区域中传播联合标识凭据需要一定的时间。 在配置联合标识凭据几分钟后发出的令牌请求可能会失败，因为缓存在目录中填充了旧数据。 在此时段内，授权请求可能会失败并出现错误消息：AADSTS70021: No matching federated identity record found for presented assertion.
为避免此问题，请在添加联合标识凭据后稍等片刻，然后再请求令牌，以确保在授权服务的所有节点之间完成复制。 我们还建议为令牌请求添加重试逻辑。 即使在成功获取令牌后，也应该对每个请求进行重试。 最终，在数据完全复制后，失败百分比将会下降。
不支持并发更新（用户分配的托管标识）
适用于：用户分配的托管标识
在同一用户分配的托管标识下创建多个联合标识凭据会并发触发并发检测逻辑，导致请求失败并出现 409-conflict HTTP 状态代码。
Terraform Provider for Azure（资源管理器）3.40.0 版引入了一个更新，它按顺序创建而不是同时创建多个联合标识凭据。 创建多个联合标识时，低于 3.40.0 的版本可能会导致管道故障。 建议使用 Terraform Provider for Azure（资源管理器）v3.40.0 或更高版本，以便按顺序创建多个联合标识凭据。
使用自动化或 Azure 资源管理器模板（ARM 模板）在同一父标识下创建联合标识凭据时，请按顺序创建联合凭据。 联合标识凭据可在不同托管标识下并行创建，且没有任何限制。
如果在循环中预配联合标识凭据，则可通过设置 "mode": "serial" 来串行预配它们。
还可以使用 dependsOn 属性按顺序预配多个新的联合标识凭据。 以下 Azure 资源管理器模板（ARM 模板）示例使用 dependsOn 属性在用户分配的托管标识上按顺序创建三个新的联合标识凭据：
{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"parameters": {
"userAssignedIdentities_parent_uami_name": {
"defaultValue": "parent_uami",
"type": "String"
}
},
"variables": {},
"resources": [
{
"type": "Microsoft.ManagedIdentity/userAssignedIdentities",
"apiVersion": "2022-01-31-preview",
"name": "[parameters('userAssignedIdentities_parent_uami_name')]",
"location": "ChinaNorth"
},
{
"type": "Microsoft.ManagedIdentity/userAssignedIdentities/federatedIdentityCredentials",
"apiVersion": "2022-01-31-preview",
"name": "[concat(parameters('userAssignedIdentities_parent_uami_name'), '/fic01')]",
"dependsOn": [
"[resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', parameters('userAssignedIdentities_parent_uami_name'))]"
],
"properties": {
"issuer": "https://kubernetes-oauth.azure.com",
"subject": "fic01",
"audiences": [
"api://AzureADTokenExchange"
]
}
},
{
"type": "Microsoft.ManagedIdentity/userAssignedIdentities/federatedIdentityCredentials",
"apiVersion": "2022-01-31-preview",
"name": "[concat(parameters('userAssignedIdentities_parent_uami_name'), '/fic02')]",
"dependsOn": [
"[resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', parameters('userAssignedIdentities_parent_uami_name'))]",
"[resourceId('Microsoft.ManagedIdentity/userAssignedIdentities/federatedIdentityCredentials', parameters('userAssignedIdentities_parent_uami_name'), 'fic01')]"
],
"properties": {
"issuer": "https://kubernetes-oauth.azure.com",
"subject": "fic02",
"audiences": [
"api://AzureADTokenExchange"
]
}
},
{
"type": "Microsoft.ManagedIdentity/userAssignedIdentities/federatedIdentityCredentials",
"apiVersion": "2022-01-31-preview",
"name": "[concat(parameters('userAssignedIdentities_parent_uami_name'), '/fic03')]",
"dependsOn": [
"[resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', parameters('userAssignedIdentities_parent_uami_name'))]",
"[resourceId('Microsoft.ManagedIdentity/userAssignedIdentities/federatedIdentityCredentials', parameters('userAssignedIdentities_parent_uami_name'), 'fic02')]"
],
"properties": {
"issuer": "https://kubernetes-oauth.azure.com",
"subject": "fic03",
"audiences": [
"api://AzureADTokenExchange"
]
}
}
]
}
Azure Policy
适用于：应用程序和用户分配的托管标识
可以使用一个拒绝 Azure Policy，如以下 ARM 模板示例所示：
{
"policyRule": {
"if": {
"field": "type",
"equals": "Microsoft.ManagedIdentity/userAssignedIdentities/federatedIdentityCredentials"
},
"then": {
"effect": "deny"
}
}
}
限制
适用于：用户分配的托管标识
下表描述了对用户分配的托管标识 REST API 发出的请求的限制。 如果超过限制，会收到 HTTP 429 错误。
| Operation | 每个 Microsoft Entra 租户的每秒请求数 | 每个订阅的每秒请求数 | 每个资源的每秒请求数 |
|---|---|---|---|
| 创建或更新请求 | 10 | 2 | 0.25 |
| 获取请求 | 30 | 10 | 0.5 |
| 按资源组列出或按订阅列出请求 | 15 | 5 | 0.25 |
| 删除请求 | 10 | 2 | 0.25 |
错误
适用于：应用程序和用户分配的托管标识
创建、更新、获取、列出或删除联合标识凭据时，可能会返回以下错误代码。
| HTTP 代码 | 错误消息 | 说明 |
|---|---|---|
| 405 | 请求格式不符合预期：未启用对联合标识凭据的支持。 | 未在此区域中启用联合标识凭据。 请参阅“当前支持的区域”。 |
| 400 | 联合标识凭据必须正好有一个受众。 | 目前，联合标识凭据支持单个受众“api://AzureADTokenExchange”。 |
| 400 | HTTP 正文中的联合标识凭据包含空属性 | 所有联合标识凭据属性都是必需的。 |
| 400 | 联合标识凭据名称“{ficName}”无效。 | 字母数字、短划线、下划线，不超过 3-120 个符号。 第一个符号为字母数字。 |
| 404 | 父用户分配的标识不存在。 | 检查联合标识凭据资源路径中的用户分配的标识名称。 |
| 400 | 此托管标识已存在颁发者和使用者组合。 | 这是一个约束。 列出与用户分配的标识关联的所有联合标识凭据，以查找现有的联合标识凭据。 |
| 409 | Conflict | 对同一用户分配的标识下的联合标识凭据资源发出的并发写入请求已被拒绝。 |