OneLogin如何通过REST API查询带过滤分页的用户MFA注册使用状态

1. 前置准备 #

• 首先在OneLogin管理后台创建API凭证：路径为「开发者 > API凭证」，分配用户读取、MFA信息读取的只读权限即可，不要分配更高操作权限
• 保存生成的client_id、client_secret，同时确认你当前OneLogin实例的区域域名（如美区为us、欧区为eu等，拼接为最终接口域名https://<区域标识>.onelogin.com）

2. 获取API访问令牌 #

所有接口调用前需要先获取鉴权令牌：

• 调用接口：POST https://<你的区域>.onelogin.com/auth/oauth2/v2/token
• 鉴权方式：将client_id:client_secret做Base64编码后放在Basic认证头中
• 请求参数：固定grant_type=client_credentials
• 返回的access_token有效期为3600秒，过期前重新请求刷新即可

3. 核心数据拉取逻辑 #

3.1 拉取全量用户基础信息（支持过滤、分页） #

调用用户列表接口拉取符合条件的用户：

• 调用接口：GET https://<你的区域>.onelogin.com/api/1/users
• 分页实现：通过page（当前页码，从1开始）、per_page（单页条数，最大支持1000）参数控制分页，返回头中的X-Total-Count字段为总用户数，可用来计算总页数
• 过滤实现：接口支持直接传入过滤参数缩小查询范围，常用参数包括：
  • status：按用户状态过滤，1为激活用户
  • department：按部门过滤
  • last_login：按最近登录时间范围过滤
  • updated_at：按用户信息最近更新时间过滤，适合做增量同步

3.2 拉取单用户MFA注册状态 #

遍历拿到的用户ID，调用单用户MFA设备接口查询注册状态：

• 调用接口：GET https://<你的区域>.onelogin.com/api/1/users/{user_id}/mfa_devices
• 返回结果为空则说明用户未注册任何MFA设备，不为空则会返回所有绑定的MFA设备类型、绑定时间、最近使用时间等注册相关信息

3.3 拉取MFA使用状态（可选） #

如果需要查询用户MFA的使用记录（如最近一次MFA验证成功/失败时间），可以调用事件日志接口过滤查询：

• 调用接口：GET https://<你的区域>.onelogin.com/api/1/events
• 过滤参数：传入event_type_id=12（MFA验证成功）、event_type_id=13（MFA验证失败）即可筛选出所有MFA相关的操作记录，同时可结合时间范围、用户ID做过滤

4. 注意事项 #

• 接口限流：OneLogin开放API默认限流为每分钟1000次请求，并发请求不要过高，遇到429状态码时按返回头Retry-After指定的秒数等待后重试即可
• 批量优化：如果用户量较大，可以将用户ID批量缓存后并发查询MFA接口，同时避免重复查询已确认状态的用户
• 增量同步：如果需要定期拉取数据，可记录上一次拉取的最大updated_at时间，下次拉取用户列表时传入该时间作为过滤条件，仅拉取更新过的用户，减少接口调用量

内容的提问来源于stack exchange，提问作者Sandip Khanzode