列出 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"
},
]
}
]
}