共用方式為


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

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

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

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

重要考量與限制

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

設定同盟身分識別認證時,可以提供幾項重要的資訊:

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

  • 簽發者是外部識別提供者的 URL。此值必須與要交換之外部權杖的 issuer 宣告相符。 必要。 如果 issuer 宣告在值中有前置或尾端空白字元,則系統會封鎖權杖交換。 此欄位的字元數限制為 600 個。

  • 主體是外部軟體工作負載的識別碼。此值必須與要交換之外部權杖的 sub (subject) 宣告相符。 主體沒有固定的格式,因為每個 IdP 都使用自己的格式 - 有時是 GUID,有時是以冒號分隔的識別碼,有時是任意字串。 此欄位的字元數限制為 600 個。

    重要

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

    重要

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

  • 對象會列出可出現在外部權杖中的對象。 必要。 您必須新增單一受眾值,其限制為 600 個字元。 建議值為 "api://AzureADTokenExchange"。 其指出 Microsoft 身分識別平台在傳入權杖的 aud 宣告中必須接受哪些內容。

  • 名稱是同盟身分識別認證的唯一識別碼。 必要。 此欄位的限制為 3-120 個字元,而且必須是易記的 URL。 支援英數字元、破折號或底線字元,第一個字元必須是英數字元。  名稱一旦建立,就是不可改變。

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

任何同盟身分識別認證屬性值皆不支援萬用字元。

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

必要條件

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

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

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

部署 Azure 資源的 GitHub Actions

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

  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 中執行的處理序提供身分識別。
  • 命名空間是服務帳戶的命名空間。
  • 名稱是同盟認證的名稱,之後無法變更。

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

其他

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

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

  • 名稱是同盟認證的名稱,之後無法變更。
  • 主體識別碼:必須符合外部識別提供者所發出權杖中的 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" 做為預設值。

範本無法使用 List、Get 和 Delete 作業。 如需了解這些作業,請參閱 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 格式所需的資訊,請參閱判斷提示格式