你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn

访问 Azure Active Directory 报告 API 的先决条件

Azure Active Directory (Azure AD) 报告 API 通过一组 REST API,可让你以编程方式访问数据。 可从许多编程语言和工具中调用这些 API。 报告 API 使用 OAuth 授权访问 Web API。

本文介绍如何使 Microsoft Graph 能够通过 PowerShell 访问 Azure 门户中的 Azure AD 报告 API

角色和许可证要求

若要通过 API 访问报告数据,需具有以下角色之一:

  • 安全读取者
  • 安全管理员
  • 全局管理员角色

Azure AD 租户只有在关联了 Azure AD Premium P1 或 P2 许可证的情况下才能访问租户的登录报告。 或者,如果目录类型为 Azure AD B2C,则无需满足任何其他许可证要求即可通过 API 访问登录报告。

即使是在使用脚本来访问报告 API,也需要注册。 注册会提供一个应用程序 ID,该 ID 是进行授权调用所必需的,代码也通过该 ID 来接收令牌。 若要将目录配置为访问 Azure AD 报告 API,必须以所需角色之一的身份登录到 Azure 门户

重要

在具有管理员权限的凭据下运行的应用程序可能具有非常强大的功能,因此请务必将应用程序的 ID 和机密凭据放置在一个安全的位置。

通过 Azure 门户启用 Microsoft Graph API

若要使应用程序在没有用户干预的情况下访问 Microsoft Graph,需要向 Azure AD 注册应用程序,然后授予 Microsoft Graph API 的权限。 本文介绍 Azure 门户中要遵循的步骤。

注册 Azure AD 应用程序

  1. Azure 门户中转到“Azure Active Directory”“应用注册”>。

  2. 选择“新注册”。

    “应用注册”页的屏幕截图,其中突出显示了“新建注册”按钮。

  3. 在“注册应用程序”页上:

    1. 为应用程序指定名称,例如 Reporting API application
    2. 对于“支持的帐户类型”设置,请选择“仅限此组织目录中的帐户”。
    3. 在“重定向 URI”部分中,从列表中选择“Web”,并键入 https://localhost
    4. 选择“注册” 。

    屏幕截图显示了可在其中输入此步骤的值的“注册应用程序”页。

授予权限

若要访问 Azure AD 报告 API,必须为应用授予 Microsoft Graph API 的“读取目录数据”和“读取所有审核日志数据”权限。

  1. “Azure Active Directory”>“应用注册”>“API 权限”,然后选择“添加权限”。

    “API 权限”菜单选项和“添加权限”按钮的屏幕截图。

  2. 选择“Microsoft Graph”>“应用程序权限”。

  3. 添加 Directory.ReadAll 和 AuditLog.Read.All,然后选择“添加权限”按钮。

    • 如果需要更多权限来运行所需的查询,可以立即添加这些权限,或者在 Microsoft Graph 中根据需要修改权限。
    • 有关详细信息,请参阅使用 Graph 浏览器

    屏幕截图显示了可在其中选择“应用程序权限”的“请求 API 权限”页。

  4. 在“报表 API 应用程序 - API 权限”页上,选择“授予管理员默认目录的许可”。

    屏幕截图显示了可在其中选择“授予管理员同意”的“报表 API 应用程序 - API 权限”页。

使用 Microsoft Graph Explorer 访问报表

配置应用注册后,可以在 Microsoft Graph 中运行活动日志查询。

  1. 使用“安全信息读取者”角色登录 https://graph.microsoft.com。 可能需要确认你已登录到适当的角色。 选择 Microsoft Graph 右上角的个人资料图标。

  2. 使用以下查询之一开始使用 Microsoft Graph 访问活动日志:

    • GET https://graph.microsoft.com/v1.0/auditLogs/directoryAudits
    • GET https://graph.microsoft.com/v1.0/auditLogs/signIns
    • 有关活动日志的 Microsoft Graph 查询的详细信息,请参阅活动报告 API 概述

    Microsoft Graph 中活动日志 GET 查询的屏幕截图。

使用 Microsoft Graph PowerShell 访问报表

若要使用 PowerShell 访问 Azure AD 报告 API,需要收集一些配置设置。 这些设置是在应用注册过程中创建的。

  • 租户 ID
  • 客户端应用 ID
  • 客户端机密或证书

在配置对报告 API 的调用时需要这些值。 建议使用证书,因为它更安全。

  1. 转到“Azure Active Directory”>“应用注册”。
  2. 复制目录(租户)ID。
  3. 复制“应用程序(客户端) ID”。
  4. 转到“应用注册”>选择你的应用程序>“证书&机密”>“证书”>“上传证书”并上传证书的公钥文件。

接下来,你将使用刚刚收集的配置设置进行身份验证。 打开 PowerShell 并运行以下命令,将占位符替换为你的信息。

Connect-MgGraph -ClientID YOUR_APP_ID -TenantId YOUR_TENANT_ID -CertificateName YOUR_CERT_SUBJECT ## Or -CertificateThumbprint instead of -CertificateName

Microsoft Graph PowerShell cmdlet:

以编程方式访问 API:

对 Azure Active Directory 报告 API 中的错误进行故障排除

访问 Microsoft Graph beta 终结点时发生 500 HTTP 内部服务器错误 - 我们目前不支持 Microsoft Graph beta 终结点 - 请确保使用 Microsoft Graph v1.0 终结点访问活动日志。

  • GET https://graph.microsoft.com/v1.0/auditLogs/directoryAudits
  • GET https://graph.microsoft.com/v1.0/auditLogs/signIns

错误:两个租户都不是 B2C 或租户没有高级许可证:访问登录报告需要 Azure Active Directory premium 1 (P1) 许可证。 如果访问登录时看到此错误消息,请确保你的租户已获得 Azure AD P1 许可证。

错误:用户没有允许的角色 - 如果在尝试使用 API 访问审核日志或登录时看到此错误消息,请确保你的帐户属于 Azure Active Directory 租户中的“安全读取者”或“报告读取者”角色。

错误:应用程序缺少 Azure AD“读取目录数据”或“读取所有审核日志数据”权限:重新访问本文的授予权限部分,以确保权限设置正确。

后续步骤