MagicTradeBot API 认证与访问控制

MagicTradeBot 通过使用 JWT（JSON Web Tokens） 实现了安全的 基于令牌的身份验证，以保护其管理 API。这确保只有经过授权的机器人实例和用户才能访问交易服务、数据和与交易所相关的操作。

🚀 概览

管理应用要求所有 API 请求都使用有效的 JWT 令牌进行身份验证。令牌通过使用 HMAC SHA-256（HS256）算法和安全的 密钥 生成，并必须在每个 API 请求的 Authorization 头中传送。

⚙️ 配置

1. 设置 JWT 密钥

在 appsettings.json（或环境变量）中配置用于签署令牌的 JWT 密钥： 

{
  "JwtSettings": {
    "SecretKey": "YOUR_SECURE_RANDOM_SECRET_KEY", // 建议至少 32 个字符
    "Issuer": "MagicTradeBot",
    "Audience": "MagicTradeBotClients",
    "TokenExpiryMinutes": 120
  }
}

对于 Docker 或云部署，也可以使用环境变量： 

JwtSettings__SecretKey=YOUR_SECURE_RANDOM_SECRET_KEY

2. 启动机器人时生成令牌

当启动 MagicTradeBot 机器人实例 时，会提示输入身份验证凭据（例如 botId 和 authKey）。这些凭据将安全地传输到 管理应用 的身份验证端点。

如果凭据有效，管理应用将签发一个 签名的 JWT 令牌。该令牌将由机器人实例保存，并自动附加到所有后续 API 请求的 Authorization 头中。 

POST /api/auth/login

请求体：
{
  "botId": "bot-eu-01",
  "authKey": "your-secure-auth-key"
}

成功响应：
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

收到令牌后，机器人实例会在整个生命周期（扫描、交易、状态更新等）中，将 JWT 包含在所有 API 请求中： 

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

这确保了机器人实例与管理应用之间的通信是安全且已认证的。

🧩 访问控制与角色管理

  • 在 JWT Claims 中分配角色（如 role: "bot"、"admin" 或 "viewer"）
  • 使用策略或过滤器限制 API 端点访问（如 [Authorize(Roles = "admin")]）
  • 对于特定机器人的端点，验证令牌中的 botId 或 instanceId
  • 当令牌过期、无效或被篡改时拒绝访问

🧪 使用 JWT 的 API 请求示例

GET /api/trade/symbols

请求头：
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

✅ 最佳实践

  • 为 HS256 使用长度 ≥256 位的强密钥
  • 将密钥存储在环境变量或安全存储中（不要写在代码里）
  • 定期轮换 JWT 密钥
  • 设置较短的令牌有效期（如 1-2 小时），如需可启用刷新令牌机制
  • 启用 HTTPS 以防止令牌在传输过程中被窃取
  • 记录并监控所有令牌验证失败的尝试

🔐 可选增强功能

  • 实现 刷新令牌机制，以支持长时间会话
  • 结合 HMAC 或 HMAC + IP 绑定，防止跨服务器滥用令牌
  • 支持 JWT 黑名单或吊销机制，用于注销或泄露后的令牌失效

📎 Related Topics