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

[アーティクル]
11/10/2023

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

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

Azure Identity 例外の処理

「トラブルシューティングの概要」の「Azure SDK for Java での例外処理」セクションで記載されている通り、Azure SDK for Java がスローできる例外とエラーコードの包括的なセットがあります。特に Azure Identity の場合、理解しなければならない主要な例外の種類がいくつかあります。

ClientAuthenticationException

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

これらのエラーとサービスクライアントのエラーを区別するため、Azure Identity クラスは、例外メッセージと場合によってはエラーメッセージで記載されているエラーのソースが説明されている詳細と一緒に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 など) へのシグナルとしても使用されます。その連鎖された資格情報は、連鎖の後の方で、他の資格情報の種類を再試行し続けなければなりません。

アクセス許可の問題

401 または 403 の StatusCode が HttpResponseException の結果となるサービスクライアントへの呼び出しは、多くの場合、呼び出し元が指定された API に対する十分なアクセス許可を持っていないことを示します。サービスドキュメントを確認して、特定の要求に必要なロールを決定します。認証されたユーザーまたはサービスプリンシパルに、リソースに対する適切なロールが付与されていることを確認します。

例外メッセージで関連情報を見つける

ClientAuthenticationException は、資格情報の認証中に予期しないエラーが発生したときにスローされます。これらのエラーには、Microsoft Entra security token service (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 エラーの診断時にエンジニアをサポートするのに役立ちます。

ログ記録の有効化と構成

Azure SDK for Java では、アプリケーションエラーをトラブルシューティングして、その解決を促進するために、一貫したログ記録が提供されます。生成されたログにより、最終状態に達する前のアプリケーションのフローが取得され、根本原因を特定するのに役立ちます。ログ記録のガイダンスについては、「トラブルシューティングの概要」の「Azure SDK for Java でログ記録を構成する」を参照してください。

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

注意事項

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

次のステップ

この記事のトラブルシューティングガイダンスが、Azure SDK for Java クライアントライブラリを使用するときの問題の解決に役立たない場合は、Azure SDK for Java GitHub リポジトリに問題を提出することをお勧めします。

次の方法で共有