Azure Active Directory Identity Protection と Microsoft Graph の基本Get started with Azure Active Directory Identity Protection and Microsoft Graph

Microsoft Graph は、Microsoft の統合 API エンドポイントであり、Azure Active Directory Identity Protection API のホームです。Microsoft Graph is the Microsoft unified API endpoint and the home of Azure Active Directory Identity Protection APIs. 危険なユーザーとサインインに関する情報を明らかにする API が 4 つあります。最初の API riskDetection を使用すると、Microsoft Graph に対して、ユーザーやサインインに結び付いているリスク検出とその検出に関連する情報の一覧のクエリを実行できます。There are four APIs that expose information about risky users and sign-ins. The first API, riskDetection, allows you to query Microsoft Graph for a list of both user and sign-in linked risk detections and associated information about the detection. 2 つ目の API である riskyUsers を使用すると、Microsoft Graph に対して、リスクとして検出されたユーザーの Identity Protection に関する情報のクエリを実行できます。The second API, riskyUsers, allows you to query Microsoft Graph for information about users Identity Protection detected as risk. 3 つ目の API である signIn を使用すると、Microsoft Graph に対して、リスク状態、詳細、およびレベルに関連する特定のプロパティを使用して、Azure AD のサインインに関する情報のクエリを実行できます。The third API, signIn, allows you to query Microsoft Graph for information on Azure AD sign-ins with specific properties related to risk state, detail, and level. 4 つ目の API である identityRiskEvents を使用すると、Microsoft Graph に対して、リスク検出とその関連情報の一覧に対するクエリを実行できます。The fourth API, identityRiskEvents, allows you to query Microsoft Graph for a list of risk detections and associated information. identityRiskEvents API は 2020 年 1 月 10 日に非推奨となる予定です。代わりに riskDetections API を使用することをお勧めします。The identityRiskEvents API will be deprecated on January 10, 2020; we suggest you use the riskDetections API instead. この記事では、Microsoft Graph への接続とこれらの API のクエリの概要について説明します。This article gets you started with connecting to the Microsoft Graph and querying these APIs. さらに踏み込んだ概要や詳しい解説、Graph Explorer の利用については、Microsoft Graph のサイトまたはこれらの API に関する特定のリファレンス ドキュメントを参照してください。For an in-depth introduction, full documentation, and access to the Graph Explorer, see the Microsoft Graph site or the specific reference documentation for these APIs:

Microsoft Graph に接続するConnect to Microsoft graph

Microsoft Graph を介して Identity Protection のデータにアクセスするには、次の 4 つのステップがあります。There are four steps to accessing Identity Protection data through Microsoft Graph:

  1. ドメイン名を取得します。Retrieve your domain name.
  2. 新しいアプリ登録を作成します。Create a new app registration.
  3. このシークレットとその他いくつかの情報を使って Microsoft Graph に本人性を証明し、認証トークンを取得します。Use this secret and a few other pieces of information to authenticate to Microsoft Graph, where you receive an authentication token.
  4. このトークンを使って API エンドポイントに要求を行い、Identity Protection データを取得します。Use this token to make requests to the API endpoint and get Identity Protection data back.

以降の手順を開始する前に次の情報が必要となります。Before you get started, you’ll need:

  • Azure AD にアプリケーションを作成するための管理者特権Administrator privileges to create the application in Azure AD
  • テナントのドメインの名前 (例: contoso.onmicrosoft.com)The name of your tenant's domain (for example, contoso.onmicrosoft.com)

ドメイン名の取得Retrieve your domain name

  1. Azure Portal に管理者としてサインインします。Sign in to your Azure portal as an administrator.

  2. 左のナビゲーション ウィンドウで、 [Active Directory] をクリックします。On the left navigation pane, click Active Directory.

    Creating an application

  3. [管理] セクションで、 [プロパティ] をクリックします。In the Manage section, click Properties.

    Creating an application

  4. ドメイン名をコピーします。Copy your domain name.

新しいアプリ登録の作成Create a new app registration

  1. [Active Directory] ページの [管理] セクションで、 [アプリの登録] をクリックします。On the Active Directory page, in the Manage section, click App registrations.

    Creating an application

  2. 上部のメニューで、 [新しいアプリケーションの登録] をクリックします。In the menu on the top, click New application registration.

    Creating an application

  3. [作成] ページで、以下の手順を実行します。On the Create page, perform the following steps:

    Creating an application

    1. [名前] ボックスにアプリケーションの名前 (例:Azure AD リスク検出 API アプリケーション) を入力します。In the Name textbox, type a name for your application (for example: Azure AD Risk Detection API Application).

    2. [種類] として [Web アプリケーションや Web API] を選択します。As Type, select Web Application And / Or Web API.

    3. [サインオン URL] ボックスに、「http://localhost」と入力します。In the Sign-on URL textbox, type http://localhost.

    4. Create をクリックしてください。Click Create.

  4. [設定] ページを開くには、アプリケーションの一覧で、新しく作成したアプリの登録をクリックします。To open the Settings page, in the applications list, click your newly created app registration.

  5. [アプリケーション ID] をコピーします。Copy the Application ID.

API を使用するためのアクセス許可をアプリケーションに付与します。Grant your application permission to use the API

  1. [設定] ページで、 [必要なアクセス許可] をクリックします。On the Settings page, click Required permissions.

    Creating an application

  2. [必要なアクセス許可] ページで、上部ツール バーの [追加] をクリックします。On the Required permissions page, in the toolbar on the top, click Add.

    Creating an application

  3. [API アクセスの追加] ページで、 [API を選択します] をクリックします。On the Add API access page, click Select an API.

    Creating an application

  4. [API を選択します] ページで、 [Microsoft Graph] を選んで、 [選択] をクリックします。On the Select an API page, select Microsoft Graph, and then click Select.

    Creating an application

  5. [API アクセスの追加] ページで、 [アクセス許可を選択します] をクリックします。On the Add API access page, click Select permissions.

    Creating an application

  6. [アクセスの有効化] ページで、 [すべての ID リスク イベント情報の読み取り] をクリックし、 [選択] をクリックします。On the Enable Access page, click Read all identity risk information, and then click Select.

    Creating an application

  7. [API アクセスの追加] ページで、 [完了] をクリックします。On the Add API access page, click Done.

    Creating an application

  8. [必要なアクセス許可] ページで [アクセス許可の付与] をクリックし、 [はい] をクリックします。On the Required Permissions page, click Grant Permissions, and then click Yes.

    Creating an application

アクセス キーを取得するGet an access key

  1. [設定] ページで、 [キー] をクリックします。On the Settings page, click Keys.

    Creating an application

  2. [キー] ページで、次の手順を実行します。On the Keys page, perform the following steps:

    Creating an application

    1. [キーの説明] テキスト ボックスに、説明 (例: Azure AD リスク検出) を入力します。In the Key description textbox, type a description (for example, Azure AD Risk Detection).
    2. [期間] として、 [1 年] を選びます。As Duration, select In 1 year.
    3. [保存] をクリックします。Click Save.
    4. キーの値をコピーし、安全な場所に貼り付けます。Copy the key value, and then paste it into a safe location.

    注意

    このキーを紛失した場合、このセクションに戻って新しいキーを作成する必要があります。If you lose this key, you will have to return to this section and create a new key. このキーはだれにも渡さないように注意してください。このキーがあれば、だれでもデータにアクセスすることができます。Keep this key a secret: anyone who has it can access your data.

Microsoft Graph に対して認証を行って Identity Risk Detections API のクエリを実行するAuthenticate to Microsoft Graph and query the Identity Risk Detections API

この時点で次の情報が揃っている必要があります。At this point, you should have:

  • テナントのドメインの名前The name of your tenant's domain
  • クライアント IDThe client ID
  • キーThe key

本人確認を行うために、post 要求を https://login.microsoft.com に送信します。要求本文に次のパラメーターを指定してください。To authenticate, send a post request to https://login.microsoft.com with the following parameters in the body:

  • grant_type: “client_credentialsgrant_type: “client_credentials
  • resource: https://graph.microsoft.comresource: https://graph.microsoft.com
  • client_id: <クライアント ID>client_id: <your client ID>
  • client_secret: <キー>client_secret: <your key>

認証に成功すると、認証トークンが返されます。If successful, this returns an authentication token.
API を呼び出すためには、次のパラメーターを持つヘッダーを作成します。To call the API, create a header with the following parameter:

`Authorization`="<token_type> <access_token>"

トークンの種類とアクセス トークンは、認証時に返されたトークンで確認できます。When authenticating, you can find the token type and access token in the returned token.

このヘッダーは、API URL (https://graph.microsoft.com/beta/identityRiskEvents) に対する要求として送信します。Send this header as a request to the following API URL: https://graph.microsoft.com/beta/identityRiskEvents

成功した場合の応答は、OData JSON 形式の ID リスク検出とその関連データのコレクションです。必要に応じてこのデータを解析し、処理できます。The response, if successful, is a collection of identity risk detections and associated data in the OData JSON format, which can be parsed and handled as you see fit.

以下に示したコードは、PowerShell を使って認証と API 呼び出しを行う例です。Here’s sample code for authenticating and calling the API using PowerShell.
該当するクライアント ID、秘密キー、テナントのドメインを追加してください。Just add your client ID, the secret key, and the tenant domain.

    $ClientID       = "<your client ID here>"        # Should be a ~36 hex character string; insert your info here
    $ClientSecret   = "<your client secret here>"    # Should be a ~44 character string; insert your info here
    $tenantdomain   = "<your tenant domain here>"    # For example, contoso.onmicrosoft.com

    $loginURL       = "https://login.microsoft.com"
    $resource       = "https://graph.microsoft.com"

    $body       = @{grant_type="client_credentials";resource=$resource;client_id=$ClientID;client_secret=$ClientSecret}
    $oauth      = Invoke-RestMethod -Method Post -Uri $loginURL/$tenantdomain/oauth2/token?api-version=1.0 -Body $body

    Write-Output $oauth

    if ($oauth.access_token -ne $null) {
        $headerParams = @{'Authorization'="$($oauth.token_type) $($oauth.access_token)"}

        $url = "https://graph.microsoft.com/beta/identityRiskEvents"
        Write-Output $url

        $myReport = (Invoke-WebRequest -UseBasicParsing -Headers $headerParams -Uri $url)

        foreach ($event in ($myReport.Content | ConvertFrom-Json).value) {
            Write-Output $event
        }

    } else {
        Write-Host "ERROR: No Access Token"
    } 

API のクエリを実行するQuery the APIs

これら 3 つの API によって、組織内の危険なユーザーとサインインに関する情報をさまざまな方法で取得できるようになります。These three APIs provide a multitude of opportunities to retrieve information about risky users and sign-ins in your organization. 次に、これらの API と関連するサンプル要求の一般的なユース ケースをいくつか示します。Below are some common use cases for these APIs and the associated sample requests. これらのクエリは、上記のサンプル コードを使用するか、Graph Explorer を使用して実行できます。You can run these queries using the sample code above or by using Graph Explorer.

すべてのオフラインリスク検出を取得する (riskDetection API)Get all of the offline risk detections (riskDetection API)

Identity Protection サインイン リスク ポリシーを使用すると、リスクがリアルタイムで検出されたときに条件を適用できます。With Identity Protection sign-in risk policies, you can apply conditions when risk is detected in real time. オフラインで検出された場合はどうなるのでしょうか。But what about detections that are discovered offline? オフラインで発生したためにサインイン リスク ポリシーをトリガーしなかった検出を理解するには、riskDetection API に対してクエリを実行できます。To understand what detections occurred offline, and thus would not have triggered the sign-in risk policy, you can query the riskDetection API.

GET https://graph.microsoft.com/beta/riskDetections?$filter=detectionTimingType eq 'offline'

危険なサインイン ポリシー (riskyUsers API) によってトリガーされた MFA チャレンジに合格したすべてのユーザーを取得するGet all of the users who successfully passed an MFA challenge triggered by risky sign-ins policy (riskyUsers API)

Identity Protection のリスクベースのポリシーが組織に与える影響を把握するには、危険なサインイン ポリシーによってトリガーされた MFA チャレンジに合格したすべてのユーザーのクエリを実行します。To understand the impact Identity Protection risk-based policies have on your organization, you can query all of the users who successfully passed an MFA challenge triggered by a risky sign-ins policy. この情報は、Identity Protection によって危険であると誤検出された可能性があるユーザーや、AI が危険と見なすアクションを実行している可能性がある正当なユーザーを把握するために役立ちます。This information can help you understand which users Identity Protection may have falsely detected at as risk and which of your legitimate users may be performing actions that the AI deems risky.

GET https://graph.microsoft.com/beta/riskyUsers?$filter=riskDetail eq 'userPassedMFADrivenByRiskBasedPolicy'

特定のユーザーに対する危険なサインインをすべて取得する (signIn API)Get all the risky sign-ins for a specific user (signIn API)

ユーザーが侵害された可能性があると考えられる場合は、危険なサインインをすべて取得することで、危険の状態をより把握できます。When you believe a user may have been compromised, you can better understand the state of their risk by retrieving all of their risky sign-ins.

https://graph.microsoft.com/beta/identityRiskEvents?`$filter=userID eq '<userID>' and riskState eq 'atRisk'

次のステップNext steps

以上、Microsoft Graph の API を呼び出す基本的な方法を紹介しました。Congratulations, you just made your first call to Microsoft Graph!
これで、思いどおりに ID リスク検出のクエリを実行し、そのデータを活用できます。Now you can query identity risk detections and use the data however you see fit.

Microsoft Graph に関する詳細情報のほか、Graph API を使ったアプリケーションの構築方法については、こちらのドキュメントMicrosoft Graph のサイトをご覧ください。To learn more about Microsoft Graph and how to build applications using the Graph API, check out the documentation and much more on the Microsoft Graph site.

関連情報については、以下をご覧ください。For related information, see: