Azure でホストされるアプリケーション認証のトラブルシューティング

  • [アーティクル]

この記事では、さまざまな TokenCredential 実装を通じて、Azure でホストされる 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 は、マネージド ID を提供するさまざまな Azure ホストで動作するように設計されています。 マネージド ID の構成とエラーのトラブルシューティングは、ホストによって異なります。 次の一覧は、マネージド ID を割り当てることができ、ManagedIdentityCredential がサポートする Azure ホスト環境を示しています。

Azure 仮想マシンのマネージド ID

ManagedIdentityCredential を使用する場合は、必要に応じて、CredentialUnavailableException を試行/キャッチします。 次の表に、この例外が示すエラーと軽減策を示します。

エラー メッセージ 説明 対応策
The requested identity hasn't been assigned to this resource. Azure Instance Metadata Service (IMDS) エンドポイントは、要求された ID が仮想マシン (VM) に割り当てられていないことを示す状態コード 400 で応答しました。 ユーザー割り当て ID を使用している場合は、指定した clientId が正しいことを確認します。

システム割り当て ID を使用している場合は、正しく有効にしていることを確認します。 詳細については、「Azure Portal を使用して VM 上の Azure リソースのマネージド ID を構成する」の「既存の VM でシステム割り当てマネージド ID を有効にする」セクションを参照してください。
The request failed due to a gateway error. ゲートウェイ エラー 502 または 504 状態コードが原因で、IMDS エンドポイントへの要求が失敗しました。 IMDS では、プロキシまたはゲートウェイ経由の呼び出しはサポートされていません。 IMDS エンドポイント http://169.254.169.254/ への呼び出しに対して VM で実行されているプロキシまたはゲートウェイを無効にする
No response received from the managed identity endpoint. IMDS への要求に対する応答が受信されなかったか、要求がタイムアウトしました。 - VM でマネージド ID が正しく構成されていることを確認します。 詳細については、「Azure portal を使用して VM で Azure リソースのマネージド ID を構成する」を参照してください。
- VM で IMDS エンドポイントに到達可能であることを確認します。 詳細については、次のセクションを参照してください。
Multiple attempts failed to obtain a token from the managed identity endpoint. IMDS エンドポイントからトークンを取得するための再試行が上限に達しました。 - 特定のエラーの詳細については、「内部例外メッセージ」を参照してください。 データが切り捨てられている場合は、ログを収集することでさらに詳細を取得できます。
- VM でマネージド ID が正しく構成されていることを確認します。 詳細については、「Azure portal を使用して VM で Azure リソースのマネージド ID を構成する」を参照してください。
- VM で IMDS エンドポイントに到達可能であることを確認します。 詳細については、次のセクションを参照してください。

IMDS が VM で利用できることを確認する

VM にアクセスできる場合は、次の例に示すように、curl を使用して、コマンド ライン経由でマネージド ID エンドポイントを使用できることを確認できます。

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 のマネージド ID

ManagedIdentityCredential を使用する場合は、必要に応じて、CredentialUnavailableException を試行/キャッチします。 次の表に、この例外が示すエラーと軽減策を示します。

エラー メッセージ 説明 対応策
ManagedIdentityCredential authentication unavailable. App Services ホストが構成した環境変数は存在しません。 - App Service インスタンスでマネージド ID が正しく構成されていることを確認します。 詳細については、「App Service と Azure Functions でマネージド ID を使用する方法」を参照してください。
- App Service Environment が適切に構成されていること、およびマネージド ID エンドポイントが使用可能であることを確認します。 詳細については、次のセクションを参照してください。

App Service マネージド ID エンドポイントが使用可能であることを確認する

App Service インスタンスへの SSH アクセス権がある場合は、マネージド ID が環境内で使用可能であることを確認できます。 まず、環境内で環境変数 MSI_ENDPOINT と MSI_SECRET が設定されていることを確認します。 次の例に示すように、curl を使用して、マネージド ID エンドポイントが使用可能であることを確認できます。

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 マネージド ID

Kubernetes のポッド ID

ManagedIdentityCredential を使用する場合は、必要に応じて、CredentialUnavailableException を試行/キャッチします。 次の表に、この例外が示すエラーと軽減策を示します。

エラー メッセージ 説明 対応策
No Managed Identity endpoint found アプリケーションは、ID がポッドに割り当てられる前に認証を試みました。 ポッドに正しいラベルが付されていることを確認します。 この問題は、ID の準備が整う前に、正しくラベル付けされたポッドが認証されるときにも発生します。 初期化競合を防ぐには、応答で Retry-After ヘッダーを設定するように NMI を構成します。 詳細については、ポッド ID ドキュメントの「NMI 応答 で Retry-After ヘッダーを設定する」を参照してください。

WorkloadIdentityCredential のトラブルシューティング

WorkloadIdentityCredential を使用する場合は、必要に応じて、CredentialUnavailableException を試行/キャッチします。 次の表に、この例外が示すエラーと軽減策を示します。

エラー メッセージ 説明 対応策
WorkloadIdentityCredential authentication unavailable. The workload options aren't fully configured. WorkloadIdentityCredentialは、Microsoft Entra ID を認証するために clientId、tenantId および tokenFilePath を必要とします。 DefaultAzureCredential を使用している場合は、次のようにします。
- クライアント ID が、workloadIdentityClientId セッターまたは AZURE_CLIENT_ID 環境変数で指定されていることを確認します。
- AZURE_TENANT_ID 環境変数を介して、テナント ID が指定されていることを確認します。
- AZURE_FEDERATED_TOKEN_FILE 環境変数を介して、トークン ファイル パスが指定されていることを確認します。
- AZURE_AUTHORITY_HOST 環境変数を介して、機関ホストが指定されていることを確認します。

WorkloadIdentityCredential を使用している場合は、次のようにします。
- 資格情報ビルダーの tenantId セッターまたは AZURE_TENANT_ID 環境変数を介して、テナント ID が指定されていることを確認します。
- 資格情報ビルダーの clientId セッターまたは AZURE_CLIENT_ID 環境変数を介して、クライアント ID が指定されていることを確認します。
- 資格情報ビルダーの tokenFilePath セッターまたは AZURE_FEDERATED_TOKEN_FILE 環境変数を介して、トークン ファイル パスが指定されていることを確認します。
- その他の問題については、「製品のトラブルシューティング ガイド」を参照してください。

次のステップ

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