チュートリアル:Azure Active Directory Reporting API と証明書を使用したデータの取得Tutorial: Get data using the Azure Active Directory reporting API with certificates

Azure Active Directory (Azure AD) レポート API は、一連の REST ベースの API を使用してデータへのプログラムによるアクセスを提供します。The Azure Active Directory (Azure AD) reporting APIs provide you with programmatic access to the data through a set of REST-based APIs. これらの API は、さまざまなプログラミング言語とツールから呼び出すことができます。You can call these APIs from a variety of programming languages and tools. ユーザーの介入なしに Azure AD Reporting API にアクセスする場合は、証明書を使用するようにアクセスを構成する必要があります。If you want to access the Azure AD Reporting API without user intervention, you must configure your access to use certificates.

このチュートリアルでは、テスト証明書を使用してレポート用の MS Graph API にアクセスする方法について説明します。In this tutorial, you learn how to use a test certificate to access the MS Graph API for reporting. このテスト証明書は、運用環境に使わないことをお勧めします。We don't recommend using test certificates in a production environment.

前提条件Prerequisites

  1. サインイン データにアクセスするには、プレミアム (P1/P2) ライセンスを持つ Azure Active Directory テナントがあることを確認してください。To access sign-in data, make sure you have an Azure Active Directory tenant with a premium (P1/P2) license. Azure Active Directory エディションにアップグレードするには、「Azure Active Directory Premium の概要」を参照してください。See Getting started with Azure Active Directory Premium to upgrade your Azure Active Directory edition. アップグレード前のアクティビティ データがない場合は、プレミアム ライセンスにアップグレードしてからレポートにデータが表示されるようになるまでに数日かかることに注意してください。Note that if you did not have any activities data prior to the upgrade, it will take a couple of days for the data to show up in the reports after you upgrade to a premium license.

  2. テナントのグローバル管理者セキュリティ管理者セキュリティ閲覧者、またはレポート閲覧者ロールに含まれているユーザー アカウントに切り替えるか、そのようなアカウントを新たに作成します。Create or switch to a user account in the global administrator, security administrator, security reader or report reader role for the tenant.

  3. Azure Active Directory Reporting API にアクセスするための前提条件を満たします。Complete the prerequisites to access the Azure Active Directory reporting API.

  4. Azure AD PowerShell V2 をダウンロードしてインストールします。Download and install Azure AD PowerShell V2.

  5. MSCloudIdUtils をインストールします。Install MSCloudIdUtils. このモジュールには、いくつかのユーティリティ コマンドレットが用意されています。その例を次に示します。This module provides several utility cmdlets including:

    • 認証に必要な ADAL ライブラリThe ADAL libraries needed for authentication
    • ADAL を使用してユーザー キー、アプリケーション キー、証明書からアクセス トークンを取得Access tokens from user, application keys, and certificates using ADAL
    • Graph API でページ単位の結果を処理Graph API handling paged results
  6. 初めてモジュールを使う場合は、Install-MSCloudIdUtilsModule を実行します。初めてではない場合は、Import-Module PowerShell コマンドを使ってモジュールをインポートします。If it's your first time using the module run Install-MSCloudIdUtilsModule, otherwise import it using the Import-Module Powershell command. セッションは次のような画面になります。Windows PowershellYour session should look similar to this screen: Windows Powershell

  7. New-SelfSignedCertificate PowerShell コマンドレットを使用して、テスト証明書を作成します。Use the New-SelfSignedCertificate Powershell commandlet to create a test certificate.

    $cert = New-SelfSignedCertificate -Subject "CN=MSGraph_ReportingAPI" -CertStoreLocation "Cert:\CurrentUser\My" -KeyExportPolicy Exportable -KeySpec Signature -KeyLength 2048 -KeyAlgorithm RSA -HashAlgorithm SHA256
    
  8. Export-Certificate コマンドレットを使用して、テスト証明書を証明書ファイルにエクスポートします。Use the Export-Certificate commandlet to export it to a certificate file.

    Export-Certificate -Cert $cert -FilePath "C:\Reporting\MSGraph_ReportingAPI.cer"
    
    

Azure Active Directory Reporting API と証明書を使用したデータの取得Get data using the Azure Active Directory reporting API with certificates

  1. Azure portal に移動し、 [Azure Active Directory][アプリの登録] の順に選択し、リストからアプリケーションを選択します。Navigate to the Azure portal, select Azure Active Directory, then select App registrations and choose your application from the list.

  2. [設定] > [キー] を選択し、 [公開キーのアップロード] を選択します。Select Settings > Keys and select Upload Public Key.

  3. 前の手順の証明書ファイルを選択し、 [保存] を選択します。Select the certificate file from the previous step and select Save.

  4. アプリケーション ID と、アプリケーションで登録した証明書のサムプリントを書き留めます。Note the Application ID, and the thumbprint of the certificate you just registered with your application. サムプリントを調べるには、ポータルのアプリケーション ページから [設定] に移動し、 [キー] をクリックします。To find the thumbprint, from your application page in the portal, go to Settings and click Keys. サムプリントは [公開鍵] 一覧の下にあります。The thumbprint will be under the Public Keys list.

  5. インライン マニフェスト エディターでアプリケーション マニフェストを開き、次のスキーマを使用して、keyCredentials プロパティを新しい証明書情報に置き換えます。Open the application manifest in the inline manifest editor and replace the keyCredentials property with your new certificate information using the following schema.

    "keyCredentials": [
         {
             "customKeyIdentifier": "$base64Thumbprint", //base64 encoding of the certificate hash
             "keyId": "$keyid", //GUID to identify the key in the manifest
             "type": "AsymmetricX509Cert",
             "usage": "Verify",
             "value":  "$base64Value" //base64 encoding of the certificate raw data
         }
     ]
    
  6. マニフェストを保存します。Save the manifest.

  7. これで、この証明書を使用して MS Graph API のアクセス トークンを取得できるようになりました。Now, you can get an access token for the MS Graph API using this certificate. MSCloudIdUtils PowerShell モジュールの Get-MSCloudIdMSGraphAccessTokenFromCert コマンドレットを使い、前の手順で取得したアプリケーション ID とサムプリントを渡します。Use the Get-MSCloudIdMSGraphAccessTokenFromCert cmdlet from the MSCloudIdUtils PowerShell module, passing in the Application ID and the thumbprint you obtained from the previous step.

    Azure ポータル

  8. Powershell スクリプトでアクセス トークンを使用して、Graph API のクエリを実行します。Use the access token in your Powershell script to query the Graph API. MSCloudIDUtils の Invoke-MSCloudIdMSGraphQuery コマンドレットを使って SignIns と directoryAudits エンドポイントを列挙します。Use the Invoke-MSCloudIdMSGraphQuery cmdlet from the MSCloudIDUtils to enumerate the signins and directoryAudits endpoint. 複数のページにわたる結果を処理し、それらの結果を PowerShell パイプラインに送っています。This cmdlet handles multi-paged results, and sends those results to the PowerShell pipeline.

  9. directoryAudits エンドポイントを照会して、監査ログを取得します。Query the directoryAudits endpoint to retrieve the audit logs. Azure PortalAzure portal

  10. SignIns エンドポイントを照会して、サインイン ログを取得します。Query the signins endpoint to retrieve the sign-in logs. Azure PortalAzure portal

  11. このデータを CSV にエクスポートし、SIEM システムに保存できるようになります。You can now choose to export this data to a CSV and save to a SIEM system. また、スケジュールされたタスクにスクリプトをラップすれば、ソース コードにアプリケーション キーを保存せずに Azure AD データをテナントから定期的に取得することができます。You can also wrap your script in a scheduled task to get Azure AD data from your tenant periodically without having to store application keys in the source code.

次の手順Next steps