マルチテナント対応のEntra IDアプリ登録をSPFx向けにマスターする

By Mirko Peters · 2026-08-11

ポッドキャストへようこそ。自分の開発テナントで丹精込めて作ったSharePoint Framework (SPFx)ソリューションを、顧客環境へ展開しようとしたことがあるなら、完全に動かなくなったときのあの血の気が引く感覚はご存じでしょう。何も表示されない。Webパーツが空っぽ。ログインのループが止まらない。テナントをまたぐ認証は、Microsoft 365開発者にとって究極の試金石であり、正しく行うには、Entra IDアプリ登録、動的スコープ、最小特権のセキュリティを深く理解する必要があります。

Automatically translated with AI from the original post. Read the English original

Titelbild: Mastering Multi-Tenant Entra ID App Registrations for SPFx

この詳細ガイドでは、最新のエピソードで話した内容をさらに掘り下げます。音声での解説をさらに詳しく聞きたい方は、Fix Multi-Tenant SPFx Authenticationをご覧ください。

はじめに: マルチテナントのSPFxが難易度高めな理由

SPFxアプリケーションをIDの境界をまたいで移行することは、「ハードモード」と表現されることがよくあります。それには十分な理由があります。単一テナント内で開発している場合、Entra ID、SharePointサイトの構造、APIのアクセス許可は、ほぼ暗黙的に扱われるか、グローバル管理者権限によって簡単に回避できます。しかし、マルチテナントモデルに足を踏み入れた瞬間――Webパーツを製品化するISV(独立系ソフトウェアベンダー)であれ、複数の子会社テナントを管理する社内ITチームであれ――そうした近道は消えてしまいます。

これからは、厳格なディレクトリの境界、明示的な管理者承認を必要とする同意の仕組み、そして固有のサイト構成と向き合うことになります。アプリ登録が単一テナントに固定されていたり、コードがハードコードされた環境パラメーターに依存していたりすれば、本番環境へのデプロイは確実に失敗します。

対象読者

技術的な仕組みに入る前に、このアーキテクチャのパターンを習得すべき人を確認しておきましょう。

複数のテナントに提供するSPFx開発者およびMicrosoft 365コンサルタント。顧客ごとのデプロイで手作業による再設定を避けたい方。
顧客のSharePoint Online環境をサポートするIT管理者およびMSP。最新の開発者ソリューションを有効にしながら、厳格なセキュリティ体制を維持する必要がある方。
SPFxのWebパーツおよび拡張機能を製品化するパートナーおよびISV。数百の異なる顧客テナントに対して、再現可能でスケーラブルな市場投入の方法を必要とする方。

重要なポイント

マルチテナント展開をうまく進めるために、次の中核となる原則をアーキテクチャの中心に据えてください。

認証は定型コードではない: マルチテナントのEntra IDアプリを使用し、テナントごとに管理者の同意を必須にしてください。これらのセキュリティ状態は実行時に検証します。
テナントの詳細をハードコードしない: URL、ID、スコープはテナントを認識する構成ソースから動的に読み込み、バックエンドで必要なシークレットは Azure Key Vault に安全に保管してください。
Graphの「空の結果」は、コードの破損を意味しない: Microsoft Graphが空の配列を返す場合、ほとんどは同意の不足、またはディレクトリのデータやフィルターの不一致が原因であり、コードベースの構文エラーではありません。
1つのパッケージで多数のテナントに対応: SPFxソリューションは完全にテナントに依存しない設計にし、テナント単位のデプロイと組み合わせて、顧客ごとのカスタムビルドを不要にしてください。
障害を早期に把握する: Application Insights や Azure Monitor を使い、テナントごとに調整したテレメトリとヘルスチェックを一元化してください。

ハイライト

技術的な検討を通じて、開発ライフサイクルで必ず対処すべきいくつかの重要なマイルストーンに触れました。

テナントをまたぐ展開を失敗させる3つの認証上の誤り。単一テナントのアプリ登録、一度だけの同意という誤解、そしてクライアント側のコードへのシークレットの埋め込みです。
Microsoft Graphが開発テナントではスムーズに動作するのに、顧客環境ではまったく結果を返さない理由と、本番公開前にそれを検証する方法。
一度パッケージ化して、どこでも構成する。真にテナントに依存しないSPFxのためのアーキテクチャ設計図。
顧客が気づく前に、サイレントな構成の問題を捕捉するログとモニタリングの戦略。
提供のスピードを保ちながら、組織のコンプライアンスを維持するガバナンスの仕組み。

Entra ID アプリ登録
- サポートされているアカウントの種類: マルチテナントを設定します。
- 最小特権の原則に従い、必要な委任 Graph スコープを正確に定義します。
- SharePoint Online とローカル開発環境の両方に対応する、有効なリダイレクト URIを設定します。
SPFx プロジェクトの強化
- 委任された API 呼び出しには、すべてMSGraphClientまたはAadHttpClientを使用します。
- テナントごとの構成情報（エンドポイントや対象サイト ID など）は、専用の SharePoint 構成リストまたは安全な API から読み込みます。フロントエンドのコードにシークレットを一切含めないようにします。
- 実行時にアクセス許可を確認し、アクセス許可が不足している場合は、直接リンクを含む「管理者の同意が必要です」バナーを適切に表示する仕組みを実装します。
同意のフロー
- 必要なスコープ、正確な管理者同意 URL、検証手順を表示する、テナント向けのオンボーディング専用ページを用意します。
- 組織全体への展開と対象を絞ったパイロットグループとを区別し、対象ユーザーごとの同意モデルに対応します。
パッケージ化と展開
- ソリューションは標準の .sppkg ファイルとして一度だけパッケージ化し、適切な場合はテナント単位の展開を有効にします。
- 中央のアプリカタログから公開し、サイト単位での追加手順を十分に文書化します。
- ビルド、バンドル、パッケージ化、アップロード、展開までを含む堅牢な CI/CD パイプラインを使用して、リリースサイクルを自動化します。
監視とサポート
- テナント ID、相関 ID、対象の機能、エラーコードを含む詳細なテレメトリを出力します。
- Application Insights または Azure Monitor のダッシュボードを設定し、対応可能なアラートを併せて構成します。
- 以前のパッケージバージョンを使用したロールバック手順を明確に文書化し、テナントごとの詳細なバージョンマップも用意します。

よくある問題と対処法

マルチテナントアプリケーションの構成では、経験豊富な開発者でも決まったパターンの問題に陥ることがあります。以下に、すばやく原因を特定して解決する方法を示します。

症状: サインインがループする、または「自分の環境では動くのに、相手の環境では動かない」という厄介な状況になります。
原因: Entra ID のアプリ登録がまだシングルテナントに設定されているか、返信 URL が対象環境と一致していません。
対処: アプリ登録をマルチテナントに切り替え、リダイレクト URI を修正したうえで、新たに同意を要求します。
症状: Microsoft Graph から空のデータセットしか返ってきません。
原因: テナント管理者による同意が行われていないか、ディレクトリのフィルターが厳しすぎます。
対処: 適切な管理者同意のフローを実行し、顧客テナントの実ユーザーを使って Graph Explorer でクエリを直接テストします。そのうえで、コード内の厳しすぎる前提条件やフィルターを緩和します。
症状: ユーザーがページに Web パーツを追加できません。
原因: パッケージがテナントのアプリカタログに正しく展開されていないか、組織のアプリポリシーによってブロックされています。
対処: アプリカタログへの展開状態を確認し、テナントのアプリ設定とポリシーを確認します。
症状: 顧客ごとに、軽微な構成変更のたびにパッケージを再ビルドする必要があります。
原因: ID、URL、シークレットがバンドルに直接埋め込まれています。
対処: 構成を外部化し、SharePoint 構成リストまたは Azure Key Vault に保存して、実行時に動的に値を読み込みます。

ガバナンスとセキュリティの基本

外部の顧客ディレクトリにコードを展開する際、セキュリティは後回しにできません。信頼を維持するため、以下のガバナンスの基本事項を実装してください。

最小特権のスコープを徹底し、定期的にスコープを見直して、使われていないアクセス許可を削除します。
バックエンドアプリケーションのシークレットは Azure Key Vault に安全に保存し、定期的なローテーションの計画を立てます。
Teams と SharePoint のアプリアクセス許可ポリシーを活用して、対象ユーザーを厳密に絞り込み、不正な利用を防ぎます。
誰がいつ同意し、どのスコープが承認されたかを記録する、包括的な同意台帳を管理します。
テナント固有のスタイル資産をコードに含めるのではなく、Microsoft 365 テーマ API を通じて Web パーツのブランディングを動的に反映させます。

検証計画（顧客への本番公開前）

十分な検証を行わずに展開しないでください。ソリューションを顧客に提示する前に、以下の検証計画を実施します。

顧客テナント内で、まったく同じユーザーアカウントと委任スコープを使用し、Graph Explorer ですべての Microsoft Graph 呼び出しをテストします。
対象を絞った少人数のユーザーとともに、独立した 1 つのサイトコレクションでローカライズしたパイロット展開を実施します。
SharePoint App Catalog内で、バージョン履歴とロールバック機能を直接確認してください。
オフライン状態や有効期限切れのトークンのシナリオを試し、エラーメッセージと自動復旧のフローが想定どおりに動作するかを確認してください。

よくある質問

SPFxにはアプリケーションのアクセス許可が必要ですか?
通常は不要です。SPFxソリューションは委任されたユーザーのコンテキストで実行されます。アプリケーションのアクセス許可には追加の管理者承認と専門的なアーキテクチャのパターンが必要になるため、ほかに現実的な選択肢がない場合にのみ使用してください。

テナントごとの同意を省略できますか?
いいえ。各クライアントテナントの管理者が、アプリケーションが要求するスコープを明示的に付与する必要があります。ただし、ガイド付きのオンボーディング画面や、実行時に表示するプロアクティブな通知バナーを作成することで、このプロセスを大幅に効率化できます。

1つのコードベースで多数のクライアントに対応するには?
ソリューションをテナントに依存しない形で作成し、環境ごとの構成をすべて外部化して、パッケージングとデプロイのパイプラインを自動化してください。クライアントごとの切り替えは、フィーチャーフラグを使うと安全に管理できます。

「データが表示されない」問題をより早く診断するには?
Graphの生の応答を、スコープの検証チェックとあわせてログに記録してください。障害が発生した際には、「同意がない、またはスコープが不足しています」と表示するインライン通知を出し、問題をすぐに修正できる直接のディープリンクを添えてください。

まとめ

SharePoint Framework ソリューション向けのマルチテナント Entra ID アプリ登録を使いこなせるかどうかが、趣味のスクリプトとエンタープライズ級のソフトウェア製品を分けるポイントです。テナントに依存しないパッケージング、動的な構成の読み込み、堅牢な実行時の同意検証へと考え方を切り替えることで、サイレントなデプロイ失敗を防ぎ、すべてのクライアントにスムーズな体験を届けられます。

これらのソリューションの背景にある実際の経験談や設計上の判断について詳しく知りたい方は、関連するポッドキャストのエピソードもぜひご覧ください: Fix Multi-Tenant SPFx Authentication。お読みいただきありがとうございます。コーディングを楽しんでください。