sup-iam鉴权文档

简介

sup-iam鉴权文档规范了本项目内鉴权模块的具体实现规范，包括职责边界、输入输出参数和应用范围等。

sup-iam鉴权采用加密-校验的方式完成认证，原则上通过认证出请求方持有Secret Key来确定其持有权限

签名算法选型

常见云厂商签名算法借鉴

  1. AWS: AWS Signature Version 4（SigV4）,包括AWS4-HMAC-SHA256 / AWS4-ECDSA-P256-SHA256
  2. Azure: HMAC-SHA256
  3. 阿里云: HMAC-SHA1 / HMAC-SHA256

签名算法选定

本项目采用兼顾性能和安全性的HMAC-SHA256，它有如下优势

  • 安全性高
  • 性能优秀
  • 易于跨语言 SDK 实现
  • 支持防重放等机制

HMAC-SHA256服务端实现方案选择

鉴于Go标准库本身就提供了hmac算法和sha256算法，我们只需要补齐算法以外的接口就行了。

  • Go标准库

相关组件

1
2
crypto/hmac
crypto/sha256

优点：

  • 易用性：官方标准库，API稳定
  • 性能：极高，单次校验微秒级，轻松扛住高 QPS
  • 成熟度：被 AWS SDK、Kubernetes、etcd 间接使用

缺点：

  • 需要自己定义

    • canonical string 规则
    • header / body hash 规则
    • version 升级策略

  • 自定义协议+crypto
    为了进一步规范鉴权加密协议，我们需要更详细地自定义协议内容

关于协议的实现，我们要实现如下接口，将输入参数规范化

接口名 描述
BuildCanonicalString 提取Request参数转为规范String
HashContent 采用统一的哈希摘要算法
Sign 使用Secret Key 和 Canonical String构建数字摘要
Vertify 认证Request的合法性

接口依赖图如下

CanonicalRequest规范

参数列表

参数名 描述
Access Key 用于服务端定位SecretKey
请求方法 HTTP请求方法
请求路径 仅URL PATH,不包含Query内容
请求时间戳 用于防止重放攻击等,允许误差 ±300秒（默认，可配置）
请求内容摘要 防止请求内容被篡改
请求参数摘要 防止请求被篡改，同时用于校验

字段规范

字段 说明 算法
AccessKey 用于定位 SecretKey 原文
Method HTTP请求方法，大小写敏感 原文
Path 纯URL Path，不含 Query 原文
ContentHash 请求内容摘要，防篡改 SHA256
Timestamp 秒级时间戳 原文
Signature 请求参数摘要，防篡改 HMAC-SHA256（使用 SecretKey）

错误规范

这里参考阿里云风格

错误码 场景 HTTP Status
InvalidAccessKey AccessKey 不存在 401
SignatureMismatch 签名不匹配 403
RequestExpired Timestamp 超过允许范围 403
AccessDenied 权限不足 403
InvalidBodyHash Body 摘要不匹配 400
InvalidCanonicalRequest 请求参数规范不符合 400