針對 Azure 裝載的應用程式驗證進行疑難解答

  • 發行項

本文提供透過各種 TokenCredential 實作驗證 Azure SDK for Java 應用程式時所遇到的問題指引。 如需詳細資訊，請參閱 驗證 Azure 裝載的 Java 應用程式。

針對 DefaultAzureCredential 進行疑難解答

當您使用 DefaultAzureCredential時，可以選擇性地嘗試/攔截 CredentialUnavailableException。 下表顯示此例外狀況所指出的錯誤，以及風險降低的方法：

錯誤訊息 描述 風險降低
CredentialUnavailableException raised with message "DefaultAzureCredential failed to retrieve a token from the included credentials." 鏈結中的所有 DefaultAzureCredential 認證都無法擷取令牌，每個認證都會擲回 CredentialUnavailableException。 啟用記錄 以驗證所嘗試的認證，並取得進一步的診斷資訊。

如需詳細資訊，請參閱下列其中一種基礎認證類型的疑難解答指南：
- EnvironmentCredential
- ManagedIdentityCredential
- VisualStudioCodeCredential
- AzureCLICredential
- AzurePowershellCredential
HttpResponseException raised from the client with a status code of 401 or 403 驗證成功，但授權的 Azure 服務以 401（驗證）或 403（禁止）狀態代碼回應。 當驗證預期的帳戶或預定帳戶沒有指派正確的許可權或角色時 DefaultAzureCredential ，通常會發生此問題。 啟用記錄 以判斷鏈結中傳回驗證令牌的認證。

如果預期以外的認證傳回令牌，請註銷對應的開發工具，以略過此問題。

請確定已將正確的角色指派給所使用的帳戶。 例如，服務特定的角色，而不是訂用帳戶擁有者角色。

針對 EnvironmentCredential 進行疑難解答

當您使用 EnvironmentCredential時，可以選擇性地嘗試/攔截 CredentialUnavailableException。 下表顯示此例外狀況所指出的錯誤，以及風險降低的方法：

錯誤訊息 描述 風險降低
Environment variables aren't fully configured. 未設定有效的環境變數組合。 請確定已針對預定的驗證方法在應用程式啟動之前設定適當的環境變數，如下列清單所述：
- 若要使用用戶端密碼驗證服務主體，請確定 AZURE_CLIENT_ID變數、 AZURE_TENANT_ID和 AZURE_CLIENT_SECRET 已正確設定。
- 若要使用憑證驗證服務主體，請確定已正確設定變數 AZURE_CLIENT_ID、 AZURE_TENANT_ID、 AZURE_CLIENT_CERTIFICATE_PATH和 AZURE_CLIENT_CERTIFICATE_PASSWORD 。
- 若要使用密碼驗證使用者，請確定變數 AZURE_USERNAME 和 AZURE_PASSWORD 已正確設定。

針對 ManagedIdentityCredential 進行疑難解答

ManagedIdentityCredential 設計用來處理提供受控識別的各種 Azure 主機。 設定受控識別和疑難解答失敗會因主機而異。 下列清單顯示您可以指派受控識別和支援 ManagedIdentityCredential 的 Azure 主機環境：

Azure 虛擬機器受控身分識別

當您使用 ManagedIdentityCredential時，可以選擇性地嘗試/攔截 CredentialUnavailableException。 下表顯示此例外狀況所指出的錯誤，以及風險降低的方法：

錯誤訊息 描述 風險降低
The requested identity hasn't been assigned to this resource. Azure 實例元數據服務 （IMDS） 端點會以狀態代碼 400 回應，指出要求的身分識別未指派給虛擬機 （VM）。 如果您使用使用者指派的身分識別，請確定指定的 clientId 是正確的。

如果您使用系統指派的身分識別，請確定您已正確啟用它。 如需詳細資訊，請參閱使用 Azure 入口網站 為 VM 上的 Azure 資源設定受控識別中的現有 VM 上啟用系統指派的受控識別一節。
The request failed due to a gateway error. IMDS 端點的要求因為閘道錯誤、502 或 504 狀態代碼而失敗。 IMDS 不支援透過 Proxy 或閘道呼叫。 停用在 VM 上執行的 Proxy 或閘道，以呼叫 IMDS 端點 http://169.254.169.254/
No response received from the managed identity endpoint. 未收到 IMDS 要求或要求逾時的要求回應。 - 確定您已在 VM 上正確設定受控識別。 如需詳細資訊，請參閱使用 Azure 入口網站 在 VM 上設定 Azure 資源的受控識別。
- 確認 VM 上可連線 IMDS 端點。 如需詳細資訊，請參閱 下一節。
Multiple attempts failed to obtain a token from the managed identity endpoint. 從 IMDS 端點擷取令牌的重試已用盡。 - 如需特定失敗的詳細資訊，請參閱內部例外狀況訊息。 如果數據已被截斷，可以藉由 收集記錄來取得更多詳細數據。
- 確定您已在 VM 上正確設定受控識別。 如需詳細資訊，請參閱使用 Azure 入口網站 為 VM 上的 Azure 資源設定受控識別。
- 確認 VM 上可連線 IMDS 端點。 如需詳細資訊，請參閱 下一節。

確認 VM 上是否提供 IMDS

如果您有 VM 的存取權，您可以使用 來確認已受管理身分識別端點是否可透過命令列使用 curl，如下列範例所示：

curl 'http://169.254.169.254/metadata/identity/oauth2/token?resource=https://management.core.windows.net&api-version=2018-02-01' -H "Metadata: true"

警告

此命令的輸出包含有效的存取令牌。 為了避免危害帳戶安全性，請勿共用此存取令牌。

Azure App Service 和 Azure Functions 受控身分識別

當您使用 ManagedIdentityCredential時，可以選擇性地嘗試/攔截 CredentialUnavailableException。 下表顯示此例外狀況所指出的錯誤，以及風險降低的方法：

錯誤訊息 描述 風險降低
ManagedIdentityCredential authentication unavailable. App Services 主機所設定的環境變數不存在。 - 請確定您已在 App Service 實例上正確設定受控識別。 如需詳細資訊，請參閱 如何使用App Service和 Azure Functions 的受控識別。
- 確認您已正確設定 App Service 環境，且受控識別端點可供使用。 如需詳細資訊，請參閱 下一節。

確認 App Service 受控識別端點可供使用

如果您能夠存取 SSH 到 App Service 實例，您可以確認受控識別可在環境中使用。 首先，請確定您已在環境中設定環境變數 MSI_ENDPOINT 和 MSI_SECRET 。 然後，您可以使用 來驗證受控識別端點是否可用 curl，如下列範例所示：

curl 'http://169.254.169.254/metadata/identity/oauth2/token?resource=https://management.core.windows.net&api-version=2018-02-01' -H "Metadata: true"

警告

此命令的輸出包含有效的存取令牌。 為了避免危害帳戶安全性，請勿共用此存取令牌。

Azure Kubernetes Service 受控識別

Kubernetes 的 Pod 身分識別

當您使用 ManagedIdentityCredential時，可以選擇性地嘗試/攔截 CredentialUnavailableException。 下表顯示此例外狀況所指出的錯誤，以及風險降低的方法：

錯誤訊息 描述 風險降低
No Managed Identity endpoint found 應用程式嘗試在將身分識別指派給其 Pod 之前進行驗證。 確認 Pod 已正確標示。 當已正確標記的Pod在身分識別就緒之前進行驗證時，也會發生此問題。 若要防止初始化競爭，請將 NMI 設定為在其回應中設定 Retry-After 標頭。 如需詳細資訊，請參閱 Pod 身分識別檔中的 NMI 回應 中設定 Retry-After 標頭。

針對 WorkloadIdentityCredential 進行疑難解答

當您使用 WorkloadIdentityCredential時，可以選擇性地嘗試/攔截 CredentialUnavailableException。 下表顯示此例外狀況所指出的錯誤，以及風險降低的方法：

錯誤訊息 描述 風險降低
WorkloadIdentityCredential authentication unavailable. The workload options aren't fully configured. WorkloadIdentityCredentialclientId需要 和 tenantIdtokenFilePath ，才能使用 Microsoft Entra ID 進行驗證。 如果您使用 DefaultAzureCredential，則：
- 確定已透過 workloadIdentityClientId setter 或 AZURE_CLIENT_ID 環境變數指定用戶端識別碼。
- 確定已透過 AZURE_TENANT_ID 環境變數指定租使用者標識碼。
- 請確定您已透過 AZURE_FEDERATED_TOKEN_FILE 環境變數指定令牌檔案路徑。
- 確定授權單位主機是透過 AZURE_AUTHORITY_HOST 環境變數指定。

如果您使用 WorkloadIdentityCredential，則：
- 確定租使用者標識碼是透過 tenantId 認證產生器或 AZURE_TENANT_ID 環境變數上的 setter 來指定。
- 確定用戶端識別碼是透過 clientId 認證產生器或 AZURE_CLIENT_ID 環境變數上的 setter 來指定。
- 確定令牌檔案路徑是透過 tokenFilePath 認證產生器或 AZURE_FEDERATED_TOKEN_FILE 環境變數上的 setter 來指定。
- 如需其他問題，請參閱 產品疑難解答指南。

下一步

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