MENU

AzureDeveloperCliCredentialのエラー解析更新｜Azure SDKで確認すべき影響と対応

Azure

Azure SDKのAzureDeveloperCliCredentialに関する今回の更新は、認証方式そのものを変えるものではありません。結論から言うと、azd auth tokenが出す新しいエラー形式を@azure/identity側で正しく読み取り、CredentialUnavailableErrorに生のJSONではなく、原因が分かるエラーメッセージを出すための修正です。ローカル開発でAzure Developer CLI、つまりazdを使って認証しているJavaScript/TypeScript開発者は、SDKの更新状況、azdのバージョン、エラーハンドリングやテストの期待値を確認しておくべきです。(GitHub)

ITtripTOOLS
その「面倒」、無料で解決。 ITtripがつくる、6つの道具。 無料ツール一覧へ すべて無料・追加課金なし
先頭0を守るCSV編集こわさないCSV PDFに直接書き込みかけるPDF 写真＋説明をPDFに写レポ スマホ⇄PCで共有コピペ便 · 文章・写真 みんなの日程を調整日程Fit 匿名質問・投票を集めるKOEQ
目次

AzureDeveloperCliCredentialの更新で何が変わるのか

今回の「AzureDeveloperCliCredential: parse new auth error formats」は、Azure SDK for JavaScriptの@azure/identityパッケージに含まれるAzureDeveloperCliCredentialのエラー解析処理に関する更新です。

AzureDeveloperCliCredentialは、Azure Developer CLIでログイン済みのユーザーまたはサービスプリンシパルを使い、ローカル開発環境からMicrosoft Entra IDのアクセストークンを取得する認証クラスです。公式ドキュメントでも、利用前にazd auth loginで認証することが案内されています。(Microsoft Learn)

今回のポイントは、次の1点に集約できます。

azd auth tokenのエラー出力形式が変わったため、Azure SDK側で新旧のJSON形式を読み分けるようにする。

これまでのAzureDeveloperCliCredentialは、古いconsoleMessage形式のJSONを前提にエラーメッセージを取り出していました。しかし、Azure Developer CLIのazd v1.23.7以降では、stderrのエラー形式が構造化された{"error":"..."}形式に変わりました。その結果、SDK側が本来表示すべきAADSTSエラーなどを抽出できず、開発者にはJSONの塊がそのまま表示されるケースがありました。(GitHub)

変更の背景：azdのエラー形式が3パターンに分かれた

今回の修正が必要になった理由は、azd auth token --output jsonのstderr形式がAzure Developer CLIのバージョンによって異なるためです。

PRでは、AzureDeveloperCliCredentialが次の3形式に対応するよう整理されています。(GitHub)

azdのバージョンstderrの主な形式以前の問題更新後の期待される動作
v1.23.7より前consoleMessage形式のJSON既存処理でおおむね解析できるdata.messageからエラー文を抽出
v1.23.7〜v1.23.15空のconsoleMessage行の後に{"error":"..."}が続く2行形式生JSONがエラーメッセージとして表示されることがあるerrorフィールドを優先して抽出
v1.24.0以降{"error":"..."}の単一行形式従来のconsoleMessage前提では解析できないerrorフィールドを抽出

実装方針としては、stderrを改行で分割し、各行をJSONとして解析できるか確認します。構造化されたerrorフィールドがあればそれを優先し、なければ従来のconsoleMessage.data.messageにフォールバックします。どちらも見つからない場合は、従来どおり生のstderrを返す設計です。(GitHub)

この設計が重要なのは、新しいazdだけに対応するのではなく、古いazdを使っている開発環境も壊さないようにしている点です。単なるログ整形ではなく、バージョン差による診断性の低下を防ぐ互換性対応と見るのが適切です。

影響を受けるパッケージと対象者

今回のPRで明示されている影響パッケージは、JavaScript/TypeScript向けの@azure/identityです。PRのファイル差分では、azureDeveloperCliCredential.ts、関連テスト、CHANGELOG.mdが更新対象になっています。(GitHub)

実務上、確認すべき対象は次のとおりです。

利用状況確認の優先度理由
new AzureDeveloperCliCredential()を直接使っている高今回の修正対象そのもの
DefaultAzureCredentialをローカル開発で使い、azd auth login済みアカウントに依存している高DefaultAzureCredential経由でAzure Developer CLI認証が使われる可能性がある
CIや開発用スクリプトでazd auth tokenを使っている中〜高エラー出力やテスト期待値が変わる可能性がある
認証エラーのmessageをログ解析・監視でパースしている高生JSONではなく、人間向けのエラー文に変わる可能性がある
本番環境でManaged IdentityやClientSecretCredentialのみ使っている低今回の修正は主にAzure Developer CLI認証のエラー解析が対象
Azure CLIのaz loginだけを使っている低対象はazではなくazd側の認証エラー形式

特に注意したいのは、DefaultAzureCredentialを使っているケースです。コード上にAzureDeveloperCliCredentialという文字列がなくても、ローカル開発時にAzure Developer CLIのログイン情報を使っている場合は、今回の変更の影響を受ける可能性があります。Azure Identityのドキュメントでは、DefaultAzureCredentialまたはAzureDeveloperCliCredentialを使うアプリケーションが、ローカル実行時にAzure Developer CLIでログインしたアカウントを利用できると説明されています。(Microsoft Learn)

すぐにアップデートが必要か

結論として、認証が正常に通っている環境では、緊急対応が必要な変更ではありません。

今回の更新は、トークン取得そのものを成功させる修正ではなく、認証に失敗したときのエラーメッセージを正しく表示するための修正です。たとえば、テナントIDの誤り、ログイン期限切れ、アカウントの権限不足などがある場合に、原因を読み取りやすくします。

一方で、次の条件に当てはまる場合は早めに確認すべきです。

  • azd v1.23.7以降を使っている
  • CredentialUnavailableErrorにJSONの塊が出て困っている
  • 認証エラーをログ収集・監視・テストで扱っている
  • チーム内でazdのバージョンが混在している
  • サポート対応や障害調査でAADSTSエラーコードを素早く見たい

なお、2026年5月7日時点でAzure SDKの最新リリース一覧では@azure/identityの安定版は4.13.1、ベータ版は4.14.0-beta.3と表示されています。一方、PR差分では修正内容が4.14.0-beta.4 (Unreleased)のCHANGELOGに追記されています。つまり、公開済みパッケージに含まれているかどうかは、実際に利用するバージョンのリリースノートとPRのマージ状況を確認して判断する必要があります。(Azure)

開発チームが確認すべきポイント

@azure/identityのバージョンを確認する

まず、プロジェクトで利用している@azure/identityのバージョンを確認します。

npm ls @azure/identity

または、パッケージマネージャーに応じて次のように確認します。

pnpm why @azure/identity
yarn why @azure/identity

モノレポや複数サービス構成では、アプリケーションごとに異なるバージョンが入っていることがあります。ルートのpackage.jsonだけでなく、実行対象のワークスペースに入っているバージョンまで確認してください。

確認時の判断基準は次のとおりです。

確認項目見るべきポイント
@azure/identityのバージョン修正が含まれるリリースか
lockファイル実際にインストールされるバージョンが固定されているか
直接依存か推移依存か他のAzure SDK経由で古い版が残っていないか
本番とローカルの差開発環境だけ古い依存関係になっていないか

Azure SDKの認証系パッケージは、他のAzureクライアントライブラリと組み合わせて使われることが多いため、「一部の開発者だけ再現する」問題が起きやすい領域です。特にpackage-lock.json、pnpm-lock.yaml、yarn.lockを共有していないプロジェクトでは、まず依存関係の固定から見直すとよいでしょう。

azdのバージョンを確認する

次に、Azure Developer CLIのバージョンを確認します。

azd version

今回のエラー形式変更は、azd v1.23.7以降が主な対象です。v1.23.7〜v1.23.15では空のconsoleMessage行とerror行が並ぶ2行形式、v1.24.0以降では単一の構造化エラー形式になることが説明されています。(GitHub)

チーム開発では、全員が同じazdバージョンを使っているとは限りません。たとえば、ある開発者は古いconsoleMessage形式、別の開発者は新しいerror形式に遭遇している可能性があります。認証エラーの再現確認では、OSやNode.jsのバージョンだけでなく、azd versionも必ず記録してください。

azdでログイン状態とトークン取得を確認する

AzureDeveloperCliCredentialで問題が出ている場合は、SDKのコードを見る前に、azd単体で認証状態を確認します。

Azure Developer CLI v1.23.0以降では、ログイン状態の確認に次のコマンドが案内されています。(GitHub)

azd auth status

古いバージョンでは、次のコマンドを使います。

azd config list

そのうえで、トークンを取得できるか確認します。

azd auth token --output json --scope https://management.core.windows.net/.default

このコマンドの出力には有効なアクセストークンが含まれる可能性があります。ログ、チャット、Issue、スクリーンショットにそのまま貼り付けないでください。公式のトラブルシューティングでも、トークン出力を共有しないよう注意されています。(GitHub)

エラーメッセージの見え方はどう変わるか

今回の修正前は、認証に失敗したときに次のような構造化JSONがそのままCredentialUnavailableErrorのメッセージとして表示されることがありました。

{"error":"fetching token: failed to authenticate:\n(invalid_tenant) ...","message":"Authentication with Azure failed.","suggestion":"Run 'azd auth login' to sign in again."}

修正後は、SDKがerrorフィールドを優先して抽出するため、開発者が本当に知りたい認証エラー本文が表示されやすくなります。PR内の検証例でも、修正前はJSON全体が表示され、修正後はAADSTSエラーを含む読みやすい文面になることが示されています。(GitHub)

実務上のメリットは大きく3つあります。

改善点実務上の効果
AADSTSエラーコードを見つけやすいテナントID誤り、ログイン期限切れ、権限不足などを早く切り分けられる
JSONノイズが減る開発者やサポート担当者がログを読みやすくなる
azdの複数バージョンに対応チーム内でCLIバージョンが混在しても診断しやすい

ただし、注意点があります。これは認証失敗の根本原因を解消する修正ではありません。tenantIdが誤っている、対象サブスクリプションにアクセス権がない、azd auth loginが期限切れになっている、といった問題そのものは別途対応が必要です。

移行・設定確認の進め方

まずは「更新が必要な環境」を絞り込む

すべてのAzure SDK利用プロジェクトで即時対応が必要なわけではありません。次の順で対象を絞り込みましょう。

手順確認内容判断
1@azure/identityを使っているか使っていなければ対象外
2AzureDeveloperCliCredentialまたはDefaultAzureCredentialをローカル開発で使っているか使っていれば確認対象
3azd v1.23.7以降を使っているか使っていれば影響を受けやすい
4認証エラー時にJSONが表示されるか表示されるなら修正版の適用候補
5エラーメッセージをテストや監視で比較しているか期待値修正が必要になる可能性あり

この順で確認すると、不要なライブラリアップデートを避けながら、問題が起きやすい箇所に集中できます。

SDK更新時はリリースノートを確認する

今回のPRは、@azure/identityのAzureDeveloperCliCredentialに関する不具合修正です。ただし、利用する時点でどのバージョンに含まれるかは、実際のリリースノートで確認する必要があります。PRの差分では4.14.0-beta.4 (Unreleased)のCHANGELOGに追記されていますが、リリース済みかどうかはnpmやAzure SDK Releasesの掲載状況と照合してください。(GitHub)

アップデートする場合は、次のように依存関係を明示的に更新します。

npm install @azure/identity@latest

ベータ版を検証する場合は、安定版と混同しないよう、検証用ブランチや検証環境で試すのが安全です。

npm install @azure/identity@next

実務では、いきなり全サービスで更新するのではなく、認証エラーが再現している開発用アプリやテスト用プロジェクトで先に確認するのがおすすめです。

エラーハンドリングはJSON前提にしない

今回の変更で特に見直したいのが、エラーメッセージの扱いです。

避けたい実装は、error.messageをJSONとして解析するコードです。

// 避けたい例
try {
  await credential.getToken(scope);
} catch (error: any) {
  const parsed = JSON.parse(error.message);
  console.log(parsed.error);
}

修正後は、error.messageがすでに人間が読めるエラー文になっている可能性があります。JSON前提の処理は失敗しやすくなります。

実務では、次のように「表示用メッセージ」として扱う方が安全です。

try {
  await credential.getToken(scope);
} catch (error) {
  if (error instanceof Error) {
    console.error("Azure authentication failed:", error.message);
  } else {
    console.error("Azure authentication failed:", error);
  }
}

監視やログ分析でAADSTSコードを拾う場合も、JSON構造ではなく、文字列内のAADSTSコードを正規表現で検出するなど、形式変更に強い方法を選ぶとよいでしょう。

テストで見直すべき箇所

今回のPRでは、parseAzdStderrに対して新しい形式、古い形式、複数行形式、プレーンテキスト形式を扱うテストが追加されています。(GitHub)

自社プロジェクトでも、次のようなテストがある場合は見直しが必要です。

テストの種類見直すポイント
認証エラーのスナップショットテスト生JSONを期待していないか
CredentialUnavailableErrorのメッセージ比較完全一致ではなく、重要なエラーコードや文言の部分一致にできないか
CLI stderrをモックするテストconsoleMessage形式だけでなく、error形式も試しているか
障害調査ログの検証JSON全体ではなく、AADSTSコードやtenant IDの有無を確認しているか

特にスナップショットテストでは、今回のような「正しい改善」によってテストが落ちることがあります。エラー文の全文一致は壊れやすいため、次のような観点で期待値を設計してください。

expect(error.message).toContain("AADSTS");
expect(error.message).not.toContain('"type":"consoleMessage"');

全文一致よりも、「原因が読めるか」「不要なJSONが露出していないか」を検証する方が、今回の修正意図に合っています。

トラブルシューティング時の実用チェックリスト

AzureDeveloperCliCredentialで認証エラーが出たら、次の順で確認すると無駄な切り分けを減らせます。

確認コマンド・観点期待する状態
Azure Developer CLIが入っているかazd versionバージョンが表示される
ログイン済みかazd auth status対象アカウントが確認できる
トークン取得できるかazd auth token --output json --scope ...トークン取得に成功する
SDKバージョンnpm ls @azure/identity修正を含むバージョンか確認できる
テナント指定tenantIdや環境変数想定するMicrosoft Entraテナントを指している
ログAZURE_LOG_LEVEL=infoなどどのCredentialが試行されたか追える

Azure Identityのトラブルシューティングでは、Azure Developer CLIが未インストールの場合、PATHに含まれていない場合、azd auth loginが未実行または期限切れの場合が代表的な原因として案内されています。(GitHub)

よくある勘違いと注意点

Azure CLIのazとAzure Developer CLIのazdを混同しない

AzureCliCredentialが使うのはaz、AzureDeveloperCliCredentialが使うのはazdです。

az loginに成功していても、azd auth loginが済んでいなければAzureDeveloperCliCredentialは期待どおり動かないことがあります。逆に、azd auth login済みでも、Azure CLI側のaz account showとは状態が異なる場合があります。

認証エラーの調査では、どちらのCredentialを使っているのかを最初に確認してください。

今回の修正は権限不足を直すものではない

今回の更新は、エラーの表示を改善するものです。次のような根本原因は、別途対応が必要です。

原因対応例
テナントIDが誤っているtenantId、環境変数、azdのログイン先を確認
サブスクリプション権限がないRBACロールや対象サブスクリプションを確認
ログイン期限切れazd auth loginを再実行
サービスプリンシパルの資格情報が誤っているclient ID、secret、tenant IDを確認
対象スコープが誤っているAzureサービスに合ったscopeを指定

エラー文が読みやすくなっても、認証失敗の原因が消えるわけではありません。むしろ、読みやすくなったエラーコードをもとに、権限やテナント設定を正しく直すための更新と捉えるべきです。

ログにアクセストークンを残さない

azd auth token --output jsonの確認は有効ですが、出力にはアクセストークンが含まれる可能性があります。トークンは資格情報そのものなので、Issue、チャット、CIログ、スクリーンショットに貼らないでください。公式トラブルシューティングでも、トークン出力を共有しないよう明記されています。(GitHub)

ログ収集基盤にCLI出力を送っている場合は、トークン文字列をマスクする設定も確認しましょう。

他のAzure SDK言語版との関係

今回のPRはJavaScript/TypeScript向けの@azure/identityが対象ですが、同じ問題は複数のAzure SDK言語版でも扱われています。関連PRとして、Go版、.NET版、Python版の対応が参照されています。Go版では同種の修正が2026年4月21日にマージされ、Python版も関連PRとしてマージ済みと表示されています。(GitHub)

複数言語でAzure SDKを使っているチームでは、JavaScriptだけでなく、Go、.NET、Pythonなどの認証エラーの見え方も揃っていく可能性があります。ただし、各言語のリリース時期や含まれるバージョンは異なるため、言語ごとのリリースノートを個別に確認してください。

実務での対応方針

今回のAzure SDK更新に対して、開発チームは次のように動くのが現実的です。

状況対応
認証は成功しており、エラー調査にも困っていない直ちに対応しなくてもよい。次回の定期アップデートで確認
JSON形式のエラーメッセージが表示されて困っている修正版を含む@azure/identityのリリースを確認し、検証環境で更新
azd v1.23.7以降をチームで使っているSDK更新の影響を確認し、テスト期待値を見直す
エラーメッセージを監視やテストでパースしているJSON前提の処理をやめ、文字列として扱う
複数言語のAzure SDKを使っている言語ごとの修正状況とリリースバージョンを確認

読み終えた後にまずやるべきことは、azd versionとnpm ls @azure/identityの確認です。次に、認証エラーが出る環境でazd auth statusとazd auth tokenを使い、CLI単体でトークン取得できるかを確認します。そのうえで、修正版の@azure/identityが利用可能になっているかを見て、必要な環境から段階的にアップデートしてください。

今回の更新は派手な機能追加ではありませんが、認証エラーの調査時間を短縮する実用的な修正です。特にAzure Developer CLIをローカル開発の認証基盤として使っているチームでは、「エラーが読める状態」を保つために、SDKとCLIのバージョンをセットで管理することが重要です。

Azure
Azure SDK Azure Developer CLI AzureDeveloperCliCredential @azure/identity

この記事を書いた人

佐藤健司のアバター 佐藤健司

実務の現場で詰まりがちなポイントを地図にするITブログ「IT trip」を運営。Windows／Office（Teams・Excel）からSQL、サーバ運用、ガジェットまで、再現性のある手順と“なぜそうなるか”を丁寧に解説します。読んだらすぐ試せること、そして迷った人の次の一歩が見えることを大切にしています。

関連記事

コメント

コメントする

目次