教學課程:使用 Azure Active Directory 報告 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 報告 API,請務必設定您的存取權以使用憑證。If you want to access the Azure AD Reporting API without user intervention, you must configure your access to use certificates.

在本教學課程中,您會了解如何使用測試憑證來存取 MS 圖形 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 Premium 來升級 Azure Active Directory 版本。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 報告 API 的必要條件Complete the prerequisites to access the Azure Active Directory reporting API.

  4. 下載並安裝 Azure AD PowerShell V2Download and install Azure AD PowerShell V2.

  5. 安裝 MSCloudIdUtilsInstall MSCloudIdUtils. 此模組會提供數個公用程式 Cmdlet,包括︰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
    • 處理分頁結果的圖形 APIGraph 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 commandlet 建立測試憑證。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 commandlet 將其匯出至憑證檔案。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 報告 API 搭配憑證來取得資料Get data using the Azure Active Directory reporting API with certificates

  1. 導覽至 Azure 入口網站,選取 [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 Certificates & secrets under Manage section on Application registration blade and select Upload Certificate.

  3. 從上一個步驟中選取憑證檔案,然後選取 [新增]。Select the certificate file from the previous step and select Add.

  4. 請記下應用程式識別碼,以及您剛剛向應用程式註冊的憑證指紋。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 Certificates & secrets under Manage section. 指紋會出現在 憑證 清單下方。The thumbprint will be under the Certificates list.

  5. 在內嵌資訊清單編輯器中開啟應用程式資訊清單,然後驗證 keyCredentials 屬性是否已使用下列新的憑證資訊更新 -Open the application manifest in the inline manifest editor and verify the keyCredentials property is updated with your new certificate information as shown below -

    "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. 現在,您可以使用此憑證來取得 MS 圖形 API 的存取權杖。Now, you can get an access token for the MS Graph API using this certificate. 使用 MSCloudIdUtils PowerShell 模組中的 Get-MSCloudIdMSGraphAccessTokenFromCert Cmdlet,然後傳入您從上一個步驟中所取得的應用程式識別碼和指紋。Use the Get-MSCloudIdMSGraphAccessTokenFromCert cmdlet from the MSCloudIdUtils PowerShell module, passing in the Application ID and the thumbprint you obtained from the previous step.

    此螢幕擷取畫面顯示 PowerShell 視窗,其中包含可建立存取權杖的命令。

  7. 使用 PowerShell 指令碼中的存取權杖來查詢圖形 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.

  8. 查詢 directoryAudits 端點以擷取稽核記錄。Query the directoryAudits endpoint to retrieve the audit logs.

    此螢幕擷取畫面顯示 PowerShell 視窗,其中包含命令,可使用此程序中先前的存取權杖來查詢 directoryAudits 端點。

  9. 查詢 signins 端點以擷取登入記錄。Query the signins endpoint to retrieve the sign-in logs.

    此螢幕擷取畫面顯示 PowerShell 視窗,其中包含命令,可使用此程序中先前的存取權杖來查詢 signins 端點。

  10. 您現在可以選擇將此資料匯出為 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