API 开放鉴权

流量入口管理

创建流量入口

如需开放 API 鉴权，创建流量入口时需选择 面向合作伙伴开放 API 场景。

API 开放鉴权 - 图1

调用方认证方式

  • Key 认证：通过请求参数中的 appKey 字段，或请求头中的 X-App-Key 识别调用方。
  • HMAC 签名认证：使用 HMAC 对请求行、请求头、请求 Body 进行加密，具备较高的安全性，因根据 HTTP 签名算法标准草案设计，同时具备一定的通用性，具体请参见 HMAC 签名认证。
  • 参数签名认证：通过请求参数中的 appKey 字段识别调用方，同时通过对参数进行签名的 sign 字段完成校验，具体请参见 参数签名认证。
  • OAuth2 认证：基于 OAuth2 Client Credentials 模式，通过动态 Token 识别调用方，调用方可借助类似 Spring Cloud Security 的库实现。

调用方访问条件

  • 认证通过：仅需携带的调用凭证正确，即可通过识别进行访问。
  • 认证通过 + 授权许可：需额外针对调用方授权后，对应调用方才可访问。

调用者授权

若调用方访问条件选择 认证通过 + 授权许可，则需进行调用者授权。

您可以在创建流量入口时完成调用者授权，也可以在后续通过流量入口编辑操作完成。

API 开放鉴权 - 图2

调用量控制

您可以在创建流量入口时完成调用量控制，也可以在后续通过流量入口编辑操作完成。

API 开放鉴权 - 图3

调用方凭证管理

选择对应调用方后，点击 凭证。

API 开放鉴权 - 图4

调用方需根据流量入口的认证方式，选择正确的凭证。

API 开放鉴权 - 图5

签名认证算法

在平台提供的认证鉴权方式中，HMAC 签名认证和参数签名认证均可在识别出调用方的同时，对请求参数、Body 进行签名检查，从而进一步确保请求未被篡改或伪造。

HMAC 签名认证（推荐）

该算法主要依据 HTTP 签名草案 建立，使用 Kong 原生的 HMAC-Auth 插件。

Authorization 请求头构成

标准的 Authorization 请求头示例如下：

  1. Authorization: hmac appkey="wsK8t77fvAAs3i7878NSkC0j95ib3oVu", algorithm="hmac-sha256", headers="date request-line", signature="gaweQbATuaGmLrUr3HE0DzU1keWGCt3H96M28sSHTG8="

  • HMAC

    表明使用 HMAC 签名，此为静态字段，在所有请求中均为一致，无需变化。

  • appkey=”wsK8t77fvAAs3i7878NSkC0j95ib3oVu”

    即凭证中的 App Key 字段（如下图所示），需与 HMAC 以 ASCII 空格 分隔。

API 开放鉴权 - 图6

  • algorithm=”hmac-sha256”

    表示使用的签名算法，无需变化，需与 appkey 以 ASCII 字符 , 和 ASCII 空格 分隔。

  • headers=”date request-line”

    参与签名的请求头，均为小写，其内容是有序的，表明签名过程中字段拼接的顺序（具体请参见 签名算法），需与 algorithm 以 ASCII 字符 , 和 ASCII 空格 分隔。

    tip 提示 字段 request-line 相对特殊，表示请求行，例如 GET /api?name=bob HTTP/1.1，此处虽写在 headers 中，实质上并不是 header。

  • signature=”gaweQbATuaGmLrUr3HE0DzU1keWGCt3H96M28sSHTG8=”

    基于签名算法生成的签名值，需与 headers 以 ASCII 字符 , 和 ASCII 空格 分隔。

签名算法

  1. 不存在请求 Body

  • 必须请求头

    • Date
    • Authorization

  • Date 请求头

    Date 请求头需遵循 RFC1123 HTTP 规范，例如 Thu, 10 Dec 2020 08:47:43 GMT。

    • Unix 命令生成：

      1. env LANG=eng TZ=GMT date  '+%a, %d %b %Y %T %Z'

    tip 提示 若 Date 请求头时间与服务器时间的绝对差值大于 5 分钟，将被认为请求重放而拒绝请求。

  • Authorization 请求头

    请求头的构造，请参见 Authorization 请求头构成。此处将介绍如何生成签名。

    例如，对于以下请求：

    1. curl -i -X GET http://localhost/requests?name=bob \
    2.       -H 'Host: hmac.com' \
    3.       -H 'Date: Thu, 22 Jun 2017 21:12:36 GMT' \
    4.       -H 'Authorization: hmac appkey="wsK8t77fvAAs3i7878NSkC0j95ib3oVu", algorithm="hmac-sha256", headers="date host request-line", signature="FiPTWoayUGvlaAk6HbnxEzlXo0JO2HhiDGEwsR4yKPo="'

    Authorization 头中指定了用于签名的请求头，date、host 以及特殊的请求行 request-line，按序拼接字符串，获得待签名字符串：

    1. date: Thu, 22 Jun 2017 21:12:36 GMT
    2. host: hmac.com
    3. GET /requests?name=bob HTTP/1.1

    对待签名字符串进行签名，规则如下：

    1. signed_string=HMAC-SHA256(<signing_string>, "secret")
    2. signature=base64(<signed_string>)

    若 App Secret 为 qdWre3pJxitNm9NOBRH3EpWeVYepnt3f，可得到签名值为 FiPTWoayUGvlaAk6HbnxEzlXo0JO2HhiDGEwsR4yKPo=。

    使用 Unix 命令生成签名：

    1. echo -ne "date: Thu, 22 Jun 2017 21:12:36 GMT\nhost: hmac.com\nGET /requests?name=bob HTTP/1.1" | \
    2. openssl dgst -sha256 -hmac "qdWre3pJxitNm9NOBRH3EpWeVYepnt3f" -binary | base64
  1. 存在请求 Body

  • 必须请求头

    • Date
    • Digest
    • Authorization

  • Date 请求头

    与不存在 Body 时一致。

  • Digest 请求头

    需使用 SHA-256 对请求 Body 进行签名，例如 Body 为 {"name": "bob"}，则对应的 Digest 请求头为 Digest: SHA-256=lWuihDRnfX2CUVffGA74EjBnzVgnfHPywPXkYaKDC1I=，其中 Digest 请求头的 value 需以 SHA-256= 开头。

    使用 Unix 命令生成：

    1. echo -n '{"name": "bob"}' | openssl dgst -sha256 -binary | base64

    请求限制：请求 Body 大小不超过 10 m。

  • Authorization 请求头

    区别于不存在 Body 的情况，Headers 部分必须带上 Digest，示例如下：

    1. curl -i -X POST http://localhost/requests \
    2.       -H 'Host: hmac.com' \
    3.       -H 'Date: Thu, 22 Jun 2017 21:12:36 GMT' \
    4.       -H 'Digest: SHA-256=956ba28434677d7d825157df180ef8123067cd58277c73f2c0f5e461a2830b52' \
    5.       -H 'Authorization: hmac appkey="wsK8t77fvAAs3i7878NSkC0j95ib3oVu", algorithm="hmac-sha256", headers="date request-line digest", signature="CZSUv+kxWHN/vPEbwARg4r+NN3Vnb9+Aaq5XOQiENJA="'
    6.       -d '{"name": "bob"}'

    Authorization 头中指定了用于签名的请求头，date、host 、特殊的请求行 request-line 以及请求 Body 的签名值 digest，按序拼接字符串，获得待签名字符串：

    1. date: Thu, 22 Jun 2017 21:12:36 GMT
    2. GET /requests?name=bob HTTP/1.1
    3. digest: SHA-256=lWuihDRnfX2CUVffGA74EjBnzVgnfHPywPXkYaKDC1I=

    生成签名的方式请参见 不存在请求 Body。

代码示例 1：Java 语言实现带 Body 的 Post 请求客户端 HMAC 认证

tip 提示

该示例仅包含生成必要请求参数的代码，不包含发起 HTTP 请求的代码。

  1. import org.apache.commons.codec.binary.Base64;
  2. import org.apache.commons.codec.digest.HmacAlgorithms;
  3. import org.apache.commons.codec.digest.HmacUtils;
  5. import java.nio.charset.StandardCharsets;
  6. import java.security.MessageDigest;
  7. import java.time.ZoneId;
  8. import java.time.ZoneOffset;
  9. import java.time.ZonedDateTime;
  10. import java.time.format.DateTimeFormatter;
  11. import java.util.Locale;
  13. public class HmacTest {
  15.     private static final String APP_KEY = "088ed68d41504123b76d0812f328b560";
  16.     private static final String APP_SECRET = "01c28076047a46a9a3d46d9082f2a716";
  17.     private static final String URI = "/requests?name=bob";
  19.     public static void main(String[] args) {
  20.         String requestBody = "{\"name\": \"bob\"}";
  22.         // generate date
  23.         // 注意：日期小于 10 时，使用 RFC_1123_DATE_TIME 格式化后的字符串会因省略十位的 0 而被认为错误
  24.         DateTimeFormatter timeFormatter = DateTimeFormatter
  25.                 .ofPattern("EEE, dd MMM yyyy HH:mm:ss z", Locale.ENGLISH)
  26.                 .withZone(ZoneId.of("GMT"));
  27.         String date = timeFormatter.format(ZonedDateTime.now(ZoneOffset.UTC));
  29.         // generate digest
  30.         MessageDigest messageDigest = MessageDigest.getInstance("SHA-256");
  31.         messageDigest.update(requestBody.getBytes(StandardCharsets.UTF_8));
  32.         String digest = "SHA-256=" + Base64.encodeBase64String(messageDigest.digest());
  34.         // generate signature 
  35.         String signStrFormat = "date: %s\n%s %s HTTP/1.1\ndigest: %s";
  36.         String signStr = String.format(signStrFormat, date, "POST", URI, digest);
  37.         String signature = Base64.encodeBase64String(new HmacUtils(HmacAlgorithms.HMAC_SHA_256, APP_SECRET).hmac(signStr));
  39.         // generate Authorization
  40.         String authorizationFormat = "hmac appkey=\"%s\", algorithm=\"hmac-sha256\", headers=\"date request-line digest\", signature=\"%s\"";
  41.         String authorization = String.format(authorizationFormat, APP_KEY, signature);
  43.         System.out.println("signStr: \n" + signStr);
  44.         System.out.println("Date: " + date);
  45.         System.out.println("Digest: " + digest);
  46.         System.out.println("Authorization: " + authorization);
  48.         // 发起 http 请求时, 将上述打印的 Date, Digest, Authorization 设置到请求头
  49.     }
  50. }

代码示例 2：Go 语言实现带 Body 的 Post 请求客户端 HMAC 认证

tip 提示

该示例包含计算各必要参数和发起 HTTP 请求的完整代码。

  1. package main
  3. import (
  4.     "bytes"
  5.     "crypto/hmac"
  6.     "crypto/sha256"
  7.     "encoding/base64"
  8.     "fmt"
  9.     "io/ioutil"
  10.     "log"
  11.     "net/http"
  12.     "time"
  13. )
  15. func main() {
  16.     const (
  17.         body   = `{"name": "bob"}`
  18.         appKey = "088ed68d41504123b76d0812f328b560"
  19.         appSec = "01c28076047a46a9a3d46d9082f2a716"
  20.         host   = "https://go-http-demo-auth.daily.terminus.io"
  21.         uri    = "/requests?name=bob"
  22.     )
  24.     request, err := http.NewRequest(http.MethodPost, host+uri, bytes.NewBufferString(body))
  25.     if err != nil {
  26.         log.Fatalf("failed to NewRequest: %v", err)
  27.     }
  28.     if err = hmacRequest(request, appKey, appSec); err != nil {
  29.         log.Fatalf("failed to hmacRequest: %v", err)
  30.     }
  31.     response, err := http.DefaultClient.Do(request)
  32.     if err != nil {
  33.         log.Fatalf("failed to Do: %v", err)
  34.     }
  35.     data, err := ioutil.ReadAll(response.Body)
  36.     if err != nil {
  37.         log.Fatalf("failed to ReadAll: %v", err)
  38.     }
  39.     fmt.Printf("response body: %s", string(data))
  40. }
  42. // digest 实现对 Body 的摘要算法
  43. // 注意：计算签名时，要从 binary 以 Base64 方法编码为 string
  44. func digest(data []byte) (string, error) {
  45.     h := sha256.New()
  46.     if _, err := h.Write(data); err != nil {
  47.         return "", err
  48.     }
  49.     return "SHA-256=" + base64.StdEncoding.EncodeToString(h.Sum(nil)), nil
  50. }
  52. // date 获取计算签名所需的日志，注意 Location 是 Europe/London 时间，时间格式是 RFC1123
  53. func date() (string, error) {
  54.     location, err := time.LoadLocation("Europe/London")
  55.     if err != nil {
  56.         return "", err
  57.     }
  58.     return time.Now().In(location).Format(time.RFC1123), nil
  59. }
  61. // signature 根据给定的 date, method, reqeustLine, digest 和 appSecret 生成签名
  62. func signature(date, method, requestLine, digest, appSecret string) (signString, sign string, err error) {
  63.     signString = fmt.Sprintf("date: %s\n%s %s HTTP/1.1\ndigest: %s", date, method, requestLine, digest)
  64.     h := hmac.New(sha256.New, []byte(appSecret))
  65.     if _, err := h.Write([]byte(signString)); err != nil {
  66.         return signString, "", err
  67.     }
  68.     sign = base64.StdEncoding.EncodeToString(h.Sum(nil))
  69.     return signString, sign, nil
  70. }
  72. // authorization 构造请求头 Authorization 的值
  73. func authorization(appKey, sign string) string {
  74.     const authorizationPat = `Authorization: hmac appkey="%s", algorithm="hmac-sha256", headers="date request-line digest", signature="%s"`
  75.     return fmt.Sprintf(authorizationPat, appKey, sign)
  76. }
  78. // hmacRequest 将计算出的 date, digest, signature 等放入 *http.Request 的 headers
  79. func hmacRequest(r *http.Request, appKey, appSecret string) error {
  80.     body, err := r.GetBody()
  81.     if err != nil {
  82.         return err
  83.     }
  84.     // read body
  85.     data, err := ioutil.ReadAll(body)
  86.     if err != nil {
  87.         return err
  88.     }
  90.     // make digest
  91.     digest, err := digest(data)
  92.     if err != nil {
  93.         return err
  94.     }
  95.     fmt.Printf("digest: %s\n", digest)
  97.     // make date
  98.     date, err := date()
  99.     if err != nil {
  100.         return err
  101.     }
  102.     fmt.Printf("date: %s\n", date)
  104.     // make signature
  105.     signString, sign, err := signature(date, r.Method, r.URL.RequestURI(), digest, appSecret)
  106.     if err != nil {
  107.         log.Fatalf("failed to sinature: %v", err)
  108.     }
  109.     fmt.Printf("signString: %s\n", signString)
  110.     fmt.Printf("sign: %s\n", sign)
  112.     // make auth
  113.     author := authorization(appKey, sign)
  114.     fmt.Printf("authorization: %s\n", author)
  116.     // set headers
  117.     r.Header.Set("date", date)
  118.     r.Header.Set("digest", digest)
  119.     r.Header.Set("Authorization", author)
  121.     return nil
  122. }

参数签名认证

所有参数（包括 appKey，但不包括签名参数 sign 自身）均按照字符序增序排列，随后在排列的参数串末尾加上 appSecret，对完整字符串进行 SHA512 签名，生成签名参数 sign。

基于 URL 参数的签名

例如，调用参数为：

  1. /api?appKey=foobar&name=dadu&abc=123

参数名按照字母序升序排列，得到：

  1. abc=123&appKey=foobar&name=dadu

假设调用凭证中的 App Secret 为 my.secret，并将其附加到参数末尾，得到：

  1. abc=123&appKey=foobar&name=dadumy.secret

计算该字符串的 SHA512，得到签名值为：

  1. f97efc239eef4eafe69bfe41438740199d939e2e123c4c5a6b5d0b5e58d295a2818d6444c5c7b9e5985e751ad93f9c854e1966e59a63a1eeceb31e46641e291a

最终得到请求为：

  1. /api?appKey=foobar&name=dadu&abc=123&sign=f97efc239eef4eafe69bfe41438740199d939e2e123c4c5a6b5d0b5e58d295a2818d6444c5c7b9e5985e751ad93f9c854e1966e59a63a1eeceb31e46641e291a

基于 Body 的签名

对于 Post 等带有 Body 的请求，将对 Body 进行签名，此时分为两种情况：

  1. Content-Type 为 application/x-www-form-urlencoded

    此时与 URL 参数签名的方式一致，仅需将参数放至 Body 里面。

    请求限制：

    • Body 大小不超过 10 m。
    • 参数个数不大于 100 个。

  2. Content-Type 为 application/json

    例如，原始请求为：

    1. POST --header 'Content-Type: application/json'
    2.      -d '
    3. {"userName":"abc","gender":"male"}
    4. '

    将 Body 整体作为名为 Data 的参数，按照字母升序排列，得到：

    1. appKey=foobar&data={"userName":"abc","gender":"male"}

    假设调用凭证中的 App Secret 为 my.secret，并将其附加到参数末尾，得到：

    1. appKey=foobar&data={"userName":"abc","gender":"male"}my.secret

    计算该字符串的 SHA512，得到签名值为：

    1. ec23eeda5f88abe26311ed020439172eea409e3475875c87e9abfa8a6856138e767608e8497435f573ccb417a90448c78abdca4a0de12c4da4583aa3add7bf52

    最终调用方需发起的请求为：

    1. POST --header 'Content-Type: application/json'
    2.      -d '
    3. {
    4.   "data": "{\"userName\":\"abc\",\"gender\":\"male\"}",
    5.   "appKey": "foobar",
    6.   "sign": "ec23eeda5f88abe26311ed020439172eea409e3475875c87e9abfa8a6856138e767608e8497435f573ccb417a90448c78abdca4a0de12c4da4583aa3add7bf52"
    7. }'

    网关收到请求后，发至后端服务的真正请求和原始请求一致：

    1. POST --header 'Content-Type: application/json'
    2.      -d '
    3. {"userName":"abc","gender":"male"}
    4. '

    请求限制：Body 大小不超过 2 m。

加上时间戳的签名（可选）

增加名为 apiTimestamp 的时间戳参数，同其他参数一起字符升序排列之后，进行签名生成 sign。

  • 时间戳取值

    Unix 时间戳标准：从 1970 年 1 月 1 日（UTC/GMT 的午夜 ）开始所经过的秒数

    不同语言的获取方式：

    | Java | System.currentTimeMillis() / 1000 | | :————- | :—————————————————— | | JavaScript | Math.round(new Date().getTime()/1000) |

  • 时间校验

    添加 apiTimestamp 时间戳参数后，网关将判断是否和服务端时间接近，允许正负误差在 5 分钟内，否则鉴权失败。

  • Example

    以 URL 参数的签名为例：

    1. /api?appKey=foobar&name=dadu&abc=123

    加上参数 apiTimestamp=1581565619，进行字符升序排列，并加上 App Secret（假设为 my.secret）：

    1. abc=123&apiTimestamp=1581565619&appKey=foobar&name=dadumy.secret

    计算该字符串的 SHA512，得到签名值为：

    1. 61cabbc719e5edff3021ab5047bd3c5981e6348066d0416254dd529241a7135d57498dac56d2400139bc1040c5759d1c0798f1673913c537d10769c149879edd

    最终得到请求为：

    1. /api?appKey=foobar&name=dadu&abc=123&apiTimestamp=1581565619&sign=61cabbc719e5edff3021ab5047bd3c5981e6348066d0416254dd529241a7135d57498dac56d2400139bc1040c5759d1c0798f1673913c537d10769c149879edd

    基于 Body 签名的方式类似，apiTimestamp 需带在 Body 的 JSON 结构体中，例如：

    1. POST --header 'Content-Type: application/json'
    2.      -d '
    3. {
    4.   "data": "{\"userName\":\"abc\",\"gender\":\"male\"}",
    5.   "appKey": "foobar",
    6.   "apiTimestamp": 1581565619,
    7.   "sign": "xxxx",
    8. }'

代码示例

签名实现：

  1. // SignAuthHelper.Java
  2. import org.apache.commons.codec.binary.Hex;
  3. import org.apache.commons.lang.StringUtils;
  5. import java.io.UnsupportedEncodingException;
  6. import java.security.NoSuchAlgorithmException;
  7. import java.util.ArrayList;
  8. import java.util.List;
  9. import java.util.Map;
  10. import java.security.MessageDigest;
  11. import java.util.stream.Collectors;
  13. /**
  14.  * SignAuthHelper.java (JAVA 8+)
  15.  */
  16. public class SignAuthHelper {
  18.     public static Map<String, String> sign(Map<String,String> args, String appSecret) {
  19.         args.put("appKey", args.get("appKey"));
  20.         List<String> keyList = args.entrySet().stream().map(Map.Entry::getKey).sorted().collect(Collectors.toList());
  21.         List<String> kvList = new ArrayList<>();
  22.         for (String key: keyList) {
  23.             kvList.add(key + "=" + args.get(key));
  24.         }
  25.         String argsStr = StringUtils.join(kvList, "&") + appSecret;
  26.         String sign = string2SHA512(argsStr);
  27.         args.put("sign", sign);
  28.         return args;
  29.     }
  34.     private static String string2SHA512(String str) {
  35.         MessageDigest messageDigest;
  36.         String encdeStr = "";
  37.         try {
  38.             messageDigest = MessageDigest.getInstance("SHA-512");
  39.             byte[] hash = messageDigest.digest(str.getBytes("UTF-8"));
  40.             encdeStr = Hex.encodeHexString(hash);
  41.         } catch (NoSuchAlgorithmException | UnsupportedEncodingException e) {
  42.             e.printStackTrace();
  43.         }
  44.         return encdeStr;
  45.     }
  46. }

测试程序：

  1. import java.util.HashMap;
  2. import java.util.Map;
  4. import static org.junit.Assert.assertEquals;
  6. /**
  7.  * Main.java (JAVA 8+)
  8.  */
  9. public class Main {
  11.     public static void main(String[] args) {
  13.         // Sign Request URL Parameter
  14.         // GET https://domain.com?param1=123&param2=Abc&appKey=foobar&pampasCall=query.coupon
  15.         Map<String, String> params = new HashMap<>(2);
  16.         params.put("param1", "123");
  17.         params.put("param2", "Abc");
  18.         params.put("appKey", "foobar");
  19.         params.put("pampasCall", "query.coupon");
  20.         params = SignAuthHelper.sign(params, "my.secret");
  21.         String expect = "d6fee3145be668425f70878084f9d"
  22.             + "39fce3f7c5fca283ffc4c5d5a5568077334e9a505"
  23.             + "26e7e806758a66b7647ae9951f9324a0f921e28417e07d69beed79f7ef";
  24.         assertEquals(expect, params.get("sign"));
  25.         System.out.println("Verify Success");
  28.         // Sign Request Body
  29.         // POST --header 'Content-Type: application/json'
  30.         //      --header 'Accept: application/json'
  31.         //      -d '{"userName":"abc","gender":"male"}'
  32.         // 'https://domain.com'
  34.         params = new HashMap<>(4);
  36.         // request body use data as param name
  37.         params.put("data", "{\"userName\":\"abc\",\"gender\":\"male\"}");
  38.         params.put("appKey", "foobar");
  39.         expect = "ec23eeda5f88abe26311ed020439172eea409e34"
  40.             + "75875c87e9abfa8a6856138e767608e8497435f573c"
  41.             + "cb417a90448c78abdca4a0de12c4da4583aa3add7bf52";
  42.         params = SignAuthHelper.sign(params, "test-secret");
  43.         assertEquals(expect, params.get("sign"));
  44.         System.out.println("Verify Request Body Success");
  45.     }
  46. }