承認と Microsoft Graph セキュリティ API
Microsoft Graph Security APIを介してアクセス可能なセキュリティ データは、アクセス許可とMicrosoft Entraロールの両方によって機密性が高く保護されています。
Microsoft Graph セキュリティ API では 2 種類の承認がサポートされています。
アプリケーション レベルの承認: サインインしているユーザーがいません (例: SIEM シナリオ)。 アプリケーションに付与されたアクセス許可によって、承認が決定します。
注:
このオプションは、アプリケーションがロール ベースのアクセス制御 (RBAC) を管理しているケースにも対応します。
ユーザー委任承認:Microsoft Entra テナントのメンバーであるユーザーがサインインしています。 ユーザーは、アプリケーションに必要なアクセス許可が付与されているだけでなく、Microsoft Entra ID制限付き管理ロール (セキュリティ閲覧者またはセキュリティ管理者) のメンバーである必要があります。
Graph エクスプローラーから Microsoft Graph セキュリティ API を呼び出す場合:
Microsoft Entra テナント管理者は、Graph エクスプローラー アプリケーションに対して、要求されたアクセス許可に対する同意を明示的に付与する必要があります。
ユーザーは、Microsoft Entra IDのセキュリティ閲覧者制限付き管理ロール (セキュリティ閲覧者またはセキュリティ管理者) のメンバーである必要があります。
注:
Graph エクスプローラーでは、アプリケーション レベルの承認がサポートされていません。
カスタム アプリケーションまたは独自のアプリケーションから Microsoft Graph セキュリティ API を呼び出す場合:
- Microsoft Entra テナント管理者は、アプリケーションに明示的に同意を付与する必要があります。 これは、アプリケーション レベルの承認と、ユーザーにより委任された承認の両方に必要です。
- ユーザー委任承認を使用している場合、ユーザーは、Microsoft Entra IDのセキュリティ閲覧者ロールまたはセキュリティ管理者制限付き管理ロールのメンバーである必要があります。
セキュリティ API クライアント アプリケーションで承認を管理する
Microsoft Graph セキュリティ API から提供されるセキュリティ データは機密性が高く、適切な認証および承認メカニズムを使用して保護する必要があります。 次の表に、Microsoft Graph セキュリティ API にアクセスできるクライアント アプリケーションを登録および作成する手順を示します。
| 対象者 | 操作 |
|---|---|
| アプリケーション開発者または所有者 | アプリケーションをエンタープライズ アプリケーションとして登録します。 |
| テナント管理者 | アプリケーションにアクセス許可を付与します。 |
| テナント管理者 | ユーザーにロールを割り当てます。 |
| アプリケーション開発者 | ユーザーとしてサインインし、アプリケーションを使用して Microsoft Graph セキュリティ API にアクセスします。 |
アプリケーションの登録では、アプリケーションの実行に必要なアクセス許可だけが定義されます。 これらのアクセス許可はアプリケーションに付与されません。
Microsoft Entraテナント管理者は、アプリケーションにアクセス許可を明示的に付与する必要があります。 これはテナントごとに実行し、またアプリケーション登録ポータルでアプリケーションのアクセス許可が変更されるたびに実行する必要があります。
たとえば、アプリケーション、T1 と T2 の 2 つのMicrosoft Entra テナントと、P1 と P2 の 2 つのアクセス許可があるとします。 承認プロセスを以下に示します。
アプリケーションがアクセス許可 P1 を必要とすることが登録されます。
テナント T1 のユーザーがこのアプリケーションのMicrosoft Entra トークンを取得すると、トークンにアクセス許可は含まれません。
テナント T1 のMicrosoft Entra管理者は、アプリケーションに対するアクセス許可を明示的に付与します。 テナント T1 のユーザーがアプリケーションのMicrosoft Entra トークンを取得すると、アクセス許可 P1 が含まれます。
テナント T2 のユーザーがアプリケーションのMicrosoft Entra トークンを取得すると、テナント T2 の管理者がまだアプリケーションにアクセス許可を付与していないため、トークンにアクセス許可は含まれません。 アクセス許可はテナントごとおよびアプリケーションごとに付与する必要があります。
アプリケーションの登録が変更され、アクセス許可 P1 と P2 が必要になりました。
テナント T1 のユーザーがアプリケーションのMicrosoft Entra トークンを取得すると、アクセス許可 P1 のみが含まれます。 アプリケーションに付与されたアクセス許可は、付与された内容のスナップショットとして記録されます。アプリケーションの登録 (アクセス許可) を変更しても、アクセス許可は 自動的には変更されません。
テナント T2 の管理者がアクセス許可 P1 と P2 をアプリケーションに付与します。 これで、テナント T2 のユーザーがアプリケーションのMicrosoft Entra トークンを取得すると、トークンにはアクセス許可 P1 と P2 が含まれます。
注:
テナント T1 内のアプリケーションとテナント T2 内のアプリケーションのMicrosoft Entra トークンには、各テナント管理者がアプリケーションに対して異なるアクセス許可を付与しているため、異なるアクセス許可が含まれています。
アプリケーションをテナント T1 で再び実行できるようにするには、テナント T1 の管理者が、アクセス許可 P1 と P2 をアプリケーションに明示的に付与する必要があります。
Microsoft ID プラットフォーム エンドポイントにアプリケーションを登録する
Microsoft ID プラットフォーム エンドポイントにアプリケーションを登録するには、次のものが必要です。
- アプリケーション名: アプリケーション名として使用される文字列。
- リダイレクト URL:Microsoft Entra IDからの認証応答が送信される URL。 最初に、テスト クライアント Web アプリケーション ホーム ページを使用できます。
- 必要なアクセス許可: アプリケーションが Microsoft Graph を呼び出すことができるようにするために必要なアクセス許可。
アプリケーションを登録するには、次の操作を行います。
Azure アプリ登録ポータルに移動してサインインします。
注:
テナント管理者である必要はありません。[マイ アプリケーション] リストにリダイレクトされます。
[新規登録] を選択します。
新しいアプリケーションの登録ページで [名前]の値を入力し、サポートするアカウントの種類を選択します。 [リダイレクト URL] フィールドにリダイレクト URL を入力します。
[登録] を選択してアプリを作成し、アプリの概要ページを表示します。 *
アプリの [API のアクセス許可] ページに移動します。
[アクセス許可を追加する] を選択し、ポップアップで [Microsoft Graph] を選択します。 [委任されたアクセス許可] を選択します。 検索ボックスを使用して、必要なアクセス許可を検索して選択します。 アクセス許可のリストについては、「セキュリティのアクセス許可」を参照してください。
注:
Microsoft Graph セキュリティ API では、GET クエリに *.Read.All スコープ、PATCH/POST/DELETE クエリに *.ReadWrite.All スコープが必要です。
アクセス許可 エンティティ サポートされている要求 SecurityActions.Read.All • securityActions (プレビュー) GET SecurityActions.ReadWrite.All • securityActions (プレビュー) GET、POST SecurityEvents.Read.All • アラート • secureScores • secureScoreControlProfiles 取得 SecurityEvents.ReadWrite.All • アラート • secureScores • secureScoreControlProfiles GET、POST、PATCH ThreatIndicators.ReadWrite.OwnedBy • tiIndicator (プレビュー) GET、POST、PATCH、DELETE [アクセス許可を追加する]を選択します。
以下の情報を保存します。
- アプリケーション (クライアント) ID
- リダイレクト URL
- 必要なアクセス許可のリスト
*Windows Defender Advanced Threat Protection (WDATP) には、Microsoft Graph Security APIで必要なロールよりも追加のユーザー ロールが必要です。そのため、WDATP と Microsoft Graph Security APIロールの両方のユーザーのみが WDATP データにアクセスできます。 アプリケーションのみの認証では、これにより制限されません。そのため、アプリ専用の認証トークンを使用することをお勧めします。
詳細情報については、 「Microsoft ID プラットフォームにアプリを登録する」を参照してください。
アプリケーションにアクセス許可を付与する
アプリケーションの登録では、アプリケーションに必要なアクセス許可が定義されますが、アプリケーションにこれらのアクセス許可は付与されません。 Microsoft Entraテナント管理者は、管理者の同意エンドポイントを呼び出すことによって、これらのアクセス許可を明示的に付与する必要があります。 詳細については、「管理者の同意エンドポイントを使用する」を参照してください。
アプリケーションにアクセス許可を付与するには、以下の情報が必要です。
- アプリケーション ID: Azure アプリケーション登録ポータルのアプリケーション ID。
- リダイレクト URL: Azure アプリケーション登録ポータルで認証応答のために設定した文字列。
アクセス許可を付与するには、次の操作を行います。
テキスト エディターで、以下の URL 文字列を作成します。
https://login.microsoftonline.com/common/adminconsent?client_id=<Application Id>&state=12345&redirect_uri=<Redirect URL>Web ブラウザーでこの URL に移動し、テナント管理者としてサインインします。 ダイアログ ボックスに、アプリケーション登録ポータルで指定した、アプリケーションに必要なアクセス許可のリストが表示されます。 [OK] を選択し、アプリケーションにこれらのアクセス許可を付与します。
注:
この手順では、アクセス許可がユーザーではなくアプリケーションに付与されます。 つまり、このアプリケーションを使用するMicrosoft Entra テナントに属するすべてのユーザーには、管理者以外のユーザーであっても、これらのアクセス許可が付与されます。
Microsoft Entra ロールをユーザーに割り当てる
アプリケーションにアクセス許可が付与されると、アプリケーションへのアクセス権を持つすべてのユーザー (つまり、Microsoft Entra テナントのメンバー) は、付与されたアクセス許可を受け取ります。 機密性の高いセキュリティ データをさらに保護するために、Microsoft Graph Security APIでは、ユーザーにMicrosoft Entra IDセキュリティ閲覧者ロールを割り当てる必要もあります。 詳細については、「Microsoft Entra IDの管理者ロールのアクセス許可」および「Microsoft Entra IDを持つユーザーに管理者ロールと管理者以外のロールを割り当てる」を参照してください。
注:
この手順を実行するには、管理者である必要があります。
ユーザーにロールを割り当てるには:
- Microsoft Entra 管理センターにサインインします。
- [ ID ] メニュー > の [ ユーザー> ] を展開し、[ すべてのユーザー] を選択します。
- ユーザーを選択します。
- [割り当てられている役割]、[割り当ての追加] の順に選択します。
- [セキュリティ閲覧者] を選択し、[追加] をクリックします。
認証コードを作成する
認証コードを作成するには、以下の情報が必要です。
- アプリケーション ID: アプリケーション登録ポータルのアプリケーション ID。
- リダイレクト URL:Microsoft Entra IDからの認証応答が送信される URL。 最初に、https://localhost またはテスト クライアント Web アプリケーション ホーム ページを使用できます。
- アプリケーション キー (オプション): アプリケーションのキー。 これは、アプリケーション専用認証コードを使用するアプリケーションを開発する場合に適用されます (つまりユーザーにより委任される認証はサポートされません)。
次の表に、認証コードの作成に使用できるリソースを示します。
既存のライブラリを使用しないアプリケーションの場合は、「ユーザーの代わりにアクセスを取得」を参照してください。
- Microsoft Entra IDからコードを取得します。 呼び出すクエリには、アプリケーション ID、リダイレクト URI、および必要なアクセス許可のパラメーターが指定されています。
- コードを使用してアクセス トークンを取得します。
OpenId Connect ライブラリを使用する場合は、「Microsoft Entra ID と OpenID Connect を使用した認証」を参照し、 を呼び出しますapp.UseOpenIdConnectAuthentication()。
注:
ユーザーにより委任された認証トークンを要求する場合、ライブラリのパラメーターは Requested Scopes です。 このパラメーターには、登録アプリケーションに必要なスコープではなく、User.Read を使用してください。 Requested Scopes パラメーターは、返される認証トークンに含まれるアクセス許可には影響しません。 これらのアクセス許可は、テナント管理者がアプリケーションに付与したアクセス許可によって決定します。
たとえば .NET MSAL ライブラリを使用している場合には、次のように呼び出します。
var accessToken = (await client.AcquireTokenAsync(scopes)).AccessToken;
注:
この例では、最小限の特権を持つアクセス許可 (User.Read など) を使用する必要があります。 ただし、返されるアクセス トークンには、テナント管理者が現在のユーザー テナントに付与したアクセス許可 (User.Read.All、User.ReadWrite.All など) が含まれることがあります。
トークン (文字列) は、認証情報とアプリケーションに必要なアクセス許可を含むMicrosoft Entra IDによって返されます。 以下の例に示すように、このトークンをベアラー トークンとして HTTP ヘッダーに割り当てます。
request.Headers.Authorization = new AuthenticationHeaderValue("bearer", accessToken);
Microsoft Graph により、このトークンに含まれている情報が検証され、アクセスが付与または拒否されます。
返されるトークンに含まれている要求を確認するには、NuGet library System.IdentityModel.Tokens.Jwt を使用します。
JwtSecurityTokenHandler tokenHandler = new JwtSecurityTokenHandler();
var securityToken = tokenHandler.ReadToken(accessToken) as JwtSecurityToken;
Microsoft Graph からの応答には、client-request-id というヘッダーが含まれています。これは GUID です。 アクセスが拒否される場合は、Microsoft 技術コミュニティでサポートを要請する際にこの GUID を指定してください。これにより、この認証エラーの原因の調査を支援できます。
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示