培训
认证
Microsoft Certified: Identity and Access Administrator Associate - Certifications
演示 Microsoft Entra ID 的功能,以将标识解决方案现代化、实现混合解决方案和实现标识治理。
本文介绍如何在 Microsoft Entra ID 中管理用户分配的托管标识的联合标识凭据。 联合标识凭据在用户分配的托管标识与外部标识提供者 (IdP) 之间创建信任关系。 不支持在系统分配的托管标识上配置联合标识凭据。
将用户分配的托管标识配置为信任外部 IdP 后,配置外部软件工作负荷以将来自外部 IdP 的令牌交换为来自 Microsoft 标识平台的访问令牌。 外部工作负荷使用访问令牌来访问 Microsoft Entra 受保护的资源,而无需管理机密(在支持的场景中)。 若要详细了解令牌交换工作流,请阅读工作负荷标识联合验证。
本文介绍如何在用户分配的托管标识中创建、列出和删除联合标识凭据。
最多可以向应用程序或用户分配的托管标识添加 20 个联合标识凭据。
配置联合标识凭据时,需要提供几条重要信息:
issuer 和 subject 是建立信任关系所需的关键信息。 issuer
和 subject
的组合在应用中必须唯一。 当外部软件工作负荷请求 Microsoft 标识平台来交换访问令牌的外部令牌时,将针对外部令牌中提供的 和 声明来检查联合标识凭据的 issuerissuer
和 subjectsubject
值。 如果该验证检查通过,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 个字符。
任何联合标识凭据属性值都不支持通配符。
若要详细了解受支持的区域、传播联合凭据更新的时间、支持的颁发者等,请阅读联合标识凭据的重要注意事项和限制。
在 Microsoft Azure 门户中,导航到你创建的用户分配的托管标识。 在左侧导航栏中的“设置”下,选择“联合凭据”,然后选择“添加凭据”。
在“联合凭据场景”下拉列表框中,选择你的场景。
要为 GitHub 操作添加联合身份,请执行以下步骤:
对于“实体类型”,请选择“环境”、“分支”、“拉取请求”或“标记”,并指定值。 值必须与 GitHub 工作流中的配置完全匹配。 有关详细信息,请阅读示例。
为联合凭据添加“名称”。
“颁发者”、“受众”和“主题标识符”字段会根据你输入的值自动填充。
选择“添加”以配置联合凭据。
将你的 Microsoft Entra 托管标识中的以下值用于你的 GitHub 工作流:
AZURE_CLIENT_ID
,托管标识客户端 ID
AZURE_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”。
对于拉取请求事件触发的工作流,请将“实体类型”指定为“拉取请求”
填写“群集证书颁发者 URL”、“命名空间”、“服务帐户名称”和“名称”字段:
选择“添加”以配置联合凭据。
从下拉菜单中选择“其他证书颁发者”场景。
指定以下字段(以在 Google Cloud 中运行的一个软件工作负载为例):
选择“添加”以配置联合凭据。
在 Microsoft Azure 门户中,导航到你创建的用户分配的托管标识。 在左侧导航栏中的“设置”下,选择“联合凭据”。
在该用户分配的托管标识上配置的联合标识凭据已列出。
在 Microsoft Azure 门户中,导航到你创建的用户分配的托管标识。 在左侧导航栏中的“设置”下,选择“联合凭据”。
在该用户分配的托管标识上配置的联合标识凭据已列出。
若要删除特定联合标识凭据,请选择凭据的“删除”图标。
在 Azure Cloud Shell 中使用 Bash 环境。 有关详细信息,请参阅 Azure Cloud Shell 中的 Bash 快速入门。
如需在本地运行 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="centralus"
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 PowerShell 而不是使用 Cloud Shell,请执行以下操作:
安装最新版本的 Azure PowerShell(如果尚未安装)。
登录 Azure。
Connect-AzAccount
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 门户中部署 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": "westcentralus",
"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 CLI 登录到 Azure。
az login
使用 az account get-access-token 获取访问令牌。
az account get-access-token
在用户分配的指定托管标识上创建或更新联合标识凭据。
curl 'https://management.azure.com/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.azure.com/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.azure.com/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.azure.com/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.azure.com/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.azure.com/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.azure.com/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.azure.com/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 访问令牌。 |
培训
认证
Microsoft Certified: Identity and Access Administrator Associate - Certifications
演示 Microsoft Entra ID 的功能,以将标识解决方案现代化、实现混合解决方案和实现标识治理。