利用用戶指定管理身份，將 Azure 託管的 Java 應用程式認證至 Azure 資源

推薦的認證方式是使用 管理身份，將Azure託管應用程式認證至其他Azure資源。 大多數 Azure 服務都支援此方法，包括託管於 Azure App Service、Azure Container Apps 及 Azure Virtual Machines 上的應用程式。 欲了解更多資訊，請參閱 Azure 服務與支援受管理身份的資源類型。 若需瞭解有關各種驗證技術與方法的更多資訊，請參閱 使用 Azure Identity library 為 Java 應用程式驗證Azure 服務。

在以下章節中，您將了解：

• 基本的管理身份概念。
• 如何為您的應用程式建立由使用者指派的管理身份。
• 如何將角色指派給使用者指派的管理身份。
• 如何利用應用程式代碼中使用者指派的管理身份來進行驗證。

基本受控識別概念

管理身份讓應用程式能安全連接其他 Azure 資源，無需使用秘密金鑰或其他應用程式秘密。 在內部，Azure 追蹤身份及其被允許存取的資源。 Azure 利用這些資訊自動取得 Microsoft Entra 令牌，讓應用程式能夠連接其他 Azure 資源。

設定載入的應用程式時，需要考慮兩種類型的受控識別：

• System-assigned 管理身份直接啟用於 Azure 資源，並與其生命周期綁定。 當資源被刪除時，Azure 會自動幫你刪除該身份。 系統指派的身分識別提供使用受控識別的極簡方法。
• User-assigned 管理身份被建立為獨立的Azure資源，並提供更高的彈性與功能。 它們非常適合涉及多個需要共享相同身份與權限的 Azure 資源解決方案。 例如，若多個虛擬機需要存取同一組 Azure 資源，使用者指派的管理身份便能提供可重用性與最佳化管理。

小提示

如需如何深入瞭解如何選取和管理系統指派和使用者指派的受控識別，請參閱 受控識別最佳做法建議 一文。

以下章節說明啟用及使用Azure託管應用程式的使用者指派管理身份的步驟。 如果你需要使用系統指派的管理身份，請參考 使用系統指派的管理身份驗證在 Azure 託管的 Java 應用程式以訪問 Azure 資源。

建立使用者指派的管理型身分識別

使用者指派的管理身份會透過 Azure 入口網站或 Azure CLI 在你的 Azure 訂閱中建立為獨立資源。 Azure CLI指令可在 Azure Cloud Shell或安裝 Azure CLI 的工作站上執行。

Azure portal

1. 在Azure入口網站，請在主搜尋欄輸入 Managed identities，並在 Services 區塊中選擇匹配結果。

2. 在 [受控識別] 頁面上，選取 [+ 建立]。

   

3. 在 [建立使用者指派的受控識別 頁面上，選取使用者指派受控識別的訂用帳戶、資源群組和區域，然後提供名稱。

4. 選取 [檢閱 + 建立]，以檢閱和驗證您的輸入。

   

5. 選取 [建立]，以建立使用者指派的受控識別。

6. 建立身份之後，選擇 移至資源。

7. 在新身分識別的 [概觀] 頁面上，複製 用戶端標識碼 值，以供稍後設定應用程式程式代碼時使用。

Azure CLI

使用 Azure CLI 指令 az identity create 建立一個受管理身份：

az identity create \
    --resource-group <resource-group-name> \
    --name <identity-name> \
    --query 'clientId' \
    --output json

命令輸出會列印所建立使用者指派受控識別的用戶端標識碼。 用戶端識別碼可用來設定依賴身分識別的應用程式程式碼。

您可以使用 az identity show 命令再次檢視受控識別屬性：

az identity show \
    --resource-group <your-resource-group> \
    --name <your-managed-identity-name> \
    --output json

將受控識別指派給您的應用程式

使用者指派的管理身份可以與一個或多個 Azure 資源綁定。 使用該身分識別的所有資源都會獲得透過身分識別角色授予的權限。

Azure portal

1. 在 Azure 入口網站中，導覽到承載你應用程式程式碼的資源，例如 Azure App Service 或 Azure Container Apps 實例。

2. 從資源的 [概觀] 頁面中，展開 [[設定]，然後從導覽中選取 [身分識別]。

3. 在 [身分識別] 頁面上，切換至 [使用者指派] 索引標籤。

4. 選取 + 新增 以開啟 新增使用者指派的受控識別 面板。

5. 在 [新增使用者指定的受控身份 面板上，使用 [訂用帳戶] 下拉式清單來篩選您的身份搜尋結果。 使用 User assigned managed identities 搜尋框，找到你在 Azure 上為主機應用程式的資源啟用的使用者指派管理的身分識別。

6. 選取身分識別，然後在面板底部選擇 [新增] 以繼續。

   

Azure CLI

Azure CLI 提供不同指令，將使用者指派的管理身份分配給不同類型的主機服務。

1. 使用 Azure CLI 為資源（例如 Azure App Service 網頁應用程式）分配使用者指派的管理的身分識別時，您需要該身分識別的資源 ID。 使用 az identity show 命令來擷取資源識別碼：

   az identity show \
       --resource-group <your-resource-group> \
       --name <your-managed-identity-name> \
       --output json \
       --query id
   

2. 取得資源 ID 後，使用 Azure CLI 指令 az <resourceType> identity assign 指令將使用者指定的管理身份與不同資源關聯，例如以下：

   Azure App Service時，請使用Azure CLI指令 az webapp identity assign：

   az webapp identity assign \
       --resource-group <resource-group-name> \
       --name <webapp-name> \
       --identities <user-assigned-identity-resource-id>
   

   Azure Container Apps時，請使用Azure CLI指令 az containerapp identity assign：

   az containerapp identity assign \
       --resource-group <resource-group-name> \
       --name <containerapp-name> \
       --user-assigned <user-assigned-identity-resource-id>
   

   對於Azure Virtual Machines，請使用Azure CLI指令 az vm identity assign：

   az vm identity assign \
       --resource-group <resource-group-name> \
       --name <vm-name> \
       --identities <user-assigned-identity-resource-id>
   

將角色指派給管理的身分識別

接下來，判斷您的應用程式需要哪些角色，並將這些角色指派給受控識別。 您可以在下列範圍將角色指派給受控識別：

• 資源：指派的角色僅適用於該特定資源。
• 資源群組：指派的角色會套用至資源群組中包含的所有資源。
• 訂用帳戶：指派的角色會套用至訂用帳戶中包含的所有資源。

以下範例展示了如何在資源群組範圍內指派角色，因為許多應用程式使用單一資源群組來管理所有相關的 Azure 資源。

Azure portal

1. 流覽至資源群組的 [概觀] 頁面，其中包含具有使用者指派受控識別的應用程式。

2. 請選取左側導覽列中的 存取控制 (IAM)。

3. 在 [存取控制 （IAM）] 頁面上，選取頂端功能表上的 [+ 新增]，然後選擇 [新增角色指派] 導覽至 [新增角色指派] 頁面。

   

4. [新增角色指派] 頁面會顯示多步驟的索引標籤式工作流程，以將角色指派給身分。 在 [初始 角色] 索引標籤上，使用頂端的搜尋方塊來找出您要指派給身分識別的角色。

5. 從結果中選取角色，然後選擇 [下一步] 以移至 [成員] 標籤。

6. 針對 [[指派存取權給] 選項，選取 [受控識別]。

7. 針對 [成員] 選項，選取 [+ 選取成員] 以開啟 [選取受控識別] 面板。

8. 在 [選取受控識別 面板上，使用 [訂用帳戶] 和 [受控 識別] 下拉式清單來篩選您身分識別的搜尋結果。 使用 Select 搜尋框，找到你為 App 主機Azure資源啟用的使用者指派管理身份。

   

9. 選取身分，然後在面板底部選擇[選取]以繼續。

10. 請在頁面底部點選 ，然後選擇 [檢閱 + 指派]。

11. 在最後一個 [檢閱 + 指派] 索引標籤上，選取 [檢閱 + 指派]，以完成工作流程。

Azure CLI

1. 要使用 Azure CLI 將角色指派給使用者指派的管理身份，你需要該身份的主體 ID。 使用 az identity show 命令來擷取主體識別碼：

   az identity show \
       --resource-group <your-resource-group> \
       --name <your-managed-identity-name> \
       --output json \
       --query principalId
   

2. 使用 az role definition list 命令來查看受控識別可以被指派哪些角色：

   az role definition list \
       --query "sort_by([].{roleName:roleName, description:description}, &roleName)" \
       --output table
   

3. 使用 az role assignment create 命令，將角色指派給受控身份：

   az role assignment create \
       --assignee <your-principal-id> \
       --role <role-name> \
       --scope <scope>
   

   例如，為了允許 ID 為 99999999-9999-9999-9999-999999999999 的受管理身份具備讀取、寫入及刪除 msdocs-sdk-auth-example 資源群組中所有儲存帳號的 Azure 儲存體 blob 容器和資料的權限，請使用以下指令將應用程式服務主體指派到 Storage Blob Data Contributor 角色：

   az role assignment create \
       --assignee 99999999-9999-9999-9999-999999999999 \
       --role "Storage Blob Data Contributor" \
       --scope "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/msdocs-sdk-auth-example"
   

關於使用 Azure CLI 在資源或訂閱層級分配權限的資訊，請參閱文章 Assign Azure roles with the Azure CLI。

從你的應用程式認證到 Azure 服務

Azure 身分識別程式庫 提供各種 認證的實作，以支援不同的情境和 Microsoft Entra 驗證流程。 由於在本機執行時無法使用受控身分識別，後續步驟會示範應該在什麼情況下使用哪種認證：

• 本機開發環境：只在本機開發時，請使用名為 DefaultAzureCredential 的類別，以便使用預先配置且有意見的認證鏈。 DefaultAzureCredential 會從你本地的工具或 IDE（如 Azure CLI 或 Visual Studio Code）中發現使用者憑證。 它也提供重試的彈性和便利性、回應等候時間，以及支援多個驗證選項。 請造訪 在本地開發期間對 Azure 服務進行驗證 文章以了解更多資訊。
• Azure 託管應用程式：當你的應用程式在Azure中運行時，請使用 ManagedIdentityCredential 安全地發現你應用程式所設定的管理身份。 指定此確切類型的認證可防止其他可用認證被意外使用。

實作程式碼

將 azure-identity 相依性加入你的 pom.xml 檔案。

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
</dependency>

Azure 服務是透過各種 Azure SDK 用戶端函式庫中的專用用戶端類別存取的。 以下程式碼範例示範如何建立憑證實例並與 Azure SDK 服務客戶端一起使用。 在您的應用程式代碼中，請完成以下步驟以使用管理身份進行認證：

1. 匯入 DefaultAzureCredentialBuilder、 ManagedIdentityCredentialBuilder和 TokenCredential 類別。
2. 將適當的 TokenCredential 實例傳遞給用戶端：
   • 在本地運行時使用DefaultAzureCredential
   • 當應用程式在Azure執行時，請使用 ManagedIdentityCredential，並設定客戶端 ID、資源 ID 或物件 ID。

用戶端識別碼

在設定需要使用該身分識別進行驗證的應用程式或服務時，用戶端標識碼可用來識別受控識別。

1. 請使用以下指令取得分配給使用者指派管理身份的客戶端 ID：

   az identity show \
       --resource-group <resource-group-name> \
       --name <identity-name> \
       --query clientId \
       --output tsv
   

2. 使用客戶識別碼配置 ManagedIdentityCredential：

   import com.azure.core.credential.TokenCredential;
   import com.azure.identity.DefaultAzureCredentialBuilder;
   import com.azure.identity.ManagedIdentityCredentialBuilder;
   import com.azure.security.keyvault.secrets.SecretClient;
   import com.azure.security.keyvault.secrets.SecretClientBuilder;
   
   TokenCredential credential = null;
   
   // Set up credential based on environment (Azure or local development)
   String environment = System.getenv("ENV");
   
   if (environment != null && environment.equals("production")) {
       // Specify the client ID of the user-assigned managed identity
       credential = new ManagedIdentityCredentialBuilder()
           .clientId("<user-assigned-managed-identity-client-id>")
           .build();
   } else {
       credential = new DefaultAzureCredentialBuilder()
           .build();
   }
   
   // Azure SDK client builders accept the credential as a parameter
   SecretClient client = new SecretClientBuilder()
       .vaultUrl("https://<your-key-vault-name>.vault.azure.net")
       .credential(credential)
       .buildClient();
   

資源識別碼

資源識別碼（resource ID）會使用以下結構唯一識別您 Azure 訂閱內的管理身份資源：

/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{identityName}

資源識別碼可以依慣例建置，這可讓您在環境中使用大量使用者指派的受控識別時更方便。

1. 請使用以下指令取得分配給使用者指派的管理身份的資源 ID：

   az identity show \
       --resource-group <resource-group-name> \
       --name <identity-name> \
       --query id \
       --output tsv
   

2. 使用資源識別碼設定 ManagedIdentityCredential：

   import com.azure.core.credential.TokenCredential;
   import com.azure.identity.DefaultAzureCredentialBuilder;
   import com.azure.identity.ManagedIdentityCredentialBuilder;
   import com.azure.security.keyvault.secrets.SecretClient;
   import com.azure.security.keyvault.secrets.SecretClientBuilder;
   
   TokenCredential credential = null;
   
   // Set up credential based on environment (Azure or local development)
   String environment = System.getenv("ENV");
   
   if (environment != null && environment.equals("production")) {
       // Specify the resource ID of the user-assigned managed identity
       credential = new ManagedIdentityCredentialBuilder()
           .resourceId("/subscriptions/<subscription-id>/resourcegroups/<resource-group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identity-name>")
           .build();
   } else {
       credential = new DefaultAzureCredentialBuilder()
           .build();
   }
   
   // Azure SDK client builders accept the credential as a parameter
   SecretClient client = new SecretClientBuilder()
       .vaultUrl("https://<your-key-vault-name>.vault.azure.net")
       .credential(credential)
       .buildClient();
   

物件標識碼

物件 ID 是 Microsoft Entra ID 中管理身份服務主體的唯一識別碼。 主體標識碼是物件標識碼的另一個名稱。

1. 請使用以下指令取得分配給使用者指派管理身份的物件 ID：

   az identity show \
       --resource-group <resource-group-name> \
       --name <identity-name> \
       --query principalId \
       --output tsv
   

2. 使用物件識別碼設定 ManagedIdentityCredential：

   import com.azure.core.credential.TokenCredential;
   import com.azure.identity.DefaultAzureCredentialBuilder;
   import com.azure.identity.ManagedIdentityCredentialBuilder;
   import com.azure.security.keyvault.secrets.SecretClient;
   import com.azure.security.keyvault.secrets.SecretClientBuilder;
   
   TokenCredential credential = null;
   
   // Set up credential based on environment (Azure or local development)
   String environment = System.getenv("ENV");
   
   if (environment != null && environment.equals("production")) {
       // Specify the object ID of the user-assigned managed identity
       credential = new ManagedIdentityCredentialBuilder()
           .objectId("<user-assigned-managed-identity-object-id>")
           .build();
   } else {
       credential = new DefaultAzureCredentialBuilder()
           .build();
   }
   
   // Azure SDK client builders accept the credential as a parameter
   SecretClient client = new SecretClientBuilder()
       .vaultUrl("https://<your-key-vault-name>.vault.azure.net")
       .credential(credential)
       .buildClient();
   

後續步驟

本文介紹了使用使用者指派的管理身份進行認證。 這種認證方式是 Azure SDK for Java 中多種認證方式之一。 以下文章說明其他認證方式：

• 使用系統指派的受控識別驗證 Azure 託管的 Java 應用程式以訪問 Azure 資源
• 在本地開發期間，使用開發者帳號驗證 Java 應用程式至 Azure 服務
• 在本地開發期間，使用服務主體驗證Java應用程式與Azure服務的連線

如果你遇到與Azure託管應用程式認證相關的問題，請參考 Troubleshoot Azure-hosted application authentication。