針對 Azure 身分識別驗證問題進行疑難排解

發行項
12/13/2023

本文涵蓋失敗調查技術、Azure Identity Java 用戶端連結庫中認證類型的常見錯誤，以及解決這些錯誤的風險降低步驟。由於 Azure SDK for Java 中有許多可用的認證類型，因此我們已根據使用案例，將疑難解答指南分割成各節。以下是可用的區段：

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

處理 Azure 身分識別例外狀況

如疑難解答概觀的 Azure SDK for Java 一節中的例外狀況處理所述，Azure SDK for Java 可以擲回的一組完整的例外狀況和錯誤碼。具體來說，對於 Azure 身分識別，有一些重要的例外狀況類型需要瞭解。

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

CredentialUnavailableException 是衍生自 ClientAuthenticationException的特殊例外狀況類型。此例外狀況類型可用來指出認證無法在目前的環境中驗證，因為缺少必要的組態或設定。此例外狀況也會作為鏈結認證類型的訊號，例如 DefaultAzureCredential 和 ChainedTokenCredential，鏈結認證應該會繼續在鏈結中嘗試其他認證類型。

權限問題

對服務用戶端的呼叫會產生 HttpResponseExceptionStatusCode 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 失敗時支持工程師。

啟用和設定記錄

適用於 Java 的 Azure SDK 提供一致的記錄案例，可協助針對應用程式錯誤進行疑難解答，並協助加速解決。產生的記錄會在到達終端狀態之前，先擷取應用程式流程來協助尋找根本問題。如需記錄的指引，請參閱在 Azure SDK for Java 中設定記錄和透過檢視進行疑難解答。

基礎 MSAL 連結庫 MSAL4J 也有詳細的記錄。此記錄功能非常詳細，並包含所有個人資料，包括令牌。使用產品支援時，此記錄最實用。從 v1.10.0 起，提供此記錄的認證具有稱為 enableUnsafeSupportLogging()的方法。

警告

Azure 身分識別連結庫中的要求和回應包含敏感性資訊。自定義輸出時，您必須採取預防措施來保護記錄，以避免危害帳戶安全性。

下一步

如果本文中的疑難解答指引無法協助您在使用適用於 Java 的 Azure SDK 用戶端連結庫時解決問題，建議您在適用於 Java 的 Azure SDK GitHub 存放庫中提出問題。

Share via