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

2025-04-17

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

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

Azure ID 例外の処理

トラブルシューティングの概要に関する Azure SDK for Java セクションの例外処理に記載されているように、Azure SDK for Java でスローできる例外とエラーコードの包括的なセットがあります。具体的には、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 エラーの診断時にエンジニアをサポートするのに役立ちます。

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

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

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

注意事項

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

次のステップ

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