Safeline Open Platform 账户管理 API 详解

概述

Safeline Open Platform 提供了一套完整的账户管理 API，包括用户登录、凭证管理、权限控制等功能。本文将详细介绍这些 API 的使用方法和注意事项。

登录认证 API

1. 密码登录 API

密码登录是最基础的认证方式，支持双重认证功能。

请求示例：

{
    "username": "admin",
    "password": "admin@password"
}

响应字段说明：

• id: 用户唯一标识
• is_locked: 账户是否被锁定
• permissions: 用户权限列表
• tfa_enabled: 是否启用双重认证
• session_timeout_time: 会话超时时间(秒)

常见错误：

• 密码错误会返回 "err": "error" 和错误信息
• 需要双重认证但未提供会返回 "err": "tfa-required"

2. 证书登录 API

证书登录提供更高安全性的认证方式。

GET 请求：检查证书是否有效 POST 请求：使用证书登录

特点：

• 支持双重认证
• 返回的用户信息结构与密码登录一致

凭证管理 API

1. 重置用户凭证 API

管理员可以使用此 API 重置用户密码或证书。

请求示例：

{
    "id": 23
}

响应特点：

• 重置证书会返回新的 token 和临时密码
• 重置密码会返回临时密码

2. 修改用户凭证 API

用户可自行修改认证方式或密码。

支持的操作：

• 重新生成证书
• 证书登录切换到密码登录
• 密码登录切换到证书登录
• 修改密码

请求字段说明：

• authentication_method: 认证方式(password/cert/ldap)
• old_password: 原密码(切换认证方式时需要)
• new_password: 新密码

API Token 管理

1. 获取 API Token

特点：

• 支持翻页参数
• 返回的 token 值部分会被隐藏

2. 创建 API Token

必填字段：

• name: token 名称
• permissions: 权限列表
• ip_policy: IP 访问策略

可选字段：

• expire_time: 过期时间(null 表示永不过期)

3. 修改和删除 API Token

可修改权限和 IP 策略，或直接删除 token。

双重认证配置

1. 获取认证链接

返回的 URI 可用于生成二维码，供认证 APP 扫描。

2. 启用/禁用双重认证

请求字段：

• action: enable/disable
• tfa_token: 认证码(启用/禁用时需要)

用户管理 API

1. 查询用户信息

查询方式：

• 按 ID 查询
• 按用户名查询(支持翻页)
• 获取用户列表(支持翻页)

2. 用户权限

需要 User Management 权限才能访问用户管理相关 API。

最佳实践

1. 安全建议：

   • 为重要操作启用双重认证
   • 定期更换 API Token
   • 限制 API Token 的 IP 访问范围

2. 错误处理：

   • 检查响应中的 err 字段
   • 根据 msg 字段提示用户

3. 会话管理：

   • 注意 session_timeout_time 设置
   • 长时间不操作需要重新登录

通过合理使用这些 API，可以实现完整的用户认证和管理功能，为 Safeline Open Platform 提供安全的访问控制。