配置用户分配的托管标识以信任外部标识提供者
本文介绍如何在 Microsoft Entra ID 中管理用户分配的托管标识的联合标识凭据。 联合标识凭据在用户分配的托管标识与外部标识提供者 (IdP) 之间创建信任关系。 不支持在系统分配的托管标识上配置联合标识凭据。
将用户分配的托管标识配置为信任外部 IdP 后,配置外部软件工作负荷以将来自外部 IdP 的令牌交换为来自 Microsoft 标识平台的访问令牌。 外部工作负荷使用访问令牌来访问 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 个字符。
任何联合标识凭据属性值都不支持通配符。
若要详细了解受支持的区域、传播联合凭据更新的时间、支持的颁发者等,请阅读联合标识凭据的重要注意事项和限制。
先决条件
- 如果不熟悉 Azure 资源的托管标识,请查阅概述部分。 请务必了解系统分配的托管标识与用户分配的托管标识之间的差异。
- 如果还没有 Azure 帐户,请先注册试用帐户,然后再继续。
- 获取外部 IdP 和软件工作负荷的信息,以下步骤中需要这些信息。
- 若要要创建用户分配的托管标识并配置联合标识凭据,你的帐户需要参与者或所有者角色分配。
- 创建用户分配的托管标识
- 找到用户分配的托管标识的名称,以便在后续步骤中使用。
在用户分配的托管标识上配置联合标识凭据
在 Microsoft Entra 管理中心中,导航到你创建的用户分配的托管标识。 在左侧导航栏中的“设置”下,选择“联合凭据”,然后选择“添加凭据”。
在“联合凭据场景”下拉列表框中,选择你的场景。
部署 Azure 资源的 GitHub Actions
要为 GitHub 操作添加联合身份,请执行以下步骤:
对于“实体类型”,请选择“环境”、“分支”、“拉取请求”或“标记”,并指定值。 值必须与 GitHub 工作流中的配置完全匹配。 有关详细信息,请阅读示例。
为联合凭据添加“名称”。
“颁发者”、“受众”和“主题标识符”字段会根据你输入的值自动填充。
选择“添加”以配置联合凭据。
将你的 Microsoft Entra 托管标识中的以下值用于你的 GitHub 工作流:
AZURE_CLIENT_ID
,托管标识客户端 IDAZURE_SUBSCRIPTION_ID
,订阅 ID。下面的屏幕截图演示了如何复制托管标识 ID 和订阅 ID。
AZURE_TENANT_ID
目录(租户)ID。 了解如何查找 Microsoft Entra 租户 ID。
实体类型示例
分支示例
对于主分支上的推送或拉取请求事件触发的工作流,请执行以下操作:
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
将“实体类型”指定为“分支”,将“GitHub 分支名称”指定为“main”。
环境示例
对于绑定到名为“production”的环境的“作业”,请执行以下操作:
on:
push:
branches:
- main
jobs:
deployment:
runs-on: ubuntu-latest
environment: production
steps:
- name: deploy
# ...deployment-specific steps
将“实体类型”指定为“环境”,将“GitHub 环境名称”指定为“production”。
标记示例
例如,对于目标为标记“v2”的推送触发的工作流,请执行以下操作:
on:
push:
# Sequence of patterns matched against refs/heads
branches:
- main
- 'mona/octocat'
- 'releases/**'
# Sequence of patterns matched against refs/tags
tags:
- v2
- v1.*
将“实体类型”指定为“标记”,将“GitHub 标记名称”指定为“v2”。
拉取请求示例
对于拉取请求事件触发的工作流,请将“实体类型”指定为“拉取请求”
访问 Azure 资源的 Kubernetes
填写“群集证书颁发者 URL”、“命名空间”、“服务帐户名称”和“名称”字段:
- “群集证书颁发者 URL”是托管群集的 OIDC 证书颁发者 URL 或自托管群集的 OIDC 证书颁发者 URL。
- “服务帐户名称”是 Kubernetes 服务帐户的名称,它为 Pod 中运行的进程提供标识。
- “命名空间”是服务帐户命名空间。
- “Name”是联合凭据的名称,以后将无法更改。
选择“添加”以配置联合凭据。
其他
从下拉菜单中选择“其他证书颁发者”场景。
指定以下字段:
- Name 是联合凭据的名称,以后将无法更改。
- 主题标识符:必须与外部标识提供者颁发的令牌中的
sub
声明匹配。 - 证书颁发者:必须与外部标识提供者颁发的令牌中的
iss
声明匹配。 符合 OIDC 发现规范的 URL。Microsoft Entra ID 使用此颁发者 URL 提取验证令牌所需的密钥。
选择“添加”以配置联合凭据。
在用户分配的托管标识上列出联合标识凭据
在 Microsoft Entra 管理中心中,导航到你创建的用户分配的托管标识。 在左侧导航栏中的“设置”下,选择“联合凭据”。
在该用户分配的托管标识上配置的联合标识凭据已列出。
从用户分配的托管标识中删除联合标识凭据
在 Microsoft Entra 管理中心中,导航到你创建的用户分配的托管标识。 在左侧导航栏中的“设置”下,选择“联合凭据”。
在该用户分配的托管标识上配置的联合标识凭据已列出。
若要删除特定联合标识凭据,请选择凭据的“删除”图标。
先决条件
- 如果不熟悉 Azure 资源的托管标识,请查阅概述部分。 请务必了解系统分配的托管标识与用户分配的托管标识之间的差异。
- 如果还没有 Azure 帐户,请先注册试用帐户,然后再继续。
- 获取外部 IdP 和软件工作负荷的信息,以下步骤中需要这些信息。
- 若要要创建用户分配的托管标识并配置联合标识凭据,你的帐户需要参与者或所有者角色分配。
- 创建用户分配的托管标识
- 找到用户分配的托管标识的名称,以便在后续步骤中使用。
如需在本地运行 CLI 参考命令,请安装 Azure CLI。 如果在 Windows 或 macOS 上运行,请考虑在 Docker 容器中运行 Azure CLI。 有关详细信息,请参阅如何在 Docker 容器中运行 Azure CLI。
如果使用的是本地安装,请使用 az login 命令登录到 Azure CLI。 若要完成身份验证过程,请遵循终端中显示的步骤。 有关其他登录选项,请参阅使用 Azure CLI 登录。
出现提示时,请在首次使用时安装 Azure CLI 扩展。 有关扩展详细信息,请参阅使用 Azure CLI 的扩展。
运行 az version 以查找安装的版本和依赖库。 若要升级到最新版本,请运行 az upgrade。
在用户分配的托管标识上配置联合标识凭据
运行 az identity federated-credential create 命令,在用户分配的托管标识(由相应名称指定)上创建新的联合标识凭据。 指定 name、issuer、subject 和其他参数。
az login
# set variables
location="chinanorth"
subscription="{subscription-id}"
rg="fic-test-rg"
# user assigned identity name
uaId="fic-test-ua"
# federated identity credential name
ficId="fic-test-fic-name"
# create prerequisites if required.
# otherwise make sure that existing resources names are set in variables above
az account set --subscription $subscription
az group create --location $location --name $rg
az identity create --name $uaId --resource-group $rg --location $location --subscription $subscription
# Create/update a federated identity credential
az identity federated-credential create --name $ficId --identity-name $uaId --resource-group $rg --issuer 'https://aks.azure.com/issuerGUID' --subject 'system:serviceaccount:ns:svcaccount' --audiences 'api://AzureADTokenExchange'
在用户分配的托管标识上列出联合标识凭据
运行 az identity federated-credential list 命令,读取在用户分配的托管标识上配置的所有联合标识凭据:
az login
# Set variables
rg="fic-test-rg"
# User assigned identity name
uaId="fic-test-ua"
# Read all federated identity credentials assigned to the user-assigned managed identity
az identity federated-credential list --identity-name $uaId --resource-group $rg
在用户分配的托管标识上获取联合标识凭据
运行 az identity federated-credential show 命令,显示联合标识凭据(按 ID):
az login
# Set variables
rg="fic-test-rg"
# User assigned identity name
uaId="fic-test-ua"
# Federated identity credential name
ficId="fic-test-fic-name"
# Show the federated identity credential
az identity federated-credential show --name $ficId --identity-name $uaId --resource-group $rg
从用户分配的托管标识中删除联合标识凭据
运行 az identity federated-credential delete 命令,删除现有用户分配的标识下的联合标识凭据。
az login
# Set variables
# in Linux shell remove $ from set variable statement
$rg="fic-test-rg"
# User assigned identity name
$uaId="fic-test-ua"
# Federated identity credential name
$ficId="fic-test-fic-name"
az identity federated-credential delete --name $ficId --identity-name $uaId --resource-group $rg
先决条件
- 如果不熟悉 Azure 资源的托管标识,请查阅概述部分。 请务必了解系统分配的托管标识与用户分配的托管标识之间的差异。
- 如果还没有 Azure 帐户,请先注册试用帐户,然后再继续。
- 获取外部 IdP 和软件工作负荷的信息,以下步骤中需要这些信息。
- 若要要创建用户分配的托管标识并配置联合标识凭据,你的帐户需要参与者或所有者角色分配。
- 若要运行示例脚本,可使用 Azure PowerShell 在本地运行脚本,如下一部分所述。
- 创建用户分配的托管标识
- 找到用户分配的托管标识的名称,以便在后续步骤中使用。
在本地配置 Azure PowerShell
若要在本文情景中本地使用 Azure PowerShell:
安装最新版本的 Azure PowerShell(如果尚未安装)。
登录 Azure。
Connect-AzAccount -Environment AzureChinaCloud
-
Install-Module -Name PowerShellGet -AllowPrerelease
在下一步运行此命令后,可能需要
Exit
退出当前 PowerShell 会话。 安装
Az.ManagedServiceIdentity
模块,以执行本文中用户分配的托管标识操作。Install-Module -Name Az.ManagedServiceIdentity
在用户分配的托管标识上配置联合标识凭据
运行 New-AzFederatedIdentityCredentials 命令,在用户分配的托管标识(由相应名称指定)上创建新的联合标识凭据。 指定 name、issuer、subject 和其他参数。
New-AzFederatedIdentityCredentials -ResourceGroupName azure-rg-test -IdentityName uai-pwsh01 `
-Name fic-pwsh01 -Issuer "https://kubernetes-oauth.azure.com" -Subject "system:serviceaccount:ns:svcaccount"
在用户分配的托管标识上列出联合标识凭据
运行 Get-AzFederatedIdentityCredentials 命令,读取在用户分配的托管标识上配置的所有联合标识凭据:
Get-AzFederatedIdentityCredentials -ResourceGroupName azure-rg-test -IdentityName uai-pwsh01
在用户分配的托管标识上获取联合标识凭据
运行 Get-AzFederatedIdentityCredentials 命令,显示联合标识凭据(按名称):
Get-AzFederatedIdentityCredentials -ResourceGroupName azure-rg-test -IdentityName uai-pwsh01 -Name fic-pwsh01
从用户分配的托管标识中删除联合标识凭据
运行 Remove-AzFederatedIdentityCredentials 命令,删除现有用户分配标识下的联合标识凭据。
Remove-AzFederatedIdentityCredentials -ResourceGroupName azure-rg-test -IdentityName uai-pwsh01 -Name fic-pwsh01
先决条件
- 如果不熟悉 Azure 资源的托管标识,请查阅概述部分。 请务必了解系统分配的托管标识与用户分配的托管标识之间的差异。
- 如果还没有 Azure 帐户,请先注册试用帐户,然后再继续。
- 获取外部 IdP 和软件工作负荷的信息,以下步骤中需要这些信息。
- 若要要创建用户分配的托管标识并配置联合标识凭据,你的帐户需要参与者或所有者角色分配。
- 创建用户分配的托管标识
- 找到用户分配的托管标识的名称,以便在后续步骤中使用。
模板创建和编辑
资源管理器模板有助于部署由 Azure 资源组定义的新资源或已修改资源。 有多种可用于执行模板编辑和部署的方法(包括本地方法和基于门户的方法)。 方法:
- 使用 Azure 市场中的自定义模板从头开始创建模板,或在现有常见模板或快速启动模板的基础之上操作。
- 通过导出模板从现有资源组派生。 可以从原始部署或部署当前状态导出它们。
- 使用本地 JSON 编辑器(例如 VS Code),然后使用 PowerShell 或 Azure CLI 进行上传和部署。
- 使用 Visual Studio Azure 资源组项目创建和部署模板。
在用户分配的托管标识上配置联合标识凭据
联合标识凭据和父级用户分配的标识可通过以下模板创建或更新。 可以从 Azure 门户中部署 ARM 模板。
所有模板参数都是必需的。
联合标识凭据名称长度限制为 3-120 个字符。 名称必须为字母数字、短划线、下划线。 第一个符号仅为字母数字。
必须向联合标识凭据添加正好 1 名受众。 将在令牌交换期间对该受众进行验证。 使用“api://AzureADTokenExchange”作为默认值。
模板不提供列表、获取和删除操作。 有关这些操作,请参阅 Azure CLI。 默认情况下,所有子级联合标识凭据都并行创建,这会触发并发检测逻辑,并导致部署失败并出现 409 冲突的 HTTP 状态代码。 若要按顺序创建,请使用 dependsOn 属性指定依赖项链。
确保任何类型的自动化都按顺序在同一父标识下创建联合标识凭据。 联合标识凭据可在不同托管标识下并行创建,且没有任何限制。
{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"variables": {},
"parameters": {
"location": {
"type": "string",
"defaultValue": "chinanorth",
"metadata": {
"description": "Location for identities resources. FIC should be enabled in this region."
}
},
"userAssignedIdentityName": {
"type": "string",
"defaultValue": "FIC_UA",
"metadata": {
"description": "Name of the User Assigned identity (parent identity)"
}
},
"federatedIdentityCredential": {
"type": "string",
"defaultValue": "testCredential",
"metadata": {
"description": "Name of the Federated Identity Credential"
}
},
"federatedIdentityCredentialIssuer": {
"type": "string",
"defaultValue": "https://aks.azure.com/issuerGUID",
"metadata": {
"description": "Federated Identity Credential token issuer"
}
},
"federatedIdentityCredentialSubject": {
"type": "string",
"defaultValue": "system:serviceaccount:ns:svcaccount",
"metadata": {
"description": "Federated Identity Credential token subject"
}
},
"federatedIdentityCredentialAudience": {
"type": "string",
"defaultValue": " api://AzureADTokenExchange",
"metadata": {
"description": "Federated Identity Credential audience. Single value is only supported."
}
}
},
"resources": [
{
"type": "Microsoft.ManagedIdentity/userAssignedIdentities",
"apiVersion": "2018-11-30",
"name": "[parameters('userAssignedIdentityName')]",
"location": "[parameters('location')]",
"tags": {
"firstTag": "ficTest"
},
"resources": [
{
"type": "Microsoft.ManagedIdentity/userAssignedIdentities/federatedIdentityCredentials",
"apiVersion": "2022-01-31-PREVIEW",
"name": "[concat(parameters('userAssignedIdentityName'), '/', parameters('federatedIdentityCredential'))]",
"dependsOn": [
"[resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', parameters('userAssignedIdentityName'))]"
],
"properties": {
"issuer": "[parameters('federatedIdentityCredentialIssuer')]",
"subject": "[parameters('federatedIdentityCredentialSubject')]",
"audiences": [
"[parameters('federatedIdentityCredentialAudience')]"
]
}
}
]
}
]
}
先决条件
- 如果不熟悉 Azure 资源的托管标识,请查阅概述部分。 请务必了解系统分配的托管标识与用户分配的托管标识之间的差异。
- 如果还没有 Azure 帐户,请先注册试用帐户,然后再继续。
- 获取外部 IdP 和软件工作负荷的信息,以下步骤中需要这些信息。
- 若要要创建用户分配的托管标识并配置联合标识凭据,你的帐户需要参与者或所有者角色分配。
- 可在本地运行本文中的所有命令:
- 创建用户分配的托管标识
- 找到用户分配的托管标识的名称,以便在后续步骤中使用。
获取持有者访问令牌
如果在本地运行,请通过 Azure CLI 登录到 Azure。
az login
使用 az account get-access-token 获取访问令牌。
az account get-access-token
在用户分配的托管标识上配置联合标识凭据
在用户分配的指定托管标识上创建或更新联合标识凭据。
curl 'https://management.chinacloudapi.cn/subscriptions/<SUBSCRIPTION ID>/resourceGroups/<RESOURCE GROUP>/provider
s/Microsoft.ManagedIdentity/userAssignedIdentities/<USER ASSIGNED IDENTITY NAME>/federatedIdenti
tyCredentials/<FEDERATED IDENTITY CREDENTIAL NAME>?api-version=2022-01-31-preview' -X PUT -d '{"properties": "{ "properties": { "issuer": "<ISSUER>", "subject": "<SUBJECT>", "audiences": [ "api://AzureADTokenExchange" ] }}"}' -H "Content-Type: application/json" -H "Authorization: Bearer <ACCESS TOKEN>"
PUT https://management.chinacloudapi.cn/subscriptions/<SUBSCRIPTION ID>/resourceGroups/<RESOURCE GROUP>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<USER ASSIGNED IDENTITY NAME>/federatedIdentityCredentials/<FEDERATED IDENTITY CREDENTIAL NAME>?api-version=2022-01-31-preview
{
"properties": {
"issuer": "https://oidc.prod-aks.azure.com/IssuerGUID",
"subject": "system:serviceaccount:ns:svcaccount",
"audiences": [
"api://AzureADTokenExchange"
]
}
}
请求标头
请求标头 | 说明 |
---|---|
Content-Type | 必需。 设置为 application/json 。 |
授权 | 必需。 设置为有效的 Bearer 访问令牌。 |
请求正文
名称 | 说明 |
---|---|
properties.audiences | 必需。 可在颁发的令牌中显示的受众列表。 |
properties.issuer | 必需。 要信任的颁发者的 URL。 |
properties.subject | 必需。 外部文件的标识符。 |
在用户分配的托管标识上列出联合标识凭据
在用户分配的指定托管标识上列出所有联合标识凭据。
curl 'https://management.chinacloudapi.cn/subscriptions/<SUBSCRIPTION ID>/resourceGroups/<RESOURCE GROUP>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<USER ASSIGNED IDENTITY NAME>/<RESOURCE NAME>/federatedIdentityCredentials?api-version=2022-01-31-preview' -H "Content-Type: application/json" -X GET -H "Authorization: Bearer <ACCESS TOKEN>"
GET
https://management.chinacloudapi.cn/subscriptions/<SUBSCRIPTION ID>/resourceGroups/<RESOURCE GROUP>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<USER ASSIGNED IDENTITY NAME>/<RESOURCE NAME>/federatedIdentityCredentials?api-version=2022-01-31-preview
请求标头
请求标头 | 说明 |
---|---|
Content-Type | 必需。 设置为 application/json 。 |
授权 | 必需。 设置为有效的 Bearer 访问令牌。 |
在用户分配的托管标识上获取联合标识凭据
在用户分配的指定托管标识上获取联合标识凭据。
curl 'https://management.chinacloudapi.cn/subscriptions/<SUBSCRIPTION ID>/resourceGroups/<RESOURCE GROUP>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<USER ASSIGNED IDENTITY NAME>/<RESOURCE NAME>/federatedIdentityCredentials/<FEDERATED IDENTITY CREDENTIAL RESOURCENAME>?api-version=2022-01-31-preview' -X GET -H "Content-Type: application/json" -H "Authorization: Bearer <ACCESS TOKEN>"
GET
https://management.chinacloudapi.cn/subscriptions/<SUBSCRIPTION ID>/resourceGroups/<RESOURCE GROUP>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<USER ASSIGNED IDENTITY NAME>/<RESOURCE NAME>/federatedIdentityCredentials/<FEDERATED IDENTITY CREDENTIAL RESOURCENAME>?api-version=2022-01-31-preview
请求标头
请求标头 | 说明 |
---|---|
Content-Type | 必需。 设置为 application/json 。 |
授权 | 必需。 设置为有效的 Bearer 访问令牌。 |
从用户分配的托管标识中删除联合标识凭据
在用户分配的指定托管标识上删除联合标识凭据。
curl 'https://management.chinacloudapi.cn/subscriptions/<SUBSCRIPTION ID>/resourceGroups/<RESOURCE GROUP>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<USER ASSIGNED IDENTITY NAME>/<RESOURCE NAME>/federatedIdentityCredentials/<FEDERATED IDENTITY CREDENTIAL RESOURCENAME>?api-version=2022-01-31-preview' -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer <ACCESS TOKEN>"
DELETE
https://management.chinacloudapi.cn/subscriptions/<SUBSCRIPTION ID>/resourceGroups/<RESOURCE GROUP>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<USER ASSIGNED IDENTITY NAME>/<RESOURCE NAME>/federatedIdentityCredentials/<FEDERATED IDENTITY CREDENTIAL RESOURCENAME>?api-version=2022-01-31-preview
请求标头
请求标头 | 说明 |
---|---|
Content-Type | 必需。 设置为 application/json 。 |
授权 | 必需。 设置为有效的 Bearer 访问令牌。 |
后续步骤
- 有关由外部标识提供者创建的 JWT 所需格式的信息,请阅读断言格式。