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

  • 發行項

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

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

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

重要考慮和限制

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

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

  • issuer 和 subject 是設定信任關係所需的重要資訊片段。 和 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 訂用 帳戶識別碼 。

    下列螢幕擷取畫面示範如何複製受控識別識別碼和訂用帳戶識別碼。

    Screenshot that demonstrates how to copy the managed identity ID and subscription ID from Azure portal.

  • AZURE_TENANT_ID目錄 （租使用者） 識別碼 。 瞭解如何 尋找您的 Microsoft Entra 租使用者識別碼 。

實體類型範例

分支範例

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

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

指定 Branch 的實體類型 ，以及 「main」 的 GitHub 分支名稱 。

環境範例

針對系結至名為「生產環境」的作業：

on:
  push:
    branches:
      - main

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

指定環境的 實體類型 ，以及 「production」 的 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.*

指定 Tag 的實體類型 ，以及 「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 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 所需格式的相關資訊，請閱讀判斷 提示格式 。