列出 signIn

命名空间:microsoft.graph

检索租户Microsoft Entra用户登录。 本质上是交互式的登录 (,其中用户名/密码作为身份验证令牌的一部分传递) 并且成功的联合登录当前包含在登录日志中。

最大和默认页面大小为 1,000 个对象,默认情况下,将首先返回最近的登录。 仅可在默认保留期内发生的Microsoft Entra ID登录事件。

注意

本文介绍如何从设备或服务导出个人数据。 这些步骤可用于支持一般数据保护条例 (GDPR) 下的义务。 授权租户管理员可以使用 Microsoft Graph 更正、更新或删除Microsoft Entra ID环境中的最终用户的身份信息,包括客户和员工用户配置文件或个人数据,例如用户名、工作职务、地址或电话号码。

此 API 可用于以下国家级云部署

全局服务 美国政府 L4 美国政府 L5 (DOD) 由世纪互联运营的中国

权限

为此 API 选择标记为最低特权的权限。 只有在应用需要它时,才使用更高的特权权限。 有关委派权限和应用程序权限的详细信息,请参阅权限类型。 要了解有关这些权限的详细信息,请参阅 权限参考

权限类型 最低特权权限 更高特权权限
委派(工作或学校帐户) AuditLog.Read.All 和 Directory.Read.All 不可用。
委派(个人 Microsoft 帐户) 不支持。 不支持。
应用程序 AuditLog.Read.All 和 Directory.Read.All 不可用。

重要

在具有工作或学校帐户的委托方案中,必须为登录用户分配受支持的Microsoft Entra角色或具有支持的角色权限的自定义角色。 此操作支持以下最低特权角色:

  • 全局读取者
  • 报告读取者
  • 安全管理员
  • 安全操作员
  • 安全信息读取者

appliedConditionalAccessPolicies 属性中列出的应用条件访问 (CA) 策略仅适用于具有允许他们读取条件访问数据的角色的用户和应用。 如果用户或应用有权读取登录日志,但无权读取条件访问数据,则将省略响应中的 appliedConditionalAccessPolicies 属性。 必须为已登录用户分配受支持的Microsoft Entra角色,并且应用被授予受支持的Microsoft Graph 权限。

  • 以下最低特权角色授予用户查看条件访问数据的权限:
    • 全局读取者
    • 安全管理员
    • 安全信息读取者
    • 条件访问管理
  • 应用程序必须至少具有以下权限之一才能在登录日志中查看 appliedConditionalAccessPolicy 对象:
    • Policy.Read.All
    • Policy.Read.ConditionalAccess
    • Policy.ReadWrite.ConditionalAccess

具有任何权限的已登录用户可以读取自己的登录日志。 此功能可帮助用户发现其帐户中的意外活动。 但是,用户无法从自己的日志中读取 CA 数据,除非他们具有上面标识的支持权限之一。

HTTP 请求

GET /auditLogs/signIns

可选的查询参数

此方法支持 $top$skiptoken$filter OData 查询参数,以帮助自定义响应。 若要了解一般信息,请参阅 OData 查询参数

若要避免请求超时,请使用获取所有登录的时间范围应用 $filter 参数,如 示例 1 中所示。

请求标头

名称 说明
Authorization 持有者 {token}。 必填。 详细了解 身份验证和授权

响应

如果成功,此方法在响应正文中返回 200 OK 响应代码和 signIn 对象集合。 对象的集合根据 createdDateTime 按降序列出。

示例

示例 1:列出特定时间段内的所有登录

请求

以下示例演示了列出特定时间段内所有登录的请求。

GET https://graph.microsoft.com/v1.0/auditLogs/signIns?$filter=createdDateTime ge 2024-07-01T00:00:00Z and createdDateTime le 2024-07-14T23:59:59Z

响应

以下示例显示了相应的响应。

注意:为了提高可读性,可能缩短了此处显示的响应对象。

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#auditLogs/signIns",
    "@odata.nextLink": "https://graph.microsoft.com/v1.0/auditLogs/signIns?$top=1&$skiptoken=9177f2e3532fcd4c4d225f68f7b9bdf7_1",
    "value": [
        {
            "id": "66ea54eb-6301-4ee5-be62-ff5a759b0100",
            "createdDateTime": "2023-12-01T16:03:35Z",
            "userDisplayName": "Test Contoso",
            "userPrincipalName": "testaccount1@contoso.com",
            "userId": "26be570a-ae82-4189-b4e2-a37c6808512d",
            "appId": "de8bc8b5-d9f9-48b1-a8ad-b748da725064",
            "appDisplayName": "Graph explorer",
            "ipAddress": "131.107.159.37",
            "clientAppUsed": "Browser",
            "correlationId": "d79f5bee-5860-4832-928f-3133e22ae912",
            "conditionalAccessStatus": "notApplied",
            "isInteractive": true,
            "riskDetail": "none",
            "riskLevelAggregated": "none",
            "riskLevelDuringSignIn": "none",
            "riskState": "none",
            "riskEventTypes": [],
            "resourceDisplayName": "Microsoft Graph",
            "resourceId": "00000003-0000-0000-c000-000000000000",
            "status": {
                "errorCode": 0,
                "failureReason": null,
                "additionalDetails": null
            },
            "deviceDetail": {
                "deviceId": "",
                "displayName": null,
                "operatingSystem": "Windows 10",
                "browser": "Edge 80.0.361",
                "isCompliant": null,
                "isManaged": null,
                "trustType": null
            },
            "location": {
                "city": "Redmond",
                "state": "Washington",
                "countryOrRegion": "US",
                "geoCoordinates": {
                    "altitude": null,
                    "latitude": 47.68050003051758,
                    "longitude": -122.12094116210938
                }
            },
            "appliedConditionalAccessPolicies": [
                {
                    "id": "de7e60eb-ed89-4d73-8205-2227def6b7c9",
                    "displayName": "SharePoint limited access for guest workers",
                    "enforcedGrantControls": [],
                    "enforcedSessionControls": [],
                    "result": "notEnabled"
                },
                {
                    "id": "6701123a-b4c6-48af-8565-565c8bf7cabc",
                    "displayName": "Medium signin risk block",
                    "enforcedGrantControls": [],
                    "enforcedSessionControls": [],
                    "result": "notEnabled"
                },
              ]
        }
    ]
}

示例 2:检索以“Graph”开头的 appDisplayName 的前 10 个登录应用

请求

以下示例显示了一个请求。

GET https://graph.microsoft.com/v1.0/auditLogs/signIns?&$filter=startsWith(appDisplayName,'Graph')&$top=10

响应

以下示例显示了相应的响应。 响应包含一个 @odata.nextLink 属性,该属性包含可用于检索接下来 10 个结果的 URL。

注意:为了提高可读性,可能缩短了此处显示的响应对象。

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#auditLogs/signIns",
    "@odata.nextLink": "https://graph.microsoft.com/v1.0/auditLogs/signins?$filter=startsWith(appDisplayName%2c%27Graph%27)&$top=10&$skiptoken=70f66c0893886b49370ffdb44cd8d137b1a12b9ba02f34a16f33c5e0f7c42fc7",
    "value": [
        {
            "id": "66ea54eb-6301-4ee5-be62-ff5a759b0100",
            "createdDateTime": "2023-12-01T16:03:32Z",
            "userDisplayName": "Test Contoso",
            "userPrincipalName": "testaccount1@contoso.com",
            "userId": "26be570a-ae82-4189-b4e2-a37c6808512d",
            "appId": "de8bc8b5-d9f9-48b1-a8ad-b748da725064",
            "appDisplayName": "Graph explorer",
            "ipAddress": "131.107.159.37",
            "clientAppUsed": "Browser",
            "correlationId": "d79f5bee-5860-4832-928f-3133e22ae912",
            "conditionalAccessStatus": "notApplied",
            "isInteractive": true,
            "riskDetail": "none",
            "riskLevelAggregated": "none",
            "riskLevelDuringSignIn": "none",
            "riskState": "none",
            "riskEventTypes": [],
            "resourceDisplayName": "Microsoft Graph",
            "resourceId": "00000003-0000-0000-c000-000000000000",
            "status": {
                "errorCode": 0,
                "failureReason": null,
                "additionalDetails": null
            },
            "deviceDetail": {
                "deviceId": "",
                "displayName": null,
                "operatingSystem": "Windows 10",
                "browser": "Edge 80.0.361",
                "isCompliant": null,
                "isManaged": null,
                "trustType": null
            },
            "location": {
                "city": "Redmond",
                "state": "Washington",
                "countryOrRegion": "US",
                "geoCoordinates": {
                    "altitude": null,
                    "latitude": 47.68050003051758,
                    "longitude": -122.12094116210938
                }
            },
            "appliedConditionalAccessPolicies": [
                {
                    "id": "de7e60eb-ed89-4d73-8205-2227def6b7c9",
                    "displayName": "SharePoint limited access for guest workers",
                    "enforcedGrantControls": [],
                    "enforcedSessionControls": [],
                    "result": "notEnabled"
                },
                {
                    "id": "6701123a-b4c6-48af-8565-565c8bf7cabc",
                    "displayName": "Medium signin risk block",
                    "enforcedGrantControls": [],
                    "enforcedSessionControls": [],
                    "result": "notEnabled"
                },
              ]
        }
    ]
}