共用方式為


設定使用者指派的受控識別以信任外部識別提供者

本文說明如何在 Microsoft Entra ID 中管理使用者指派受控識別的同盟身分識別認證。 同盟身分識別認證會在使用者指派的受控識別與外部識別提供者 (IdP) 之間建立信任關係。 不支援在系統指派的受控識別上設定同盟身分識別認證。

設定使用者指派的受控識別以信任外部 IdP 之後,請設定外部軟體工作負載,以從外部 IdP 交換令牌,以取得來自 Microsoft 身分識別平台 的存取令牌。 外部工作負載會使用存取令牌來存取 Microsoft Entra 受保護的資源,而不需要管理秘密(在支援的案例中)。 若要深入了解權杖交換工作流程,請參閱工作負載身分識別同盟

在本文中,您將瞭解如何在使用者指派的受控識別上建立、列出和刪除同盟身分識別認證。

重要考慮和限制

最多可以將 20 個同盟身分識別認證新增至應用程式或使用者指派的受控識別。

當您設定同盟身分識別認證時,有數個重要的資訊提供:

  • issuersubject 是設定信任關係所需的重要資訊片段。 和 subject 的組合issuer在應用程式上必須是唯一的。 當外部軟體工作負載要求 Microsoft 身分識別平台 交換存取令牌的外部令牌時,系統會針對issuer外部令牌中提供的 和 宣告檢查同盟身分識別認證的簽發者和subject主體值。 如果該驗證檢查通過,Microsoft 身分識別平台 對外部軟體工作負載發出存取令牌。

  • issuer 是外部識別提供者的 URL,必須符合 issuer 所交換之外部令牌的宣告。 必要。 issuer如果宣告在值中有前置或尾端空格符,則會封鎖令牌交換。 此欄位的字元限制為 600 個字元。

  • subject 是外部軟體工作負載的標識碼,必須符合 sub 所交換之外部令牌的 (subject) 宣告。 主體 沒有固定格式,因為每個 IdP 都會使用自己的格式,有時是 GUID,有時是冒號分隔標識符,有時是任意字串。 此欄位的字元限制為 600 個字元。

    重要

    主體設定值必須完全符合 GitHub 工作流程設定上的設定。 否則,Microsoft 身分識別平台將會查看傳入的外部權杖,並拒絕存取權杖的交換。 您將不會收到錯誤,交換會失敗且不會發生錯誤。

    重要

    如果您不小心在主體設定中新增不正確的外部工作負載資訊,則會成功建立同盟身分識別認證,而不會發生錯誤。 在令牌交換失敗之前,錯誤不會變得明顯。

  • 物件會 列出可以出現在外部令牌中的物件。 必要。 您必須新增單一物件值,其限制為600個字元。 建議值為 「api://AzureADTokenExchange」。 它說,Microsoft 身分識別平台 必須在傳入令牌的宣告中aud接受什麼。

  • name 是同盟身分識別認證的唯一標識符。 必要。 此欄位的字元限制為 3-120 個字元,而且必須是 URL 易記。 支援英數位元、虛線或底線字元,第一個字元必須是英數位元。  一旦建立它就不可變了。

  • description 是同盟身分識別認證的使用者提供的描述。 選擇性。 Microsoft Entra ID 不會驗證或檢查描述。 此欄位的限制為 600 個字元。

任何同盟身分識別認證屬性值都不支援通配符。

若要深入瞭解支持的區域、傳播同盟認證更新的時間、支援的簽發者等等,請參閱 同盟身分識別認證的重要考慮和限制。

必要條件

在使用者指派的受控識別上設定同盟身分識別認證

Microsoft Entra 系統管理中心,流覽至您所建立的使用者指派受控識別。 在左側導覽列中的 [設定] 下,選取 [同盟認證],然後選取 [新增認證]。

在 [ 同盟認證案例 ] 下拉式方塊中,選取您的案例。

部署 Azure 資源的 GitHub Actions

若要新增 GitHub 動作的同盟身分識別,請遵循下列步驟:

  1. 針對 [實體類型],選取 [環境]、[分支]、[提取要求] 或 [標記],然後指定值。 這些值必須完全符合 GitHub 工作流程中的設定。 如需詳細資訊,請閱讀範例

  2. 新增同盟認證的 [名稱]

  3. [簽發者]、[對象] 和 [主體識別碼] 欄位會根據您所輸入的值自動填入。

  4. 選取 [新增 ] 以設定同盟認證。

針對 GitHub 工作流程使用下列來自您Microsoft Entra 受控識別的值:

  • AZURE_CLIENT_ID 受控識別 用戶端標識碼

  • AZURE_SUBSCRIPTION_ID 訂用 帳戶標識碼

    下列螢幕快照示範如何複製受控識別標識碼和訂用帳戶標識碼。

    示範如何從 Azure 入口網站 複製受控識別標識碼和訂用帳戶標識碼的螢幕快照。

  • AZURE_TENANT_ID目錄 (租使用者) 識別碼。 瞭解如何 尋找您的Microsoft Entra 租用戶標識符

實體類型範例

分支範例

針對主要分支上的推送或提取要求事件所觸發的工作流程:

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

指定 [分支] 的 [實體類型] 和「主要」的 [GitHub 分支名稱]

環境範例

針對繫結至名為「生產」環境的作業:

on:
  push:
    branches:
      - main

jobs:
  deployment:
    runs-on: ubuntu-latest
    environment: production
    steps:
      - name: deploy
        # ...deployment-specific steps

指定 [環境] 的 [實體類型],以及「生產」的 [GitHub 環境名稱]

標記範例

例如,針對由推送至名為 "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.*

指定 [標記] 的 [實體類型] 和 "v2" 的 [GitHub 標記名稱]

提取要求範例

針對提取要求事件所觸發的工作流程,請指定提取要求的實體類型

存取 Azure 資源的 Kubernetes

填寫 [叢集簽發者 URL]、[命名空間]、[服務帳戶名稱] 和 [名稱] 字段:

  • 叢集簽發者 URL 是受控叢集的 OIDC 簽發者 URL,或自我管理叢集的 OIDC 簽發者 URL
  • 服務帳戶名稱 是 Kubernetes 服務帳戶的名稱,可為 Pod 中執行的進程提供身分識別。
  • 命名空間 是服務帳戶命名空間。
  • Name 是同盟認證的名稱,稍後無法變更。

選取 [新增 ] 以設定同盟認證。

其他

從下拉功能表中選取 [ 其他簽發者 案例]。

指定下列欄位(使用在 Google Cloud 中執行的軟體工作負載作為範例):

  • Name 是同盟認證的名稱,稍後無法變更。
  • 主體標識碼:必須符合 sub 外部識別提供者所簽發之令牌中的宣告。 在此範例中使用Google Cloud時, 主體 是您計劃使用之服務帳戶的唯一標識符。
  • 簽發者:必須符合 iss 外部識別提供者所簽發之令牌中的宣告。 符合 OIDC 探索規格的 URL。Microsoft Entra ID 會使用此簽發者 URL 來擷取驗證令牌所需的密鑰。 針對Google Cloud,簽發 為 “https://accounts.google.com"。

選取 [新增 ] 以設定同盟認證。

列出使用者指派受控識別的同盟身分識別認證

Microsoft Entra 系統管理中心,流覽至您所建立的使用者指派受控識別。 在 左側導覽列中的 [設定 ] 下,選取 [ 同盟認證]。

列出在該使用者指派的受控識別上設定的同盟身分識別認證。

從使用者指派的受控識別中刪除同盟身分識別認證

Microsoft Entra 系統管理中心,流覽至您所建立的使用者指派受控識別。 在 左側導覽列中的 [設定 ] 下,選取 [ 同盟認證]。

列出在該使用者指派的受控識別上設定的同盟身分識別認證。

若要刪除特定的同盟身分識別認證,請選取 該認證的 [刪除 ] 圖示。

必要條件

在使用者指派的受控識別上設定同盟身分識別認證

執行 az identity federated-credential create 命令,在使用者指派的受控識別上建立新的同盟身分識別認證(由名稱指定)。 指定名稱、簽發者主體和其他參數。

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 命令以顯示同盟身分識別認證(依標識符):

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 Cloud Shell,您可以使用程式代碼區塊右上角的 [試用] 按鈕來開啟
    • 使用 Azure PowerShell 在本機執行指令碼,如下一節所述。
  • 建立使用者指派的受控識別 (機器翻譯)
  • 在下列步驟中尋找使用者指派的受控識別名稱。

在本機設定 Azure PowerShell

若要針對本文在本機使用 Azure PowerShell,而不是使用 Cloud Shell:

  1. 如果您尚未安裝最新版的 Azure PowerShell,請先安裝。

  2. 登入Azure。

    Connect-AzAccount
    
  3. 安裝最新版的 PowerShellGet

    Install-Module -Name PowerShellGet -AllowPrerelease
    

    執行此命令以進行下一個步驟之後,您可能需要 Exit 離開目前的 PowerShell 工作階段。

  4. 安裝模組 Az.ManagedServiceIdentity 以執行本文中使用者指派的受控識別作業。

    Install-Module -Name Az.ManagedServiceIdentity
    

在使用者指派的受控識別上設定同盟身分識別認證

執行 New-AzFederatedIdentityCredentials 命令,在使用者指派的受控識別上建立新的同盟身分識別認證(由名稱指定)。 指定名稱、簽發者主體和其他參數。

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

必要條件

範本建立和編輯

Resource Manager 樣本可協助您部署 Azure 資源群組所定義的新或修改資源。 有數個選項可供範本編輯和部署,同時以本機和入口網站為基礎。 您可以:

在使用者指派的受控識別上設定同盟身分識別認證

同盟身分識別認證和父使用者指派的身分識別可以建立或更新為以下範本的方法。 您可以從 Azure 入口網站 部署ARM樣本

所有範本參數都是必要參數。

同盟身分識別認證名稱長度限制為 3-120 個字元。 它必須是英數位元、虛線、底線。 第一個符號只有英數位元。

您必須將一個物件新增至同盟身分識別認證。 物件會在令牌交換期間進行驗證。 使用 「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')]"
                        ]
                    }
                }
            ]
        }
    ]
}

必要條件

取得持有人存取令牌

  1. 如果您是在本機執行,請透過 Azure CLI 登入 Azure。

    az login
    
  2. 使用 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 存取權杖。

下一步

  • 如需外部識別提供者所建立之 JWT 所需格式的相關信息,請閱讀判斷 提示格式