Azure ID 認証に関する問題のトラブルシューティング

この記事では、エラー調査手法、Azure Identity Java クライアント ライブラリの資格情報の種類に関する一般的なエラー、およびこれらのエラーを解決するための軽減手順について説明します。 JavaのAzure SDKでは多くの資格情報の種類を使用できるため、このトラブルシューティング ガイドは使用シナリオに基づいてセクションに分かれています。 次のセクションがあります。

この記事の残りの部分では、すべての資格情報の種類に適用される一般的なトラブルシューティング手法とガイダンスについて説明します。

Azure ID 例外の処理

トラブルシューティングの概要のJavaセクションのAzure SDKの例外処理で説明したように、JavaのAzure SDKは、例外とエラー コードの包括的なセットをスローできます。 具体的には、Azure ID では、いくつかの主要な例外の種類を理解することが重要です。

ClientAuthenticationException

サービスに対する要求を行うサービス クライアントメソッドは、認証エラーから例外を発生させることができます。 これらの例外は、サービスへの最初の呼び出し時と、トークンを更新する必要があるサービスへの後続の要求で、資格情報からトークンが要求されるために発生する可能性があります。

これらのエラーとサービス クライアントのエラーを区別するために、Azure ID クラスでは、例外メッセージ内のエラーの原因と場合によってはエラー メッセージを記述する詳細を含む 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 などのチェーン資格情報の種類に対しても、チェーン資格情報がチェーン内の後続の他の資格情報の種類を引き続き試行すべきことを示します。

アクセス許可の問題

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 エラー コードに関するセクションを参照してください。

  • 関連付け ID とタイムスタンプ: サーバー側のログで要求を識別するために使用される関連付け ID と呼び出しのタイムスタンプ。 この情報は、予期しない STS エラーの診断時にエンジニアをサポートするのに役立ちます。

ログ記録を有効にして構成する

JavaのAzure SDKでは、アプリケーション エラーのトラブルシューティングと解決の迅速化に役立つ、一貫したログ記録のストーリーが提供されます。 ログは、ルートの問題の特定に役立つターミナル状態に到達する前に、アプリケーションのフローをキャプチャします。 ログ記録のガイダンスについては、 Azure SDK for Java でのログ記録の構成 とビュー のトラブルシューティングに関するページを参照してください。

基になる MSAL ライブラリ MSAL4J にも詳細なログ記録があります。 このログ記録は非常に詳細であり、トークンを含むすべての個人データが含まれます。 このログは、製品サポートを使用する場合に最も役立ちます。 v1.10.0 の時点で、このログ記録を提供する資格情報には、 enableUnsafeSupportLogging()というメソッドがあります。

注意事項

Azure ID ライブラリの要求と応答には、機密情報が含まれています。 アカウントのセキュリティを損なわないように出力をカスタマイズする場合は、ログを保護する予防措置を講じる必要があります。

次のステップ

この記事のトラブルシューティング ガイダンスで、Java クライアント ライブラリのAzure SDKを使用するときに問題を解決できない場合は、Java GitHub リポジトリのAzure SDKに問題を提出してください。

  • Last updated on