共用方式為

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

本文涵蓋失敗調查技術、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 是衍生自 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 失敗時支持工程師。

啟用和設定記錄

適用於 Java 的 Azure SDK 提供一致的記錄案例，可協助針對應用程式錯誤進行疑難解答，並協助加速解決。 記錄會在到達最終狀態之前捕捉應用程式的運行流程，以協助找出根本問題。 如需記錄的指引，請參閱 在 Azure SDK for Java 中設定記錄 和 疑難解答概述。

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

謹慎

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

後續步驟

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

  • Last updated on