123 lines
3.2 KiB
Markdown
123 lines
3.2 KiB
Markdown
一、认证方案概述
|
||
|
||
GoEdge 的 API 调用采用 令牌机制（AccessToken） 来进行用户／系统权限认证。
|
||
|
||
|
||
整体流程可简化为：
|
||
|
||
创建 AccessKey（用户或管理员）
|
||
|
||
使用 AccessKey 调用获取 AccessToken 接口
|
||
|
||
在后续所有 API 请求中，在 HTTP Header 中携带该 AccessToken 以认证身份
|
||
|
||
二、关键步骤详解
|
||
1. 创建 AccessKey
|
||
|
||
AccessKey 分为两种：
|
||
|
||
用户 AccessKey（针对平台用户，用于访问其用户相关数据）
|
||
|
||
|
||
管理员 AccessKey（针对系统／管理员用户，可操作所有管理员有权限的数据）
|
||
|
||
|
||
创建方式（概况）
|
||
|
||
用户版：在「平台用户 → 用户详情 → API AccessKey」页面创建。
|
||
|
||
|
||
管理员版：在「系统用户 → 用户详情 → API AccessKey」页面创建。
|
||
|
||
|
||
2. 获取 AccessToken
|
||
|
||
接口地址：/APIAccessTokenService/getAPIAccessToken（HTTP POST）
|
||
|
||
|
||
请求参数示例：
|
||
|
||
{
|
||
"type": "admin",
|
||
"accessKeyId": "<你的AccessKeyId>",
|
||
"accessKey": "<你的AccessKey>"
|
||
}
|
||
|
||
|
||
其中 "type" 字段：
|
||
|
||
值为 "user" 表示调用用户 AccessKey 获得 token
|
||
|
||
值为 "admin" 表示调用管理员 AccessKey 获得 token
|
||
|
||
|
||
响应结构示例：
|
||
|
||
{
|
||
"code": 200,
|
||
"data": {
|
||
"token": "<AccessToken字符串>",
|
||
"expiresAt": 1609686945
|
||
},
|
||
"message": "ok"
|
||
}
|
||
|
||
|
||
token 字段即为后续调用 API 时使用的 AccessToken。
|
||
|
||
|
||
expiresAt 表示该 token 的过期时间戳。
|
||
|
||
|
||
多次调用该接口会导致之前的 token 失效。
|
||
|
||
|
||
3. 使用 AccessToken 调用 API
|
||
|
||
在每次 API 请求（其它服务接口）中，需要在 HTTP Header 中加入字段：
|
||
|
||
X-Edge-Access-Token: <从上述获取接口得到的AccessToken>
|
||
|
||
|
||
来进行身份认证。
|
||
|
||
|
||
请求方法一般为 POST，URL 为 /服务/方法 形式。
|
||
|
||
|
||
三、重要注意事项 &机制要点
|
||
|
||
Token 有有效期 (expiresAt)，一旦过期要重新获取。
|
||
|
||
多次获取新的 token 会使之前的 token 失效，因此应注意 token 管理。
|
||
|
||
|
||
区别 “用户” 与 “管理员” 权限：对应的 AccessKey 类型不同、权限范围不同。
|
||
|
||
每次 API 调用都必须携带 header 的 token，否则将无法认证。
|
||
|
||
创建 AccessKey 前，需要在后台／平台对应页面进行授权／配置（用户／管理员视其角色而定）
|
||
|
||
四、认证方案优缺点（基于文档公开信息分析）
|
||
|
||
优点
|
||
|
||
简单易用：通过 AccessKey → 获取 token → 携带 token 调用接口，该流程直观。
|
||
|
||
分角色控制：用户 vs 管理员两种 AccessKey 类型，可以区分权限。
|
||
|
||
Token 有失效机制，有助于安全控制。
|
||
|
||
可能的局限/需注意点
|
||
|
||
未明确提及「刷新 token（refresh token）」机制：若 token 过期，需重新用 AccessKey 再次获取。
|
||
|
||
若 AccessKey／token泄露，则可能被滥用；要做好保密。
|
||
|
||
文档未说明 token 是加密 JWT 还是简单字符串，也未说明 Scope（权限粒度）如何定义。
|
||
|
||
对于高频调用或长期服务而言，每次新的 token 使旧 token 失效，可能影响服务连续性。
|
||
|
||
五、总结一句话
|
||
|
||
在 GoEdge 的 API 中，认证方案为：“先用对应角色的 AccessKey 获取一个 AccessToken，然后在所有 API 请求头中携带该 token 以识别调用者身份与权限”。 |