如何用FusionAuth创建永久用户密钥实现API认证授权？

一、User-Key的生成与存储 #

1. 注册时自动生成User-Key #

在用户注册流程中，通过FusionAuth的Webhook或自定义注册逻辑，生成一个唯一、高熵的永久密钥（比如UUID v4或32位以上的随机字符串），将其存入用户的**自定义字段（Custom User Data）**中。

• 操作示例：在注册完成的Webhook里调用FusionAuth的用户更新API，添加user.data.userKey字段，值为生成的密钥。
• 注意：密钥长度至少32位，避免碰撞和暴力破解风险。

2. 手动更新User-Key #

支持两种更新方式：

• 管理员通过FusionAuth管理后台的用户详情页，在「自定义数据」模块直接修改userKey的值。
• 调用FusionAuth的PATCH /api/user/{userId} API，传入更新后的data.userKey字段完成修改。

二、API请求的验证流程实现 #

1. 提取请求头中的User-Key #

自研应用从API请求的Header（比如X-User-Key）中获取待验证的user-key。

2. 验证User-Key的有效性 #

不要使用Login API，直接调用FusionAuth的用户搜索API匹配密钥：

• 请求示例（POST /api/user/search）：

{
  "query": {
    "data.userKey": "待验证的密钥值"
  },
  "fields": ["id", "roles", "data", "registrations"]
}

• 校验规则：若返回结果包含且仅包含一个用户，判定密钥有效；返回空或多个用户则直接返回401 Unauthorized。

3. 权限校验 #

基于返回的用户信息，完成资源访问权限验证：

• 检查用户角色（Roles）：比如确认用户是否持有api-access通用角色，或对应接口的特定角色（如order-read）。
• 检查用户应用注册状态：确认用户在当前自研应用中的注册状态正常，且拥有目标资源的访问权限（可在FusionAuth应用的权限配置中预设）。

4. 返回结果 #

验证通过后，返回用户必要数据（如用户ID、角色、自定义字段等），或直接处理API请求并返回业务响应。

三、安全优化建议 #

• 强制HTTPS传输：确保所有API请求使用HTTPS，避免密钥在传输过程中被窃取。
• 密钥轮换机制：即便设计为永久密钥，仍需提供手动轮换功能，防止密钥泄露后无法补救。
• 添加速率限制：对User-Key验证请求设置速率限制，抵御暴力破解攻击。
• 审计日志：记录所有User-Key的验证请求（包括成功/失败状态），便于后续排查和审计。

内容的提问来源于stack exchange，提问作者Javier Gonzalez Moncayo