疑難排解 Azure Identity 驗證問題

本文涵蓋失敗調查技術、Azure Identity Java 用戶端連結庫中認證類型的常見錯誤，以及解決這些錯誤的風險降低步驟。 由於 Azure SDK for Java 中有許多憑證類型可供選擇，本故障排除指南依使用情境分為多個章節。 以下是可用的區段：

本文的其餘部分涵蓋適用於所有認證類型的一般疑難解答技術和指引。

處理 Azure 身分識別例外狀況

如同故障排除總覽中 Azure SDK for Java 例外處理部分所述，Azure SDK for Java 可以拋出一組完整的例外與錯誤代碼。 針對 Azure Identity，有幾種關鍵例外類型很重要。

ClientAuthenticationException

任何向服務提出請求的服務客戶端方法，都可能因認證錯誤而產生例外。 這些例外可能會發生，因為在第一次呼叫服務時，以及在後續任何需要重新整理權杖的服務要求中，都需要從憑證要求權杖。

為了區分這些失敗與用戶端中的失敗，Azure 身分識別類別會引發 ClientAuthenticationException 並附上詳細資料，在例外狀況訊息中描述錯誤來源，並可能包含錯誤訊息。 視應用程式而定，這些錯誤可能可被恢復。 下列程式代碼顯示擷取 ClientAuthenticationException的範例：

// Create a secret client using the DefaultAzureCredential
SecretClient client = new SecretClientBuilder()
    .vaultUrl("https://myvault.vault.azure.net/")
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildClient();

try {
    KeyVaultSecret secret = client.getSecret("secret1");
} catch (ClientAuthenticationException e) {
    //Handle Exception
    e.printStackTrace();
}

憑證不可用例外

CredentialUnavailableException 是衍生自 ClientAuthenticationException的特殊例外狀況類型。 使用此例外類型表示憑證因缺乏必要的設定或設定，無法在目前環境中進行認證。 此例外同時也指示鏈式憑證類型（如 DefaultAzureCredential 和 ChainedTokenCredential），該鏈式憑證應繼續嘗試鏈中後續的其他憑證類型。

許可權問題

對服務客戶端的呼叫若導致 HttpResponseException，且其 StatusCode 為 401 或 403，通常表示呼叫者沒有足夠的權限來存取指定的 API。 請檢查服務檔，以判斷特定要求需要哪些角色。 確保已認證的使用者或服務主體在資源上獲得適當的角色。

在例外狀況訊息中尋找相關信息

ClientAuthenticationException當憑證在驗證過程中發生意外錯誤時，會拋出例外。 這些錯誤可能包括來自 Microsoft Entra 安全憑證服務（STS）的請求錯誤，且通常包含有助於診斷的資訊。 請考慮下列 ClientAuthenticationException 訊息：

ClientSecretCredential authentication failed: A configuration issue is preventing authentication - check the error message from the server for details. You can modify the configuration in the application registration portal. See https://aka.ms/msal-net-invalid-client for details.

Original exception:
AADSTS7000215: Invalid client secret provided. Ensure the secret being sent in the request is the client secret value, not the client secret ID, for a secret added to app 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'.
Trace ID: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
Correlation ID: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
Timestamp: 2022-01-01 00:00:00Z

此錯誤訊息包含下列資訊：

  • 失敗的認證類型：無法驗證的認證類型 ─ 在此案例中為 ClientSecretCredential。 診斷鏈結認證類型的問題時，這項資訊很有用，例如 DefaultAzureCredential 或 ChainedTokenCredential。

  • STS 錯誤代碼與訊息：來自 Microsoft Entra STS 的錯誤代碼與訊息——在此情況下，AADSTS7000215: Invalid client secret provided.此資訊提供了請求失敗的具體原因。 例如，在這個特定案例中，提供的客戶端秘密是錯誤的。 如需 STS 錯誤碼的詳細資訊，請參閱 Microsoft Entra 驗證和授權錯誤碼的 AADSTS 錯誤碼一節。

  • 相互關聯標識碼和時間戳：用來識別伺服器端記錄中要求的相互關聯標識碼和呼叫時間戳。 這項資訊有助於在診斷非預期的 STS 失敗時支持工程師。

啟用和設定記錄

Azure SDK for Java 提供一致的日誌故事，協助排除應用程式錯誤並加速解決。 日誌記錄應用程式在到達終端狀態前的流程，以協助找出根本問題。 如需記錄的指引，請參閱 在 Azure SDK for Java 中設定記錄 和 疑難解答概述。

基礎函式庫 MSAL4J 也具有詳細的記錄功能。 這些日誌內容繁複，包含所有個人資料，包括代幣。 使用產品支援時，此記錄最實用。 從 v1.10.0 起，提供此記錄的認證具有稱為 enableUnsafeSupportLogging()的方法。

謹慎

Azure 身分識別連結庫中的要求和回應包含敏感性資訊。 在自訂輸出時，請採取防護措施保護日誌，以避免帳號安全受到威脅。

後續步驟

如果本文的故障排除指引無法幫助你解決使用Azure SDK Java客戶端函式庫的問題，請在Java GitHub儲存庫的Azure SDK中提出問題。

  • Last updated on