您现在访问的是微软AZURE全球版技术文档网站,若需要访问由世纪互联运营的MICROSOFT AZURE中国区技术文档网站,请访问 https://docs.azure.cn.

教程:使用证书通过 Azure Active Directory 报告 API 获取数据

Azure Active Directory (Azure AD) 报告 API 通过一组基于 REST 的 API,可让你以编程方式访问数据。 可从各种编程语言和工具中调用这些 API。 如果想要访问 Azure AD 报告 API 而无需用户干预,则必须配置对证书的访问权限。

本教程介绍如何使用测试证书访问 MS 图形 API 以进行报告。 建议不要在生产环境中使用测试证书。

先决条件

  1. 若要访问登录数据,请确保拥有一个使用高级 (P1/P2) 许可证的 Azure Active Directory 租户。 请参阅 Azure Active Directory Premium 入门来升级 Azure Active Directory 版本。 请注意,如果在升级之前没有任何活动数据,则在升级到高级版许可证后,数据需要经过几天才会显示在报表中。

  2. 创建或切换到属于该租户的全局管理员、安全管理员、安全读取者或报表读取者角色的用户帐户 。

  3. 完成访问 Azure Active Directory 报告 API 的先决条件

  4. 下载并安装 Azure AD PowerShell V2

  5. 安装 MSCloudIdUtils。 此模块提供多个实用程序 cmdlet,包括:

    • 身份验证所需的 ADAL 库
    • 使用 ADAL 的用户、应用程序密钥和证书中的访问令牌
    • 处理分页结果的图形 API
  6. 如果是首次使用模块,请运行 Install-MSCloudIdUtilsModule;否则,请使用 Import-Module PowerShell 命令将其导入 。 会话应如以下屏幕所示:Windows PowerShell

  7. 使用 New-SelfSignedCertificate PowerShell commandlet 创建测试证书。

    $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 将其导出到证书文件。

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

使用证书通过 Azure Active Directory 报告 API 获取数据

  1. 导航到 Azure 门户,选择“Azure Active Directory”,然后选择“应用注册”并从列表中选择应用程序 。

  2. 在“应用程序注册”边栏选项卡上的“管理”部分中选择“证书和密码”,然后选择“上传证书” 。

  3. 选择上一步中的证书文件,然后选择“添加”。

  4. 请注意应用程序 ID 以及刚刚使用应用程序注册的证书的指纹。 若要查找指纹,请从门户中的应用程序页转到“管理”部分下的“证书和密码” 。 指纹将位于“证书”列表下。

  5. 在内联清单编辑器中打开应用程序清单,并验证 keyCredentials 属性是否更新为了新的证书信息,如下所示 -

    "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 的访问令牌。 使用 MSCloudIdUtils PowerShell 模块中的 Get-MSCloudIdMSGraphAccessTokenFromCert cmdlet,传入从上一步获取的应用程序 ID 和指纹。

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

  7. 在 PowerShell 脚本中使用访问令牌来查询图形 API。 使用 MSCloudIDUtils 中的 Invoke-MSCloudIdMSGraphQuery cmdlet 来枚举 signins 和 directoryAudits 终结点。 该 cmdlet 处理分多页的结果,并将这些结果发送到 PowerShell 管道。

  8. 查询 directoryAudits 终结点以检索审核日志。

    显示 PowerShell 窗口的屏幕截图,其中包含使用此过程前面的访问令牌来查询 directoryAudits 终结点的命令。

  9. 查询 signins 终结点以检索登录日志。

    显示 PowerShell 窗口的屏幕截图,其中包含使用此过程前面的访问令牌来查询 signins 终结点的命令。

  10. 现在可以选择将此数据导出为 CSV 并保存到 SIEM 系统。 也可以将脚本包装到计划的任务中,以便从租户定期获取 Azure AD 数据,不需将应用程序密钥存储在源代码中。

后续步骤