Microsoft Defender XDR APIsを使った連携を運用している管理者がまず確認すべきポイントは、Microsoft Entra アプリ登録、API権限、管理者同意、トークン取得先、古いAPIの移行予定です。2026年6月24日更新の公式ドキュメント「Access the Microsoft Defender XDR APIs」は、Microsoft Defender XDR APIsへアクセスする基本手順として「Microsoft Entraアプリの作成」「アクセストークンの取得」「トークンを使ったAPI呼び出し」を整理しています。特に、バックグラウンド処理ではApplication contextが推奨され、ユーザー操作ベースの連携ではUser context、複数テナント向けサービスではPartner contextを選ぶ設計が重要です。(Microsoft Learn)
今回の更新を「すぐに全テナントで設定変更が必要な新機能」と捉えるより、既存のAPI連携を棚卸しするタイミングと見るのが実務的です。公式ページ自体には全利用者に対する一律の移行期限は示されていませんが、関連する古いAdvanced Hunting APIやMicrosoft Graphのレガシーalerts APIには期限が明記されています。Advanced Huntingの古いエンドポイントは2027年2月1日にデータ返却を停止予定で、Microsoft Graphのレガシー/security/alertsエンドポイントは2026年8月31日に廃止予定です。(Microsoft Learn)
Microsoft Defender XDR APIsの更新ポイントを要約
Microsoft Defender XDR APIsは、インシデント管理、Advanced Hunting、イベントストリーミングなどを外部システムや自動化処理から扱うためのAPI群です。公式ドキュメントでは、Microsoft Defender XDRのデータやアクションをプログラムから利用し、ワークフロー自動化やセキュリティ運用の効率化に活用できると説明されています。(Microsoft Learn)
| 確認項目 | 管理者が見るべきポイント |
|---|---|
| 対象 | Microsoft Defender XDR APIsを使うカスタムアプリ、SIEM/SOAR連携、Power BIレポート、運用スクリプト、MSSP向けマルチテナントアプリ |
| 認証方式 | OAuth 2.0を前提に、Microsoft Entraアプリでトークンを取得してAPIを呼び出す |
| 推奨される文脈 | サインインユーザーなしで動く自動処理はApplication contextが推奨 |
| 権限設計 | APIごとに必要なApplication permissionまたはDelegated permissionを選び、管理者同意を付与する |
| 移行確認 | 古いAdvanced Hunting API、Microsoft Graphのレガシーalerts API、既存の/security/alerts利用有無を確認する |
| 運用上の注意 | シークレットの直書き、管理者同意漏れ、過剰権限、429エラー対策不足を避ける |
影響範囲：APIを使っていない組織への影響は限定的
今回の内容は、Microsoft Defenderポータルを手作業で使っているだけの組織よりも、APIでMicrosoft Defender XDRと外部システムを連携している組織に関係します。たとえば、インシデントをSIEMへ取り込む、Advanced HuntingのKQLを定期実行する、SOARで自動対応する、Power BIでカスタムレポートを作る、といった運用が対象です。Microsoft Defender XDR APIの概要では、共有インシデントやAdvanced Huntingテーブルをもとにワークフローを自動化できることが説明されています。(Microsoft Learn)
| 利用状況 | 影響の見方 |
|---|---|
| Defenderポータルだけを使っている | 直接の影響は小さい。API権限やアプリ登録の見直しは通常不要 |
| インシデントAPIを使っている | Incident.Read.AllやIncident.ReadWrite.Allなど、必要な権限と管理者同意を確認 |
| Advanced Hunting APIを使っている | 古いDefender XDR APIかMicrosoft GraphのrunHuntingQueryかを確認 |
Microsoft Graphの/security/alertsを使っている | 2026年8月31日までに/security/alerts_v2や/security/incidentsへの移行を計画 |
| 複数顧客テナント向けアプリを提供している | Partner context、マルチテナント設定、各テナントでの管理者同意を確認 |
| Power Automate、Logic Apps、Power BIで連携している | コネクタやカスタムクエリが古いエンドポイントを参照していないか確認 |
アクセス方式は3種類：Application、User、Partnerを使い分ける
Microsoft Defender XDR APIsへのアクセスは、主にApplication context、User context、Partner contextの3種類で整理されています。どれを選ぶかによって、必要なアプリ種別、権限、管理者同意、運用上の責任範囲が変わります。(Microsoft Learn)
| アクセス文脈 | 向いている用途 | 実務上の判断基準 |
|---|---|---|
| Application context | 定期実行バッチ、SIEM連携、SOAR連携、サービスアカウント型の自動処理 | サインインユーザーに依存せず、安定運用したい場合に選ぶ |
| User context | アナリスト向けツール、ユーザー操作に応じたAPI呼び出し | ユーザー本人の権限や表示範囲に合わせて結果を制御したい場合に選ぶ |
| Partner context | MSSP、SaaS型セキュリティサービス、複数顧客テナント対応アプリ | 複数テナントに同じアプリを提供し、各テナントで管理者同意を得る必要がある場合に選ぶ |
Application contextは、サインイン中のユーザーがいないバックグラウンドサービスやデーモン向けに使います。公式ドキュメントではこの文脈が推奨されており、Microsoft EntraのWebアプリ登録、必要なApplication permissionsの付与、シークレットまたは証明書によるトークン取得、BearerトークンでのAPI呼び出しという流れになります。(Microsoft Learn)
User contextは、単一ユーザーの代わりにAPI操作を行う方式です。この場合、アプリ側のDelegated permissionsだけでなく、ユーザー本人がMicrosoft Defenderポータル上で該当操作を行える権限を持っているかも重要です。公式ドキュメントでは、ポータルで操作できる権限があればAPIでもその操作を行えるという考え方が示されています。(Microsoft Learn)
Partner contextは、複数テナントにアプリを提供する場合に使います。マルチテナントのMicrosoft Entraアプリを作成し、各顧客テナントで管理者同意を得る必要があります。顧客テナントIDはトークン取得時にも必要になるため、MSSPや外部委託先が運用する場合は、同意取得手順とテナントID管理を標準化しておくべきです。(Microsoft Learn)
設定変更で確認すべきMicrosoft Entraアプリのポイント
最も見落としやすいのは、API権限を追加しただけで「使える状態になった」と誤解することです。Microsoft Defender XDR APIsでは、アプリ登録後に必要なAPI権限を選び、管理者同意を明示的に付与する必要があります。権限追加のたびに管理者同意が必要である点も公式手順に明記されています。(Microsoft Learn)
API権限の検索名に注意する
Microsoft Entra管理センターでAPI権限を追加する際、公式手順では「APIs my organization uses」からMicrosoft Threat Protectionを検索して選択します。これはMicrosoft Defender XDRの以前の名称であり、一覧に最初から表示されない場合があるため、検索ボックスに入力して探す必要があります。ここで迷うと「Defender XDR APIが見つからない」という問い合わせにつながりやすいポイントです。(Microsoft Learn)
Application permissionsとDelegated permissionsを混同しない
自動実行するアプリにはApplication permissions、ユーザーの代わりに操作するアプリにはDelegated permissionsを選びます。たとえば、インシデント一覧を取得するAPIでは、Application permissionとしてIncident.Read.AllやIncident.ReadWrite.All、Delegated permissionとしてIncident.ReadやIncident.ReadWriteが用意されています。ユーザー資格情報でトークンを取得する場合、応答にはそのユーザーが参照できるインシデントだけが含まれます。(Microsoft Learn)
Advanced Hunting APIでは、Application permissionにAdvancedHunting.Read.All、Delegated permissionにAdvancedHunting.Readが必要です。ユーザー資格情報で取得したトークンを使う場合は、ユーザーにView Dataロールが必要で、デバイスグループ設定に基づくアクセス範囲も影響します。(Microsoft Learn)
| API利用例 | 必要権限の考え方 | 注意点 |
|---|---|---|
| インシデント一覧を取得 | 読み取りだけならRead系、更新するならReadWrite系 | Delegatedではユーザーが見える範囲に結果が制限される |
| Advanced Huntingを実行 | AdvancedHunting.Read.AllまたはAdvancedHunting.Read | ユーザー文脈ではView Dataロールとデバイスグループの影響を受ける |
| 複数テナントの顧客データを処理 | マルチテナントアプリと各テナントの管理者同意 | 顧客ごとの同意状態、テナントID、権限差分を台帳化する |
| Microsoft Graphへ移行 | Graph側の権限へ変更 | Defender XDR APIの権限名とGraph APIの権限名は一致しない場合がある |
エンドポイントとトークン取得先の見直し
Microsoft Defender XDR APIsの主要APIのベースURIはhttps://api.security.microsoft.comです。パフォーマンスを考慮する場合、米国、欧州、英国向けの地域別エンドポイントも案内されています。すべての/apiパスのAPIはODataプロトコルを使用し、たとえばインシデント一覧はhttps://api.security.microsoft.com/api/incidentsで呼び出します。 (Microsoft Learn)
基本エンドポイント:
https://api.security.microsoft.com
インシデント一覧の例:
GET https://api.security.microsoft.com/api/incidents
Advanced Huntingの古いDefender XDR API例:
POST https://api.security.microsoft.com/api/advancedhunting/run
Microsoft GraphのAdvanced Hunting例:
POST https://graph.microsoft.com/v1.0/security/runHuntingQueryトークン取得時の対象リソースやスコープを間違えると、トークン自体は取得できてもAPI呼び出しで401や403になることがあります。既存スクリプトでapi.security.microsoft.com、api.securitycenter.microsoft.com、graph.microsoft.comが混在している場合は、どのAPIに対するトークンなのかを明確に分けて確認してください。
移行期限：Accessページ単体ではなく関連APIの期限を見る
「Access the Microsoft Defender XDR APIs」のページ自体は、Microsoft Defender XDR APIsへアクセスするための基本手順を説明するページです。そのため、このページだけを見て「全API利用者が特定日までに移行必須」と判断するのは早計です。一方で、関連するMicrosoft Graph security APIやAdvanced Hunting APIには、移行期限が明記されているものがあります。(Microsoft Learn)
| 対象 | 期限・状態 | 管理者の対応 |
|---|---|---|
| Access the Microsoft Defender XDR APIs | 公式ページは2026年6月24日更新。アクセス手順、認証文脈、関連APIへの導線を整理 | 既存のアプリ登録、権限、同意、シークレット、エンドポイントを棚卸し |
| 古いAdvanced Hunting API | 古いadvancedhunting/run、advancedqueries/runは2027年2月1日にデータ返却停止予定 | Microsoft Graphの/security/runHuntingQueryへ移行し、ThreatHunting.Read.AllなどGraph側の権限へ変更 |
| Microsoft Graphのレガシーalerts API | /security/alertsは2026年8月31日に廃止予定 | /security/alerts_v2または/security/incidentsへ移行し、フィールド差分と権限差分を検証 |
| Sentinel連携を含むalerts移行 | SentinelワークスペースがDefenderポータルに接続されていないとv2 APIで返らないケースがある | Sentinel接続状況、代替データソース、下流ワークフローを確認 |
Advanced HuntingをMicrosoft Graphへ移行する場合、エンドポイントだけでなく、権限、リソースURI、リクエスト本文、レスポンス構造も変わります。古いDefender XDR APIではQueryのみを送る形が中心ですが、Microsoft GraphのrunHuntingQueryではQueryに加えてTimespanを指定できます。レスポンスのプロパティ名も、Defender XDR APIのSchema、Resultsから、Graph側ではschema、resultsのように変わる点に注意が必要です。(Microsoft Learn)
管理者が今日確認すべきチェックリスト
まずは、APIを使っている箇所をすべて洗い出します。Microsoft Defender XDR連携は、セキュリティチームだけでなく、IT運用、データ分析、委託先、SOC、MSSPが個別に作ったスクリプトに分散していることがあります。Microsoft Graphのalerts移行ガイドでも、移行前に/security/alertsを呼び出している統合、スクリプト、コネクタ、下流プロセスを特定することが推奨されています。(Microsoft Learn)
| 確認対象 | 確認内容 | 失敗しやすいポイント |
|---|---|---|
| アプリ登録 | アプリID、テナントID、所有者、サポートされるアカウント種別 | 退職者が所有者のまま、誰もシークレットを更新できない |
| API権限 | ApplicationかDelegatedか、必要最小限か | 読み取りだけの用途にReadWriteを付けてしまう |
| 管理者同意 | 権限追加後にGrant admin consent済みか | 権限は追加済みだが同意がなく403になる |
| シークレット | 有効期限、保管場所、ローテーション手順 | コードや設定ファイルに平文で保存している |
| エンドポイント | Defender XDR APIかMicrosoft Graphか | トークンのaudienceとAPIの呼び出し先が一致しない |
| 移行対象 | 古いAdvanced Hunting API、/security/alertsの利用有無 | 期限直前にレスポンス差分やフィールド差分で止まる |
| 制限対策 | 429時のリトライ、ページング、実行時間 | 短時間に大量取得してクォータに達する |
| ログ | 401、403、429、5xxの記録 | 失敗理由を追跡できず、障害時に復旧が遅れる |
クォータと429対策も運用設計に入れる
Microsoft Defender XDR APIsは、セキュリティ運用の中核に入るほど呼び出し頻度が高くなります。インシデントAPIは最大50 calls/minまたは1,500 calls/hour、Advanced Hunting APIは45 calls/min、1時間あたり10分の実行時間、1日あたり4時間の実行時間という制限が案内されています。制限に達するとHTTP 429が返り、レスポンス本文に再開可能な時刻が含まれます。(Microsoft Learn)
実務では、単純な1分間隔ポーリングを複数システムで並行させると、すぐに制限へ近づきます。インシデント一覧はlastUpdateTimeなどの差分条件を活用し、同じ時間帯に同じデータを重複取得しないようにします。Advanced Huntingはクエリの対象期間と列数を絞り、レポート用の大量抽出とリアルタイム検知用の短いクエリを分けると安定しやすくなります。
シークレット管理はKey Vault前提で見直す
公式ドキュメントのサンプルではテスト用にシークレットを貼り付ける形が示されていますが、本番アプリケーションにシークレットをハードコードしないよう強く注意されています。シークレットは作成直後にしか値を再表示できないため、発行時に安全な場所へ保存し、運用ではAzure Key Vaultなどを使って管理する設計が推奨されます。(Microsoft Learn)
特にグローバル企業や複数拠点のSOCでは、シークレットの有効期限切れが検知遅延や自動対応停止につながります。最低限、次の項目を台帳化してください。
- アプリ名
- アプリケーションID
- テナントID
- 利用API
- 付与権限
- 管理者同意日
- シークレットまたは証明書の有効期限
- 所有者
- 障害時の連絡先
- ローテーション手順
既存連携の移行手順
いきなり本番のエンドポイントを置き換えるのではなく、影響範囲の小さい順に検証します。とくにMicrosoft Graphのalerts v2やincidents APIへ移行する場合、旧APIと新APIは完全な一対一の置き換えではありません。新しいalerts and incidents APIではインシデント中心のモデルになり、フィールド名や証拠情報の構造、返却されるアラート範囲が変わります。(Microsoft Learn)
| 手順 | 作業内容 | 判断基準 |
|---|---|---|
| 棚卸し | すべてのAPI呼び出し元、エンドポイント、権限、下流処理を一覧化 | 所有者不明の連携を残さない |
| 分類 | Defender XDR API継続、Graph移行、廃止候補に分ける | 期限付きAPIを優先する |
| 権限設計 | 移行後に必要なGraph権限やDefender権限を確認 | 最小権限で動くか |
| 検証 | ステージング環境で同じ期間・同じ条件の結果を比較 | 件数、重要度、ステータス、担当者、証拠情報が期待通りか |
| 下流修正 | SIEMマッピング、Power BI列名、SOAR条件分岐を修正 | フィールド名変更で自動化が壊れないか |
| 切り替え | 監視ログを有効化し、段階的に本番へ反映 | 401、403、429、データ欠損を監視 |
| 後片付け | 旧権限、旧シークレット、旧コネクタを削除 | 不要な高権限アプリを残さない |
グローバル運用での注意点
グローバル企業では、APIの呼び出し元リージョン、データ保存方針、各国拠点の管理者権限、MSSPとの責任分界を合わせて確認する必要があります。Defender XDR APIの主要APIには基本エンドポイントに加えて米国、欧州、英国向けの地域別エンドポイントが案内されていますが、利用するAPIやクラウド環境によって対応状況が異なるため、単純に全リージョンで同じ設定を横展開しないことが重要です。(Microsoft Learn)
Microsoft GraphのrunHuntingQueryは、Global service、US Government L4、US Government L5では利用可能とされる一方、中国の21Vianet環境では利用不可とされています。グローバル展開では、商用クラウド、政府機関向けクラウド、中国環境を同じ前提で設計せず、対象テナントごとにAPI対応表を確認してください。(Microsoft Learn)
まとめ：まずは「動いているAPI連携」を可視化する
Microsoft Defender XDR APIsの今回の確認ポイントは、単なるドキュメント更新の把握ではありません。API連携が増えた組織ほど、古いエンドポイント、過剰権限、期限切れシークレット、管理者同意漏れ、429対策不足が運用リスクになります。
まず実施すべきことは、既存のMicrosoft Defender連携を一覧化することです。次に、Microsoft Entraアプリの権限、管理者同意、シークレット管理、呼び出し先エンドポイントを確認します。そのうえで、古いAdvanced Hunting APIやMicrosoft Graphの/security/alertsを使っている場合は、期限から逆算してMicrosoft GraphのrunHuntingQuery、alerts_v2、incidentsへの移行計画を立ててください。
API連携は一度動くと放置されがちですが、セキュリティ運用では「止まってから気づく」状態が最も危険です。今回の更新を機に、Microsoft Defender XDR APIsの認証・権限・移行・監視をセットで見直すことが、安定したグローバルセキュリティ運用につながります。
コメント