教程:使用证书通过 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. 请注意应用程序 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 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,传入从上一步获取的应用程序 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.

    显示 PowerShell 窗口的屏幕截图,其中包含用于创建访问令牌的命令。

  7. 在 PowerShell 脚本中使用访问令牌来查询图形 API。Use the access token in your PowerShell script to query the Graph API. 使用 MSCloudIDUtils 中的 Invoke-MSCloudIdMSGraphQuery cmdlet 来枚举 signins 和 directoryAudits 终结点。Use the Invoke-MSCloudIdMSGraphQuery cmdlet from the MSCloudIDUtils to enumerate the signins and directoryAudits endpoint. 该 cmdlet 处理分多页的结果,并将这些结果发送到 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