承認と Microsoft Graph セキュリティ APIAuthorization and the Microsoft Graph Security API

Microsoft Graph セキュリティ API からアクセスできるセキュリティ データは機密性が高く、アクセス許可と Azure Active Directory (Azure AD) ロールによって保護されています。Security data accessible via the Microsoft Graph Security API is sensitive and protected by both permissions and Azure Active Directory (Azure AD) roles.

Microsoft Graph セキュリティ API では 2 種類の承認がサポートされています。The Microsoft Graph Security API supports two types of authorization:

  • アプリケーション レベルの承認 - ユーザーはサインインしません (例: SIEM シナリオ)。Application-level authorization - There is no signed-in user (for example, a SIEM scenario). アプリケーションに付与されたアクセス許可によって、承認が決定します。The permissions granted to the application determine authorization.

    注: このオプションは、アプリケーションがロール ベースのアクセス制御 (RBAC) を管理しているケースにも対応します。Note: This option can also support cases where Role-Based Access Control (RBAC) is managed by the application.

  • ユーザーにより委任された承認 - Azure AD テナントのメンバーであるユーザーがサインインしています。User delegated authorization - A user who is a member of the Azure AD tenant is signed in. アプリケーションに必要なアクセス許可が付与されており、ユーザーが Azure AD 制限付き管理者ロール ([セキュリティ閲覧者] または [セキュリティ管理者]) のメンバーである必要があります。The user must be a member of an Azure AD Limited Admin role - either Security Reader or Securty Administrator - in addition to the application having been granted the required permissions.

Graph エクスプローラーから Microsoft Graph セキュリティ API を呼び出す場合:If you're calling the Microsoft Graph Security API from Graph Explorer:

  • Azure AD テナント管理者は、要求されたアクセス許可を Graph エクスプローラー アプリケーションに付与することに明示的に同意する必要があります。The Azure AD tenant admin must explicitly grant consent for the requested permissions to the Graph Explorer application.
  • ユーザーは、Azure AD の [セキュリティ閲覧者] 制限付き管理者ロールのメンバーである必要があります ([セキュリティ閲覧者] または [セキュリティ管理者] のいずれか)。The user must be a member of the Security Reader Limited Admin role in Azure AD (either Security Reader or Security Administrator).

: Graph エクスプローラーでは、アプリケーション レベルの承認がサポートされていません。Note: Graph Explorer does not support application-level authorization.

カスタム アプリケーションまたは独自のアプリケーションから Microsoft Graph セキュリティ API を呼び出す場合:If you're calling the Microsoft Graph Security API from a custom or your own application:

  • Azure AD テナント管理者は、アプリケーションに対して明示的に承認を与える必要があります。The Azure AD tenant admin must explicitly grant consent to your application. これは、アプリケーション レベルの承認と、ユーザーにより委任された承認の両方に必要です。This is required both for application-level authorization and user delegated authorization.
  • ユーザーにより委任された承認を使用する場合、ユーザーは、Azure AD の [セキュリティ閲覧者] または [セキュリティ管理者] 制限付き管理者ロールのメンバーである必要があります。If you're using user delegated authorization, the user must be a member of the Security Reader or Security Administrator Limited Admin role in Azure AD.

セキュリティ API クライアント アプリケーションで承認を管理するManage authorization in security API client applications

Microsoft Graph セキュリティ API から提供されるセキュリティ データは機密性が高く、適切な認証および承認メカニズムを使用して保護する必要があります。Security data provided via the Microsoft Graph Security API is sensitive and must be protected by appropriate authentication and authorization mechanisms. 次の表に、Microsoft Graph セキュリティ API にアクセスできるクライアント アプリケーションを登録および作成する手順を示します。The following table lists the steps to register and create a client application that can access the Microsoft Graph Security API.

対象者Who 操作Action
アプリケーション開発者または所有者Application developer or owner アプリケーションをエンタープライズ アプリケーションとして登録します。Register the application as an enterprise application.
テナント管理者Tenant admin アプリケーションにアクセス許可を付与します。Grant permissions to the application.
テナント管理者Tenant admin ユーザーにロールを割り当てます。Assign roles to users.
アプリケーション開発者Application developer ユーザーとしてサインインし、アプリケーションを使用して Microsoft Graph セキュリティ API にアクセスします。Sign in as the user and use the application to access the Microsoft Graph Security API.

アプリケーションの登録では、アプリケーションの実行に必要なアクセス許可だけが定義されます。Application registration only defines which permissions the application needs in order to run. これらのアクセス許可はアプリケーションに付与されません。It does NOT grant these permissions to the application.

Azure AD テナント管理者は、アプリケーションにアクセス許可を明示的に付与する必要があります。The Azure AD tenant administrator MUST explicitly grant the permissions to the application. これはテナントごとに実行し、またアプリケーション登録ポータルでアプリケーションのアクセス許可が変更されるたびに実行する必要があります。This must be done per tenant and must be performed every time the application permissions are changed in the application registration portal.

たとえば、2 つの Azure AD テナント (T1 および T2) と 2 つのアクセス許可 (P1 および P2) があるとします。For example, assume that you have an application, two Azure AD tenants, T1 and T2, and two permissions, P1 and P2. 承認プロセスを以下に示します。The following is the authorization process:

  • アプリケーションがアクセス許可 P1 を必要とすることが登録されます。The application registers to require permission P1.
  • テナント T1 のユーザーがこのアプリケーションの Azure AD トークンを取得すると、このトークンにはアクセス許可が含まれていません。When users in tenant T1 get an Azure AD token for this application, the token does not contain any permissions.
  • テナント T1 の Azure AD 管理者が、アプリケーションにアクセス許可を明示的に付与します。The Azure AD admin of tenant T1 explicitly grants permissions to the application. テナント T1 のユーザーがこのアプリケーションの Azure AD トークンを取得すると、このトークンにはアクセス許可 P1 が含まれています。When users in tenant T1 get an Azure AD token for the application, it will contain permission P1.
  • テナント T2 のユーザーがアプリケーションの Azure AD トークンを取得すると、このトークンにはアクセス許可が含まれていません。これは、テナント T2 の管理者がアプリケーションにアクセス許可をまだ付与していないためです。When users in tenant T2 get an Azure AD token for the application, the token does not contain any permissions - because the admin of tenant T2 did not yet grant permissions to the application. アクセス許可はテナントごとおよびアプリケーションごとに付与する必要があります。Permission must be granted per tenant and per application.
  • アプリケーションの登録が変更され、アクセス許可 P1P2 が必要になりました。The application has its registration changed to now require permissions P1 and P2.
  • テナント T1 のユーザーがこのアプリケーションの Azure AD トークンを取得すると、このトークンにはアクセス許可 P1 だけが含まれています。When users in tenant T1 get an Azure AD token for the application, it only contains permission P1. アプリケーションに付与されたアクセス許可は、付与された内容のスナップショットとして記録されます。アプリケーションの登録 (アクセス許可) を変更しても、アクセス許可は自動的には変更されませんPermissions granted to an application are recorded as snapshots of what was granted - they do not change automatically after the application registration (permission) changes.
  • テナント T2 の管理者がアクセス許可 P1P2 をアプリケーションに付与します。The admin of tenant T2 grants permissions P1 and P2 to the application. 次にテナント T2 のユーザーがこのアプリケーションの Azure AD トークンを取得すると、このトークンにはアクセス許可 P1P2 が含まれています。Now, when users in tenant T2 get an Azure AD token for the application, the token will contain permissions P1 and P2.

: テナント T1 のアプリケーションとテナント T2 のアプリケーションの Azure AD トークンに含まれているアクセス許可はそれぞれ異なります。これは、それぞれのテナント管理者がアプリケーションに対して異なるアクセス許可を付与しているためです。Note: The Azure AD tokens for the application in tenant T1 and the application in tenant T2 contain different permissions, because each tenant admin has granted different permissions to the application.

  • アプリケーションをテナント T1 で再び実行できるようにするには、テナント T1 の管理者が、アクセス許可 P1P2 をアプリケーションに明示的に付与する必要があります。To make the application work again in tenant T1, the admin of tenant T1 must explicitly grant permissions P1 and P2 to the application.

Microsoft ID プラットフォーム エンドポイントにアプリケーションを登録するRegister an application with the Microsoft identity platform endpoint

Microsoft ID プラットフォーム エンドポイントにアプリケーションを登録するには、次のものが必要です。To register an application to the Microsoft identity platform endpoint, you'll need:

  • アプリケーション名 - アプリケーション名として使用される文字列。Application name - A string used for the application name.
  • リダイレクト URL - Azure AD からの承認応答の送信先 URL。Redirect URL - The URL where the authentication response from Azure AD is sent. 最初に、テスト クライアント Web アプリケーション ホーム ページを使用できます。To start, you can use the test client web app homepage.
  • 必要なアクセス許可 - アプリケーションが Microsoft Graph を呼び出すことができるようにするために必要なアクセス許可。Required Permissions - The permissions that your application requires to be able to call Microsoft Graph.

アプリケーションを登録するには、次の操作を行います。To register your application:

  1. Azure アプリ登録ポータルに移動してサインインします。Go to the Azure app registration portal and sign in.

    : テナント管理者である必要はありません。[マイ アプリケーション] リストにリダイレクトされます。Note: You don't have to be a tenant admin. You will be redirected to the My applications list.

  2. [新規登録] を選択します。Choose New registration.

  3. 新しいアプリケーションの登録ページで [名前]の値を入力し、サポートするアカウントの種類を選択します。On the registration page for the new application, enter a value for Name and select the account types you wish to support. [リダイレクト URL] フィールドにリダイレクト URL を入力します。In the Redirect URI field, enter the redirect URL.

  4. [登録] を選択してアプリを作成し、アプリの概要ページを表示します。Select Register to create the app and view its overview page. *

  5. アプリの [API のアクセス許可] ページに移動します。Go to the app's API permissions page.

  6. [アクセス許可を追加する] を選択し、ポップアップで [Microsoft Graph] を選択します。Select Add a permission and then choose Microsoft Graph in the flyout. [委任されたアクセス許可] を選択します。Select Delegated permissions. 検索ボックスを使用して、必要なアクセス許可を検索して選択します。Use the search box to find and select the required permissions. アクセス許可のリストについては、「セキュリティのアクセス許可」を参照してください。For a list of permissions, see Security permissions.

    注: Microsoft Graph Security API では、GET クエリに *.Read.All スコープ、PATCH/POST/DELETE クエリに *.ReadWrite.All スコープが必要です。Note: The Microsoft Graph Security API requires the *.Read.All scope for GET queries, and the *.ReadWrite.All scope for PATCH/POST/DELETE queries.

    アクセス許可Permission エンティティEntity サポートされている要求Supported requests
    SecurityActions.Read.AllSecurityActions.Read.All securityActions (プレビュー)securityActions (preview) GETGET
    SecurityActions.ReadWrite.AllSecurityActions.ReadWrite.All securityActions (プレビュー)securityActions (preview) GET、POSTGET, POST
    SecurityEvents.Read.AllSecurityEvents.Read.All alertsalerts
    secureScoressecureScores
    secureScoreControlProfilessecureScoreControlProfiles
    取得GET
    SecurityEvents.ReadWrite.AllSecurityEvents.ReadWrite.All alertsalerts
    secureScoressecureScores
    secureScoreControlProfilessecureScoreControlProfiles
    GET、POST、PATCHGET, POST, PATCH
    ThreatIndicators.ReadWrite.OwnedByThreatIndicators.ReadWrite.OwnedBy tiIndicator (プレビュー)tiIndicator (preview) GET、POST、PATCH、DELETEGET, POST, PATCH, DELETE
  7. [アクセス許可を追加する]を選択します。Choose Add permissions.

以下の情報を保存します。Save the following information:

  • アプリケーション (クライアント) IDApplication (client) ID
  • リダイレクト URLRedirect URL
  • 必要なアクセス許可のリストList of required permissions

* Windows Defender Advanced Threat Protection (WDATP) では、Microsoft Graph Security API で要求される以上の追加の ユーザー ロール を要求します。従って、WDATP および Microsoft Graph Security API の両方のロールのユーザーのみが WDATP のデータにアクセスできます。* Windows Defender Advanced Threat Protection (WDATP) requires additional user roles than what is required by the Microsoft Graph Security API; therefore, only the users in both WDATP and Microsoft Graph Security API roles can have access to the WDATP data. アプリケーションのみの認証では、これにより制限されません。そのため、アプリ専用の認証トークンを使用することをお勧めします。Application-only authentication is not limited by this; therefore, we recommend that you use an app-only authentication token.

詳細情報については、 「Microsoft ID プラットフォームにアプリを登録する」を参照してください。For more information, see Register your app with the Microsoft identity platform.

アプリケーションにアクセス許可を付与するGrant permissions to an application

アプリケーションの登録では、アプリケーションに必要なアクセス許可が定義されますが、アプリケーションにこれらのアクセス許可は付与されません。Application registration only defines which permission the application requires - it does not grant these permissions to the application. Azure AD テナント管理者は、管理者の同意エンドポイントを呼び出して、これらのアクセス許可を明示的に付与する必要があります。An Azure AD tenant administrator must explicitly grant these permissions by making a call to the admin consent endpoint. 詳細については、「管理者の同意エンドポイントを使用する」を参照してください。For details, see Using the admin consent endpoint.

アプリケーションにアクセス許可を付与するには、以下の情報が必要です。To grant permissions to an application, you'll need:

  • アプリケーション ID - Azure アプリケーション登録ポータルのアプリケーション ID。Application ID - The application ID from the Azure application registration portal.
  • リダイレクト URL - Azure アプリケーション登録ポータルで認証応答のために設定した文字列。Redirect URL - The string you set in the Azure application registration portal for authentication response.

アクセス許可を付与するには、次の操作を行います。To grant the permissions:

  • テキスト エディターで、以下の URL 文字列を作成します。In a text editor, create the following URL string:

    https://login.microsoftonline.com/common/adminconsent?client_id=<Application Id>&state=12345&redirect_uri=<Redirect URL>

  • Web ブラウザーでこの URL に移動し、テナント管理者としてサインインします。In a web browser, go to this URL, and sign in as a tenant administrator. ダイアログ ボックスに、アプリケーション登録ポータルで指定した、アプリケーションに必要なアクセス許可のリストが表示されます。The dialog box shows the list of permission the application requires, as specified in the application registration portal. [OK] を選択し、アプリケーションにこれらのアクセス許可を付与します。Choose OK to grant the application these permissions.

注: この手順では、アクセス許可がユーザーではなくアプリケーションに付与されます。Note: This step grants permissions to the application - not to users. つまり、このアプリケーションを使用する Azure AD テナントに属するすべてのユーザー (管理者以外のユーザーを含む) に、これらのアクセス許可が付与されます。This means that all users belonging to the Azure AD tenant that use this application will be granted these permissions - even non-admin users.

Azure AD のロールをユーザーに割り当てるAssign Azure AD roles to users

アプリケーションにアクセス許可が付与されると、そのアプリケーションにアクセスできるすべてのユーザー (Azure AD テナントのメンバー) に、付与されたアクセス許可が与えられます。After an application is granted permissions, everyone with access to the application (that is, members of the Azure AD tenant) will receive the granted permissions. 機密性の高いセキュリティ データの保護を強化するため、Microsoft Graph セキュリティ API では、ユーザーに Azure AD の [セキュリティ閲覧者] ロールが割り当てられている必要があります。To further protect sensitive security data, the Microsoft Graph Security API also requires users to be assigned the Azure AD Security Reader role. 詳細については、「Azure Active Directory での管理者ロールのアクセス許可」と「Azure Active Directory を使ってユーザーに管理者と管理者以外のロールを割り当てる」を参照してください。For details, see Administrator role permissions in Azure Active Directory and Assign administrator and non-administrator roles to users with Azure Active Directory.

注: この手順を実行するには、テナント管理者でなければなりません。Note: You must be a tenant admin to perform this step.

ユーザーにロールを割り当てるには:To assign an RBAC role to a user

  1. Azure Portal (https://portal.azure.com)) にサインインします。Sign in to the Azure portal (https://portal.azure.com).
  2. 左上のアイコンをクリックして、Azure ポータル メニューを展開します。Click the icon in the top left to expand the Azure portal menu. [Azure Active Directory] > [ユーザー] の順に選択します。Select Azure Active Directory > Users.
  3. ユーザーの名前をクリックします。Click the user name of the account.
  4. [割り当てられている役割]、[割り当ての追加] の順に選択します。Choose Assigned roles, and then Add assignment.
  5. [セキュリティ閲覧者] を選択し、[追加] をクリックします。Select Security reader, and click Add.

認証コードを作成するCreate an authentication code

認証コードを作成するには、以下の情報が必要です。To create an authentication code, you'll need:

  • アプリケーション ID - アプリケーション登録ポータルのアプリケーション ID。Application ID - The application ID from application registration portal.
  • リダイレクト URL - Azure AD からの承認応答の送信先 URL。Redirect URL - The URL where the authentication response from Azure AD is sent. 最初に、https://localhost またはテスト クライアント Web アプリケーション ホーム ページを使用できます。To start, you can use https://localhost or the test client web app homepage.
  • アプリケーション キー (オプション) - アプリケーションのキー。Application Key (optional) - The key of the application. これは、アプリケーション専用認証コードを使用するアプリケーションを開発する場合に適用されます (つまりユーザーにより委任される認証はサポートされません)。This applies when you're developing an application that will use application-only authentication code (that is, will not support user delegated authentication).

次の表に、認証コードの作成に使用できるリソースを示します。The following table lists resources that you can use to create an authentication code.

アプリケーションの種類Type of application 認証ライブラリAuthentication library
デスクトップ アプリケーション - iOSDesktop apps - iOS MSAL.framework: iOS 用 Microsoft Authentication Library プレビューMSAL.framework: Microsoft Authentication Library Preview for iOS
デスクトップ アプリケーション - AndroidDesktop apps - Android Microsoft Authentication Library (MSAL)Microsoft Authentication Library (MSAL)
デスクトップ アプリケーション - .NetDesktop apps - .Net Microsoft Authentication Library (MSAL)Microsoft Authentication Library (MSAL)
Web アプリケーション - JavaScript SPAWeb apps - JavaScript SPA JavaScript 用 Microsoft Authentication Library プレビューMicrosoft Authentication Library for JavaScript Preview
Web アプリケーション - .NET Web ServerWeb apps - .NET Web Server OpenIdConnection、Cookies、SystemWebOpenIdConnection, Cookies, SystemWeb
Web アプリケーション - NodeJS Web アプリケーションWeb apps - NodeJS Web App

既存のライブラリを使用しないアプリケーションの場合は、「ユーザーの代わりにアクセスを取得」を参照してください。For applications that don't use any of the existing libraries, see Get access on behalf of a user.

  1. Azure AD からコードを取得します。Get a code from Azure AD. 呼び出すクエリには、アプリケーション ID、リダイレクト URI、および必要なアクセス許可のパラメーターが指定されています。The query to call contains parameter for Application ID, Redirect URl, and required permissions.
  2. コードを使用してアクセス トークンを取得します。Use the code to get an access token.

OpenId Connect ライブラリを使用する場合は、「Azure AD および OpenID Connect を使用して認証する」を参照し、app.UseOpenIdConnectAuthentication() を呼び出してください。If you use OpenId Connect library, see Authenticate using Azure AD and OpenID Connect and call app.UseOpenIdConnectAuthentication().

注: ユーザーにより委任された認証トークンを要求する場合、ライブラリのパラメーターは Requested Scopes です。Note: If you're requesting user delegated authentication tokens, the parameter for the library is Requested Scopes. このパラメーターには、登録アプリケーションに必要なスコープではなく、User.Read を使用してください。Use User.Read for this parameter instead of what the registered application requires. Requested Scopes パラメーターは、返される認証トークンに含まれるアクセス許可には影響しません。The Requested Scopes parameter does NOT affect the permissions contained in the returned authentication tokens. これらのアクセス許可は、テナント管理者がアプリケーションに付与したアクセス許可によって決定します。These are determined by the permissions that the tenant admin granted the application.

たとえば .NET MSAL ライブラリを使用している場合には、次のように呼び出します。For example, if you're using the .NET MSAL library, call the following:

var accessToken = (await client.AcquireTokenAsync(scopes)).AccessToken;

注: この例では、最小限の特権を持つアクセス許可 (User.Read など) を使用する必要があります。Note: This example should use the least privileged permission, such as User.Read. ただし、返されるアクセス トークンには、テナント管理者が現在のユーザー テナントに付与したアクセス許可 (User.Read.All、User.ReadWrite.All など) が含まれることがあります。However, the returned access token can contain permissions that were granted by the tenant admin for the current user tenant, such as User.Read.All or User.ReadWrite.All.

Azure AD により、認証情報とアプリケーションに必要なアクセス許可が含まれているトークン (文字列) が返されます。A token (string) is returned by Azure AD that contains your authentication information and the permissions required by the application. 以下の例に示すように、このトークンをベアラー トークンとして HTTP ヘッダーに割り当てます。Assign this token to the HTTP header as a bearer token, as shown in the following example.

request.Headers.Authorization = new AuthenticationHeaderValue("bearer", accessToken);

Microsoft Graph により、このトークンに含まれている情報が検証され、アクセスが付与または拒否されます。Microsoft Graph will validate the information contained in this token and grant, or reject, access.

返されるトークンに含まれている要求を確認するには、NuGet library System.IdentityModel.Tokens.Jwt を使用します。To view claims contained in the returned token, use NuGet library System.IdentityModel.Tokens.Jwt.

JwtSecurityTokenHandler tokenHandler = new JwtSecurityTokenHandler();
var securityToken = tokenHandler.ReadToken(accessToken) as JwtSecurityToken;

Microsoft Graph からの応答には、client-request-id というヘッダーが含まれています。これは GUID です。The response from Microsoft Graph contains a header called client-request-id, which is a GUID. アクセスが拒否される場合は、Microsoft 技術コミュニティでサポートを要請する際にこの GUID を指定してください。これにより、この認証エラーの原因の調査を支援できます。If access is denied, please specify this GUID when seeking support at Microsoft Tech Community, so we can help investigate the cause of this authentication failure.