MENU

Azure SDKのMSAL追加クエリパラメータ対応とは？AdditionalQueryParametersの影響と確認ポイント

Azure

2026年5月5日のAzure SDK for .NET更新では、TokenCredentialOptionsに実験的なAdditionalQueryParametersが追加され、Azure Identityの認証処理からMSALへ追加クエリパラメータを渡せるようになりました。結論から言うと、通常のDefaultAzureCredentialやマネージドIDを使っているだけなら、すぐにコード変更する必要はありません。一方で、Microsoft Entraの特殊な認証フロー、Azure PowerShell連携、Agentic Sessions、InteractiveBrowserCredentialなどのMSALベース認証で独自パラメータが必要な開発チームは、Azure.Coreのバージョン、キャッシュキー設定、実験的APIの扱いを確認すべきです。今回の変更はPR #58939として2026年5月5日にマージされ、関連Issue #58921を解決するものです。(GitHub)

目次

Azure SDKのMSAL追加クエリパラメータ対応で何が変わったのか

今回の変更の中心は、Azure SDK for .NETの認証オプションであるTokenCredentialOptionsに、追加クエリパラメータを指定するためのAdditionalQueryParametersが加わったことです。Azure.Core 1.55.0のCHANGELOGにも、TokenCredentialOptionsへ実験的なAdditionalQueryParametersプロパティを追加し、認証時にMSALへ追加クエリ文字列パラメータを転送できるようにした、と記載されています。(GitHub)

この機能は、Microsoft Entra IDへの認証リクエストに、通常のAzure SDK認証では付与されないクエリパラメータを追加したい場合に使います。元のIssueでは、任意のクエリ文字列パラメータをMSAL .NETのWithExtraQueryParametersへ転送するための実験的プロパティとして提案され、Azure PowerShellなどの利用者がMicrosoft Entra Agentic Sessionsをサポートする用途が例示されています。(GitHub)

ただし、これは認証処理を便利にする汎用カスタマイズ機能というより、特定の認証フローで明示的に必要になった場合に使う拡張ポイントです。PR本文でも「first iteration」であり、Experimental機能として導入され、今後の実装で設計が変わる可能性があると説明されています。(GitHub)

変更点の要点

項目内容実務での確認ポイント
追加されたAPITokenCredentialOptions.AdditionalQueryParametersAzure.Core 1.55.0以降を参照しているか確認する
対象MSALに裏付けられたAzure Identity資格情報すべてのcredentialで効く前提にしない
目的Microsoft Entra認証リクエストに追加クエリパラメータを付与認証要件で必要な場合だけ使う
キャッシュ制御各パラメータをトークンキャッシュキーに含めるか指定可能トークン内容や有効性に影響するパラメータは慎重に判断する
安定性Experimentalラッパー化し、将来のAPI変更に備える
リリースAzure.Core 1.55.0NuGetやCentral Package Managementの固定バージョンを確認する

PRの概要では、AdditionalQueryParametersはMSAL-backed credential pipelineに接続され、MSALのbuilderへWithExtraQueryParameters経由で渡されると説明されています。また、オプションのdeep copy、snapshot、null/empty値の扱いに関するテストも追加されています。(GitHub)

対応が必要な人、確認だけでよい人

この更新はAzure SDK利用者全員に影響するものではありません。まず、現在の認証方式と、追加クエリパラメータが本当に必要かを切り分けてください。

利用状況対応方針
通常のDefaultAzureCredentialでKey Vault、Storage、App Configurationなどへ接続している基本的にコード変更は不要。依存パッケージ更新時のビルド確認で十分
Microsoft Entra認証リクエストに独自クエリパラメータを付ける要件があるAdditionalQueryParametersの導入を検討する
Azure PowerShellや独自ライブラリでAzure Identity credentialをラップしているオプションのclone、snapshot、キャッシュ挙動をテストする
InteractiveBrowserCredentialなど、対話型・ブローカー連携の認証を使っている必要なパラメータが認証リクエストに付与されるか確認する
マネージドID中心で、追加認証パラメータの要件がない対応不要。ただしAzure.Coreの更新影響は通常どおり確認する
Java、Python、JavaScriptなど.NET以外のAzure SDKを使っているこのPRはAzure SDK for .NETの変更として扱う。別言語へ同じ仕様があると決めつけない

重要なのは、「Azure SDKに新機能が入ったから使う」ではなく、「認証プロバイダーや上位機能の要件として追加クエリパラメータが必要だから使う」という順序で判断することです。

AdditionalQueryParametersは何を指定するプロパティか

AdditionalQueryParametersは、パラメータ名をキーにし、値とキャッシュキーへ含めるかどうかのフラグを持つ辞書として扱われます。MSAL側のWithExtraQueryParametersにも、IDictionary<string, (string Value, bool IncludeInCacheKey)>を受け取るオーバーロードがあり、追加パラメータをHTTP認証リクエストのクエリ文字列へ付与し、各パラメータをトークンキャッシュキー計算に含めるか制御できます。(Microsoft Learn)

実装イメージは次のようになります。実際のパラメータ名と値は、Microsoft Entraや利用するサービス、ライブラリ側のドキュメントで指定されたものを使ってください。

using Azure.Identity;

#pragma warning disable AZID0001 // AdditionalQueryParameters is experimental

var options = new InteractiveBrowserCredentialOptions
{
    TenantId = "<tenant-id>",
    ClientId = "<client-id>"
};

options.AdditionalQueryParameters["<required-param-name>"] =
    (Value: "<required-param-value>", IncludeInCacheKey: true);

#pragma warning restore AZID0001

var credential = new InteractiveBrowserCredential(options);

DefaultAzureCredentialOptionsにも継承関係上は指定できますが、追加クエリパラメータが必要な認証フローが明確なら、まずはInteractiveBrowserCredentialなど対象のcredentialに絞って設定するのが安全です。DefaultAzureCredentialのチェーンに広く設定すると、どのcredentialで有効になり、どのcredentialで無視されるのかが分かりにくくなります。

IncludeInCacheKeyの判断基準

今回の変更で特に注意すべきなのが、IncludeInCacheKeyです。MSALのドキュメントでは、パラメータがトークンの内容や有効性に影響する場合、正しいトークンをキャッシュから返すためにIncludeInCacheKeyをtrueにすべきと説明されています。(Microsoft Learn)

判断の目安は次のとおりです。

判断例理由
trueにするパラメータの違いによって、返るトークンのclaims、利用条件、セッション、対象リソースが変わる異なる条件のトークンを同じキャッシュとして扱うと、誤ったトークンを再利用する恐れがある
falseを検討する表示やリクエスト補助だけに使われ、トークン内容に影響しないパラメータキャッシュキーに含めると、不要にキャッシュが分断される可能性がある
判断できない仕様書や提供元の説明がなく、トークンへの影響が不明提供元に確認する。安易にfalseへ倒さない

失敗しやすいのは、「キャッシュヒット率を上げたいからfalseにする」という判断です。認証パラメータがトークンの内容や有効性に関わる場合、キャッシュヒット率よりも正しいトークンを返すことが優先されます。逆に、何でもtrueにするとキャッシュが細かく分かれ、対話型認証の回数やトークン取得回数が増える可能性があります。

Azure.Core 1.55.0への更新確認

NuGet GalleryではAzure.Core 1.55.0が公開されており、.NET CLIでは次の形式で追加できます。NuGetページ上ではAzure.Core 1.55.0が.NET 8.0、.NET Standard 2.0、.NET Framework 4.6.2などを対象にしていることも確認できます。([NuGet][5])

dotnet add package Azure.Core --version 1.55.0

Central Package Managementを使っている場合は、Directory.Packages.propsも確認してください。

<ItemGroup>
  <PackageVersion Include="Azure.Core" Version="1.55.0" />
</ItemGroup>

現在解決されているバージョンは、次のコマンドで確認できます。

dotnet list package --include-transitive

Windows環境で絞り込みたい場合は、次のように確認できます。

dotnet list package --include-transitive | findstr Azure.Core

macOSやLinuxでは次のように確認します。

dotnet list package --include-transitive | grep Azure.Core

Azure.Coreは多くのAzure SDKクライアントライブラリから推移的に参照されます。明示的にAzure.Coreを更新していなくても、別パッケージの更新でバージョンが変わることがあります。特に大規模な.NETプロジェクトでは、アプリ本体、共通ライブラリ、テストプロジェクトでAzure.Coreのバージョンが意図せず分かれていないか確認してください。

移行時に確認すべきポイント

追加パラメータが本当に必要か確認する

AdditionalQueryParametersは、認証リクエストをカスタマイズするための強力な入口です。しかし、通常の認証エラーを回避するために独自パラメータを入れる用途には向きません。

まず確認すべきことは次の3つです。

確認項目見るべき内容
仕様上の要件Microsoft Entra、対象サービス、上位ライブラリのドキュメントで追加パラメータが明示されているか
対象credentialそのcredentialがMSAL-backedとして扱われ、追加パラメータを受け取る経路に乗るか
キャッシュ影響パラメータ差分で返るトークンが変わるか

PRの説明でも、この機能はMSAL-backed credentialsでのみ尊重されるとされています。つまり、すべてのAzure Identity credentialに同じように効くわけではありません。(GitHub)

Experimental警告を雑に消さない

APIには実験的機能であることを示す属性が付いており、API surface上でもExperimentalAttribute("AZID0001")が確認できます。(GitHub)

警告を消す場合は、プロジェクト全体でまとめて無効化するより、利用箇所を限定して抑制する方が安全です。

#pragma warning disable AZID0001
options.AdditionalQueryParameters["<required-param-name>"] =
    (Value: "<required-param-value>", IncludeInCacheKey: true);
#pragma warning restore AZID0001

このように範囲を絞れば、将来ほかの実験的APIを誤って使ったときに気づきやすくなります。

credential生成後に変更しても反映される前提にしない

PRでは、AdditionalQueryParametersのdeep copyやsnapshotに関するテストが追加されています。これは、共有された可変dictionaryによる副作用を避けるための実装です。(GitHub)

そのため、次のような書き方は避けてください。

var options = new InteractiveBrowserCredentialOptions();
var credential = new InteractiveBrowserCredential(options);

// 生成後に追加しても、期待どおり反映される前提にしない
options.AdditionalQueryParameters["<required-param-name>"] =
    (Value: "<required-param-value>", IncludeInCacheKey: true);

基本は、credentialを生成する前に必要なパラメータをすべて設定します。

var options = new InteractiveBrowserCredentialOptions();

#pragma warning disable AZID0001
options.AdditionalQueryParameters["<required-param-name>"] =
    (Value: "<required-param-value>", IncludeInCacheKey: true);
#pragma warning restore AZID0001

var credential = new InteractiveBrowserCredential(options);

機密情報をクエリパラメータに入れない

追加クエリパラメータは、認証リクエストのURLに付与される可能性があります。アクセストークンそのものではなくても、URL、プロキシ、診断ログ、ブラウザ履歴、監査ログなどに残る可能性を考慮してください。

特に避けるべきものは次のとおりです。

入れてはいけない情報理由
シークレット、APIキー、パスワードURLやログに残るリスクが高い
個人情報認証ログや監査ログの取り扱いが難しくなる
長大なJSONや状態情報URL長制限やログ肥大化の原因になる
仕様で定義されていない独自値認証エラーや将来の互換性問題を招く

追加パラメータが必要な場合でも、値は最小限にし、ログ出力や監査ルールも併せて見直してください。

テストで見るべき観点

本番導入前には、単に「ビルドが通る」だけでなく、認証リクエストとトークンキャッシュの挙動を確認します。

テスト観点確認内容
リクエスト付与認証リクエストに必要なパラメータが含まれるか
キャッシュ分離IncludeInCacheKey: trueにしたパラメータを変えたとき、誤ったトークンが再利用されないか
キャッシュ効率falseでよいパラメータをtrueにして、不要な再認証が増えていないか
null/empty値空値を渡した場合の挙動がアプリ要件と合うか
credential差分InteractiveBrowserCredential、DefaultAzureCredentialなど、実際に使うcredentialごとに期待どおりか
ログ追加パラメータが不要にログへ残っていないか

PRでも、MSAL builderへの転送、snapshot、null/empty値の扱いを確認するテストが追加されています。実務でも、これに近い観点で回帰テストを用意すると安全です。(GitHub)

実装判断のおすすめフロー

AdditionalQueryParametersを使うか迷った場合は、次の順で判断してください。

順序判断内容結果
1追加クエリパラメータが公式仕様や上位機能の要件に明記されているか明記がなければ使わない
2利用するcredentialがMSAL-backedで、この機能の対象か対象外なら別の実装方法を検討
3パラメータがトークン内容や有効性に影響するか影響するならIncludeInCacheKey: trueを検討
4Experimental APIを受け入れられるか将来変更に備えてラッパー化
5テストとロールバック手段があるかない場合は本番適用を急がない

実務では、次のように小さなヘルパーに閉じ込めると、将来API名や型が変わった場合の修正範囲を限定できます。

using Azure.Identity;

public static class CredentialOptionsExtensions
{
    public static void AddRequiredAuthParameter(
        this TokenCredentialOptions options,
        string name,
        string value,
        bool includeInCacheKey)
    {
#pragma warning disable AZID0001
        options.AdditionalQueryParameters[name] =
            (Value: value, IncludeInCacheKey: includeInCacheKey);
#pragma warning restore AZID0001
    }
}

利用側は次のように書けます。

var options = new InteractiveBrowserCredentialOptions
{
    TenantId = "<tenant-id>",
    ClientId = "<client-id>"
};

options.AddRequiredAuthParameter(
    name: "<required-param-name>",
    value: "<required-param-value>",
    includeInCacheKey: true);

var credential = new InteractiveBrowserCredential(options);

Experimental APIをアプリ全体に散らばらせないことが、今回の更新を安全に取り込む最大のポイントです。

よくある疑問

Azure.Core 1.55.0に上げれば全員が対応する必要がありますか

いいえ。追加クエリパラメータを使わない通常のAzure SDK利用では、基本的にコード変更は不要です。Azure.Core 1.55.0の機能追加として存在しますが、使わなければ認証リクエストに独自パラメータは付与されません。(GitHub)

どのcredentialでも有効ですか

いいえ。PRの説明では、この機能はMSAL-backed credentialsでのみ尊重されるとされています。マネージドIDや開発ツール連携など、認証経路によっては追加パラメータが反映されない場合があります。(GitHub)

MSALのWithExtraQueryParametersを直接呼ぶ必要がありますか

Azure Identity credentialを使っているアプリでは、通常は直接MSAL builderを操作しません。今回の変更は、Azure SDK側のTokenCredentialOptionsからMSAL側のWithExtraQueryParametersへ渡すための入口です。MSALのAPI自体には、追加パラメータを認証リクエストへ付与し、キャッシュキーへの含有可否を制御するオーバーロードがあります。(Microsoft Learn)

本番環境で使ってもよいですか

必要性が明確で、テストとロールバック手段がある場合に限定して使うのが現実的です。PRでは、この機能が最初のイテレーションでありExperimentalとして導入され、将来の実装で設計が変わる可能性があるとされています。(GitHub)

今回の更新で取るべき次のアクション

今回のAzure SDK documentation updateで確認すべきことは、AdditionalQueryParametersを使うかどうかではなく、自分のアプリの認証要件に「MSALへ追加クエリパラメータを渡す必要」があるかどうかです。

まず、dotnet list package --include-transitiveでAzure.Coreの解決バージョンを確認してください。次に、Microsoft Entra認証で独自パラメータを必要とする機能を使っているかを確認します。該当する場合は、AdditionalQueryParametersをcredential生成前に設定し、IncludeInCacheKeyを仕様に基づいて判断し、Experimental APIを局所的に扱う実装にします。

通常のAzure SDK利用者にとっては大きな移行作業ではありません。しかし、認証フローを拡張しているライブラリ作者や社内共通基盤の担当者にとっては、キャッシュキー、ログ、credentialごとの差分を見落とすとトラブルにつながる変更です。必要な場所だけに導入し、将来のAPI変更に備えて薄いラッパーとテストを用意しておくのが安全です。

[5]: https://www.nuget.org/packages/Azure.Core/1.55.0 “
NuGet Gallery
| Azure.Core 1.55.0
“

Azure
MSAL Microsoft Entra Azure SDK Azure.Core Azure.Identity

この記事を書いた人

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

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

関連記事

コメント

コメントする

目次