使用 App Service 和 Azure Functions 的受控識別

2025-06-05

本文說明如何建立 Azure App Service 和 Azure Functions 應用程式的受控識別，以及如何使用它來存取其他資源。

來自 Microsoft Entra ID 的受控識別可讓您的應用程式輕鬆地存取其他 Microsoft受 Entra 保護的資源，例如 Azure Key Vault。 Azure 平臺會管理身分識別，因此您不需要布建或輪替任何秘密。如需有關 Microsoft Entra ID 中受控識別的詳細資訊，請參閱 Azure 資源的受控識別。

您可以將兩種類型的身分識別授與您的應用程式：

系統指派的身分識別會繫結至應用程式，並在刪除該應用程式時一併刪除。應用程式只能有一個系統指派的身分識別。
使用者指派的身分識別是一項獨立 Azure 資源，可指派給您的應用程式。應用程式可以有多個使用者指派的身分識別。一個使用者指派的身分識別可以指派給多個 Azure 資源，例如兩個 App Service 應用程式。

受控識別設定是位置的特有項目。若要在管理入口中設定部署插槽的受控識別，請先移至插槽。若要使用 Azure 入口網站，在 Microsoft Entra 租用戶中尋找 Web 應用程式或部署位置的受控識別，請直接從租用戶的 [概觀] 頁面搜尋。

注意

受控識別不適用於在 Azure Arc 中部署的應用程式。

由於受控識別不支援跨目錄案例，因此如果您的應用程式跨訂用帳戶或租使用者移轉，則不會如預期般運作。若要在這類移動之後重新建立受控識別，請參閱如果我將訂用帳戶移至另一個目錄，是否會自動重新建立受控識別？下游資源也必須更新存取原則，才能使用新的身分識別。

必要條件

若要執行本文中的步驟，您必須擁有 Azure 資源的最低許可權集。您需要的特定許可權會根據您的案例而有所不同。下表摘要說明最常見的案例：

案例	必要權限	內建角色範例
建立系統指派的身分識別	在應用程式上方或在槽位上方	網站參與者
建立使用者指派的身分識別	`Microsoft.ManagedIdentity/userAssignedIdentities/write` 要在其中建立身分識別的資源群組	受控識別參與者
將使用者指派的身分識別指派給您的應用程式	`Microsoft.Web/sites/write` 透過應用程式、`Microsoft.Web/sites/slots/write` 插槽或 `Microsoft.ManagedIdentity/userAssignedIdentities/*/assign/action` 透過身分識別	網站參與者和受控識別作員
建立 Azure 角色指派	`Microsoft.Authorization/roleAssignments/write` 超過目標資源範圍	角色型存取控制系統管理員或使用者存取系統管理員

新增系統指派的身分識別

若要啟用系統指派的受控識別，請使用下列指示。

在 Azure 入口網站中，移至您的應用程式頁面。
在左側功能表上，選取 [設定]> [身分識別]。
在 [系統指派] 索引標籤上，將 [狀態] 切換為 [開啟]。然後選擇儲存。

執行 az webapp identity assign 命令：

az webapp identity assign --resource-group <group-name> --name <app-name>

針對 App Service

執行 Set-AzWebApp -AssignIdentity 命令：

Set-AzWebApp -AssignIdentity $true -ResourceGroupName <group-name>  -Name <app-name>

針對 Functions

執行 Update-AzFunctionApp -IdentityType 命令：

Update-AzFunctionApp -ResourceGroupName <group-name> -Name <function-app-name>  -IdentityType SystemAssigned

您可以使用 Azure Resource Manager 範本，將 Azure 資源的部署自動化。若要深入瞭解，請參閱在App Service 中自動化資源部署和在 Azure Functions 中自動化資源部署。

您可以在資源定義中包含下列屬性，以建立具有身分識別類型 Microsoft.Web/sites 的任何資源：

"identity": {
    "type": "SystemAssigned"
}

新增系統指派的類型能告訴 Azure 該如何建立及管理應用程式的身分識別。

例如，Web 應用程式範本應如下列 JSON 所示：

{
    "apiVersion": "2022-03-01",
    "type": "Microsoft.Web/sites",
    "name": "[variables('appName')]",
    "location": "[resourceGroup().location]",
    "identity": {
        "type": "SystemAssigned"
    },
    "properties": {
        "name": "[variables('appName')]",
        "serverFarmId": "[resourceId('Microsoft.Web/serverfarms', variables('hostingPlanName'))]",
        "hostingEnvironment": "",
        "clientAffinityEnabled": false,
        "alwaysOn": true
    },
    "dependsOn": [
        "[resourceId('Microsoft.Web/serverfarms', variables('hostingPlanName'))]"
    ]
}

建立網站時，它包含下列屬性：

"identity": {
    "type": "SystemAssigned",
    "tenantId": "<tenant-id>",
    "principalId": "<principal-id>"
}

屬性 tenantId 會識別在 Microsoft Entra 租使用者中，該身份所屬的租戶。屬性 principalId 是應用程式新身分識別的唯一標識符。在 Microsoft Entra ID 中，服務主體的名稱與您為 App Service 或 Azure Functions 實例指定的名稱相同。

如果您需要在範本的稍後階段參考這些屬性，請使用 reference() 範本函式搭配 'Full' 選項，如下列範例所示：

{
    "tenantId": "[reference(resourceId('Microsoft.Web/sites', variables('appName')), '2018-02-01', 'Full').identity.tenantId]",
    "objectId": "[reference(resourceId('Microsoft.Web/sites', variables('appName')), '2018-02-01', 'Full').identity.principalId]",
}

新增使用者指派的身分識別

若要建立具有使用者指派身分識別的應用程式，請建立身分識別，然後將其資源標識元新增至您的應用程式組態。

根據這些指示建立使用者指派的受控識別資源。
在應用程式的左側功能表上，選取 [ 設定>身分識別]。
選取 [ 用戶指派]，然後選取 [ 新增]。
搜尋您稍早建立的身分識別、加以選取，然後選取 [ 新增]。

完成這些步驟之後，應用程式會重新啟動。

建立使用者指派的身分識別：

az identity create --resource-group <group-name> --name <identity-name>

az webapp identity assign執行命令，將身分識別指派給應用程式：

az webapp identity assign --resource-group <group-name> --name <app-name> --identities <identity-id>

針對 App Service

目前不支援使用 Azure PowerShell 在 App Service 中新增使用者指派的身分識別。

針對 Functions

建立使用者指派的身分識別：

Install-Module -Name Az.ManagedServiceIdentity -AllowPrerelease
$userAssignedIdentity = New-AzUserAssignedIdentity -Name <identity-name> -ResourceGroupName <group-name> -Location <region>

執行 Update-AzFunctionApp -IdentityType UserAssigned -IdentityId 命令，以指派 Functions 中的身分識別：

Update-AzFunctionApp -Name <app-name> -ResourceGroupName <group-name> -IdentityType UserAssigned -IdentityId $userAssignedIdentity.Id

您可以在資源定義中包含下列區塊，以建立具有身分識別的類型Microsoft.Web/sites的任何資源。將<resource-id>替換為所需身分識別的資源 ID。

"identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
        "<resource-id>": {}
    }
}

注意

應用程式可以同時具有系統指派的身分識別和使用者指派的身分識別。在這裡情況下， type 屬性為 SystemAssigned,UserAssigned。

新增使用者指派的類型會告知 Azure 使用您為應用程式指定的使用者指派身分識別。

例如，Web 應用程式範本應如下列 JSON 所示：

{
    "apiVersion": "2022-03-01",
    "type": "Microsoft.Web/sites",
    "name": "[variables('appName')]",
    "location": "[resourceGroup().location]",
    "identity": {
        "type": "UserAssigned",
        "userAssignedIdentities": {
            "[resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', variables('identityName'))]": {}
        }
    },
    "properties": {
        "name": "[variables('appName')]",
        "serverFarmId": "[resourceId('Microsoft.Web/serverfarms', variables('hostingPlanName'))]",
        "hostingEnvironment": "",
        "clientAffinityEnabled": false,
        "alwaysOn": true
    },
    "dependsOn": [
        "[resourceId('Microsoft.Web/serverfarms', variables('hostingPlanName'))]",
        "[resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', variables('identityName'))]"
    ]
}

建立網站時，它包含下列屬性：

"identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
        "<resource-id>": {
            "principalId": "<principal-id>",
            "clientId": "<client-id>"
        }
    }
}

針對 Microsoft Entra 管理所用的身分識別，principalId 屬性是唯一識別碼。屬性 clientId 是應用程式新身分識別的唯一標識符。您可以使用它來指定要在執行時間呼叫期間使用的身分識別。

設定目標資源

您必須設定目標資源，以允許從您的應用程式存取。針對大部分的 Azure 服務，您可以藉由建立角色指派來設定目標資源。

某些服務會使用 Azure 角色型訪問控制以外的機制。若要瞭解如何使用身分識別來設定存取權，請參閱每個目標資源的檔。若要深入瞭解哪些資源支援 Microsoft Entra 權杖，請參閱支援 Microsoft Entra 驗證的 Azure 服務。

例如，如果您要求令牌來存取 Azure Key Vault 中的機密資訊，您也必須建立角色指派，讓受控的身分識別能夠使用目標保存庫中的機密資訊。否則，即使您使用有效的令牌，Key Vault 仍會拒絕您的呼叫。 Azure SQL 資料庫和其他服務也是如此。

重要

受控身分識別的後端服務會將每個資源的 URI 快取保留大約 24 小時。對於受控識別的群組或角色成員資格，變更可能需要數小時才會生效。目前無法強制令牌在受管理的身份到期前刷新。如果您變更受控識別的群組或角色成員資格以新增或移除許可權，您可能需要等候數小時，讓使用身分識別的 Azure 資源具有正確的存取權。

如需群組或角色成員資格的替代方案，請參閱使用受控識別進行授權的限制。

以應用程式程式碼連線至 Azure 服務

透過其受控識別，應用程式可以取得 Azure 資源的令牌，例如 Azure SQL Database、Azure Key Vault 和 Azure 儲存空間，這些資源由 Microsoft Entra ID 協助保護。這些令牌代表存取資源的應用程式，而不是應用程式的任何特定使用者。

App Service 和 Azure Functions 提供內部可存取的 REST 端點來擷取權杖。您可以使用標準 HTTP GET 請求從應用程式中訪問 REST 端點。您可以使用每種語言的一般 HTTP 用戶端來實作要求。

針對 .NET、JavaScript、JAVA 和 Python，Azure 身分識別用戶端程式庫會在此 REST 端點上提供抽象概念，並簡化開發體驗。連線至其他 Azure 服務就如同將認證物件新增至服務特定用戶端一樣簡單。

原始 HTTP GET 要求會使用兩個提供的環境變數，如下所示：

GET /MSI/token?resource=https://vault.azure.net&api-version=2019-08-01 HTTP/1.1
Host: <ip-address-:-port-in-IDENTITY_ENDPOINT>
X-IDENTITY-HEADER: <value-of-IDENTITY_HEADER>

範例回應看起來可能如下列範例所示：

HTTP/1.1 200 OK
Content-Type: application/json

{
    "access_token": "eyJ0eXAi…",
    "expires_on": "1586984735",
    "resource": "https://vault.azure.net",
    "token_type": "Bearer",
    "client_id": "00001111-aaaa-2222-bbbb-3333cccc4444"
}

該回應與 Microsoft Entra 服務對服務存取權杖要求的回應相同。若要存取金鑰保存庫，請將的值access_token新增至與保存庫的客戶端連線。

針對 Java 應用程式和函數，使用受控身分識別的最簡單方式是透過適用於 Java 的 Azure 身分識別用戶端程式庫。如需詳細資訊，請參閱教學課程：使用受控識別從 App Service 連線到 Azure 資料庫，而不使用秘密。

如需詳細資訊，請參閱客戶端連結庫的個別文件標題：

連結的範例會使用 DefaultAzureCredential。相同的模式可以在 Azure 中使用受控識別，也可以在本機電腦上使用，即使沒有受控識別。

如需適用於 Java 的 Azure 身分識別用戶端連結庫更多程式碼範例，請參閱 Azure 身分識別範例。

使用下列指令碼指定 Azure 服務的資源 URI，以便從本機端點擷取權杖：

$resourceURI = "https://<Entra-resource-URI-for-resource-to-obtain-token>"
$tokenAuthURI = $env:IDENTITY_ENDPOINT + "?resource=$resourceURI&api-version=2019-08-01"
$tokenResponse = Invoke-RestMethod -Method Get -Headers @{"X-IDENTITY-HEADER"="$env:IDENTITY_HEADER"} -Uri $tokenAuthURI
$accessToken = $tokenResponse.access_token

如需 REST 端點的詳細資訊，請參閱本文稍後的 REST 端點參考。

移除身分識別

當您移除系統指派的身分識別時，隨即從 Microsoft Entra ID 中刪除。刪除應用程式資源本身時，系統指派的身分識別也會從 Microsoft Entra ID 自動移除。

在應用程式的左側功能表上，選取 [ 設定>身分識別]。
請依照身分識別類型執行下列步驟：
- 針對系統指派的身分識別：在系統指派索引標籤上，將狀態切換為關閉。然後選擇儲存。
- 針對使用者指派的身分識別：選取 [ 使用者指派 ] 索引卷標，選取身分識別的複選框，然後選取 [ 移除]。選取是以確認。

若要移除系統指派的身分識別，請使用此命令：

az webapp identity remove --resource-group <group-name> --name <app-name>

若要移除一或多個使用者指派的身分識別，請使用此命令：

az webapp identity remove --resource-group <group-name> --name <app-name> --identities <identity-id1> <identity-id2> ...

您也可以在[system]中指定--identities，以移除系統指派的身分識別。

針對 App Service

若要移除 App Service 的系統指派身分識別，請執行 Set-AzWebApp -AssignIdentity 命令：

Set-AzWebApp -AssignIdentity $false -Name <app-name> -ResourceGroupName <group-name>

針對 Functions

若要移除 Azure PowerShell 中的所有身分識別（僅限 Azure Functions），請執行下列命令：

# Update an existing function app to have IdentityType "None".
Update-AzFunctionApp -Name <function-app-name> -ResourceGroupName <group-name> -IdentityType None

若要移除 ARM 範本中的所有身分識別，請使用下列程式代碼：

"identity": {
    "type": "None"
}

注意

您也可以設定只停用本機令牌服務的應用程式設定： WEBSITE_DISABLE_MSI。不過，它會保留身分識別。工具仍會將受控識別顯示為開啟或啟用。因此，我們不建議您使用此設定。

REST 端點參考

具有受控識別的應用程式可定義兩個環境變數來提供此端點：

IDENTITY_ENDPOINT：本機令牌服務的 URL。
IDENTITY_HEADER: 可協助減輕伺服器端偽造請求（SSRF）攻擊的標頭。平臺會旋轉數值。

變數 IDENTITY_ENDPOINT 是應用程式可以要求令牌的本機URL。若要取得資源的令牌，請對此端點提出 HTTP GET 要求。包含下列參數：

參數名稱在描述

resource 查詢資源的 Microsoft Entra 資源 URI，也就是要取得權杖的目標資源。此資源可以是支援 Microsoft Entra 驗證或任何其他資源 URI 的 Azure 服務之一。

api-version 查詢要使用的權杖 API 版本。使用 2019-08-01。

X-IDENTITY-HEADER 頁首 IDENTITY_HEADER 環境變數的值。此標頭可用來協助減輕 SSRF 攻擊。

client_id 查詢 (選擇性) 要使用的使用者指派身分識別，其用戶端識別碼。它不能用於包含 principal_id、 mi_res_id或 object_id的要求。如果省略所有識別碼參數 (client_id、principal_id、object_id 和 mi_res_id)，則會使用系統指派的身分識別。

principal_id 查詢 (選擇性) 要使用的使用者指派身分識別，其主體識別碼。參數 object_id 是可以改用的別名。它不能用於包含 client_id、 mi_res_id或 object_id的要求。如果省略所有識別碼參數 (client_id、principal_id、object_id 和 mi_res_id)，則會使用系統指派的身分識別。

mi_res_id 查詢 (選擇性) 要使用的使用者指派身分識別，其 Azure 資源識別碼。它不能用於包含 principal_id、 client_id或 object_id的要求。如果省略所有識別碼參數 (client_id、principal_id、object_id 和 mi_res_id)，則會使用系統指派的身分識別。

參數名稱	在	描述
`resource`	查詢	資源的 Microsoft Entra 資源 URI，也就是要取得權杖的目標資源。此資源可以是支援 Microsoft Entra 驗證或任何其他資源 URI 的 Azure 服務之一。
`api-version`	查詢	要使用的權杖 API 版本。使用 `2019-08-01`。
`X-IDENTITY-HEADER`	頁首	`IDENTITY_HEADER` 環境變數的值。此標頭可用來協助減輕 SSRF 攻擊。
`client_id`	查詢	(選擇性) 要使用的使用者指派身分識別，其用戶端識別碼。它不能用於包含 `principal_id`、 `mi_res_id`或 `object_id`的要求。如果省略所有識別碼參數 (`client_id`、`principal_id`、`object_id` 和 `mi_res_id`)，則會使用系統指派的身分識別。
`principal_id`	查詢	(選擇性) 要使用的使用者指派身分識別，其主體識別碼。參數 `object_id` 是可以改用的別名。它不能用於包含 `client_id`、 `mi_res_id`或 `object_id`的要求。如果省略所有識別碼參數 (`client_id`、`principal_id`、`object_id` 和 `mi_res_id`)，則會使用系統指派的身分識別。
`mi_res_id`	查詢	(選擇性) 要使用的使用者指派身分識別，其 Azure 資源識別碼。它不能用於包含 `principal_id`、 `client_id`或 `object_id`的要求。如果省略所有識別碼參數 (`client_id`、`principal_id`、`object_id` 和 `mi_res_id`)，則會使用系統指派的身分識別。

重要

如果您嘗試為使用者指派的身分識別取得令牌，請確保納入一個選擇性屬性。否則，令牌服務會嘗試取得系統指派的身分識別令牌，但該身分識別可能存在，也可能不存在。

請考慮下列教學課程：

共用方式為

使用 App Service 和 Azure Functions 的受控識別

必要條件

新增系統指派的身分識別

新增使用者指派的身分識別

設定目標資源

以應用程式程式碼連線至 Azure 服務

移除身分識別

REST 端點參考

相關內容

意見反應

其他資源