API Gateway：消費者認證鑒權

下文將通過Java樣本來說明Token的產生方式，其他語言您也可使用相關的工具產生金鑰組。

1. 建立Maven專案並注入依賴。

   首先，建立一個Maven專案，注入如下依賴項：

   <dependency>
       <groupId>org.bitbucket.b_c</groupId>
       <artifactId>jose4j</artifactId>
       <version>0.7.0</version>
   </dependency>

2. 選擇Token產生方式。

   您可以選擇使用預設對稱金鑰樣本產生Token和非對稱金鑰樣本產生Token兩種方式來產生Token。根據您的需求進行選擇：

   使用預設對稱金鑰樣本產生Token

   程式碼範例：

   package org.example;
   
   import java.io.UnsupportedEncodingException;
   import java.security.PrivateKey;
   
   import org.jose4j.base64url.Base64;
   import org.jose4j.json.JsonUtil;
   import org.jose4j.jwk.OctJwkGenerator;
   import org.jose4j.jwk.OctetSequenceJsonWebKey;
   import org.jose4j.jws.AlgorithmIdentifiers;
   import org.jose4j.jws.JsonWebSignature;
   import org.jose4j.jwt.JwtClaims;
   import org.jose4j.jwt.NumericDate;
   import org.jose4j.keys.HmacKey;
   import org.jose4j.lang.JoseException;
   import sun.lwawt.macosx.CSystemTray;
   
   public class Main {
       public static void main(String[] args) throws JoseException, UnsupportedEncodingException {
           //使用本文上述樣本
           String privateKeyJson = "{\n"
                   + "    \"k\": \"VoBG-oyqVoyCr9G56ozmq8n_rlDDyYMQOd_DO4GOkEY\",\n"
                   + "    \"kty\": \"oct\",\n"
                   + "    \"alg\": \"HS256\",\n"
                   + "}";
           JwtClaims claims = new JwtClaims();
           claims.setGeneratedJwtId();
           claims.setIssuedAtToNow();
           //設定到期時間，並且小於7天
           NumericDate date = NumericDate.now();
           date.addSeconds(120*60);
           claims.setExpirationTime(date);
           claims.setNotBeforeMinutesInThePast(1);
           //添加自訂參數，所有值請都使用String類型
           //設定消費者標識
           claims.setClaim("uid", "11215ac069234abcb8944232b79ae711");
           JsonWebSignature jws = new JsonWebSignature();
           //設定密碼編譯演算法
           jws.setAlgorithmHeaderValue(AlgorithmIdentifiers.HMAC_SHA256);
           jws.setKey(new HmacKey(Base64.decode(JsonUtil.parseJson(privateKeyJson).get("k").toString())));
           jws.setPayload(claims.toJson());
           String jwtResult = jws.getCompactSerialization();
           System.out.println("Generate Json Web token , result is \n " + jwtResult);
       }
   }

   代碼相關設定說明：

   • privateKeyJson：即在建立消費者時使用的JWKS，可以在建立消費者時記錄下自己使用的JWKS，也可以在建立消費者後，在消費者基礎配置頁擷取JWKS。

   • 設定消費者標識。即claims.setClaim("uid", "11215ac069234abcb8944232b79ae711")，該消費者標識為建立消費者時控制台預設產生，也可以根據自身邏輯進行修改。您也可以在建立消費者後，在消費者基礎配置頁擷取消費者標識。

   • 設定密碼編譯演算法。即jws.setAlgorithmHeaderValue(AlgorithmIdentifiers.HMAC_SHA256)，該密碼編譯演算法要和JWKS保持一致。

     說明

     目前支援的密碼編譯演算法有ES256、ES384、ES512、RS256、RS384、RS512、PS256、PS384、PS512、HS256、HS384、HS512和EdDSA。

     使用對稱式加密的時，需要對"k"進行解碼。

     jws.setKey(new HmacKey(Base64.decode(JsonUtil.parseJson(privateKeyJson).get("k").toString())));

   • 設定到期時間。到期時間需要小於7天，超出到期時間後，請重建Token，以保證Token的安全性。

     ...
         NumericDate date = NumericDate.now();
         date.addSeconds(120*60);
         claims.setExpirationTime(date);
         claims.setNotBeforeMinutesInThePast(1);
     ...

   • 根據自身業務需要，可以在JWKS的PAYLOAD中添加自訂參數。

   使用非對稱金鑰樣本產生Token

   程式碼範例：

   package org.example;
   
   import java.security.PrivateKey;
   import org.jose4j.json.JsonUtil;
   import org.jose4j.jws.AlgorithmIdentifiers;
   import org.jose4j.jws.JsonWebSignature;
   import org.jose4j.jwt.JwtClaims;
   import org.jose4j.jwt.NumericDate;
   import org.jose4j.lang.JoseException;
   import org.jose4j.jwk.RsaJsonWebKey;
   
   public class Main {
       public static void main(String[] args) throws JoseException {
           // 使用 JWK 格式的密鑰樣本
           String privateKeyJson = "{"
                   + "\"kty\":\"RSA\","
                   + "\"n\":\"u-8lR9lyRhu8tl4vRxOl7yfshssx5jRstabc9n4Rxrz102Z7TPFYrXBZHgf67Y0d-zx9tWd5j91WZxLHv4K6VWPN7zEWEQNn3vUg76dPHPzVkZJWziFPS1EvS4a2gRZdrE4nPogaQ72WySVC0yUF2fL0NKeOclD__coCFxn4QQjcDXyu_CUbI_FuDcdw267mVjjylAaFvOZHH0pXsV8m5zXlpc2aiemWYQJD9MtWRcoKlexWMkTwbEqW5-NWAl0Uo202ahDA1NiaQ98Ch4nw6g2E1GvwxxHkbvMuZcs5z8F5Ct_w0IPtvY7ngSyEN-WCU40oj-C5NUCy_73FpXXdWQ\","
                   + "\"e\":\"AQAB\","
                   + "\"d\":\"Uxg1IqSZazg-Y2AXhVTBrJG5egwD3yZU3qiN0IsDbx0DkFoisG2R6PXg4W9j2n7nv7sKVhgPXrXdyys5mIrDuperaVQJzrHzzlgSHQSb7VQ5Vekfanq95a5avAkvTrpF5raTkYl6G3OLZRqNhnA7Oxe6NEHVsOPxnBQignZgFtiBtCSZY4RVH6Dx4jFfBBNMC9ifyLWLpHut7eczvxI412nBkxgtEjSeFe083NlumO_ZYHbijPcQf5zFWPLEj2EvlgbSwhjc-uSAF4OljAyG_DHZYvztEIGMdxMgBHgwtEvCfzS6PeUgvUR-SB7m_L8z4gjz6TlpSYe3CnZqE69KdQ\","
                   + "\"p\":\"9mNw8U_GxbcSknueUeFFSU9wKD9E9P2ZO5RP5d7o3qGUXOfbrH_g5GMH3YJiPBDZs_2BYFrAACOY4YM-QTiXWVs4xS3OeD8AdH3wEXR_3DMEkOez3cNq3Jy3ZJabm7IUnPMIWv5gpIHghcx0YTtM5RabSgexLMKh2-6sB466378\","
                   + "\"q\":\"w0PzXI_8Q5jv15OUq-dV_Z0kp91Icumf6PEERZN4v3i3VolLBnamMiIQiF74ywclKpZmtfOQTfyL41Xj2vbm2Aus6akRsU3NhQlVtIQTzHWUuEQgMIJYDK7--FzEcZORm1qBiEffiWv6U-slyCcLcNDNT-wjMX8BrS4oWHIoCOc\","
                   + "\"dp\":\"fRRiY76yE_EqVn63Eq4ftGXFdEkaQpzzS1GxderBoTO506hI1rtcedTkS0lDgWa0fjE1mqq3SdrIY8NyuT13Z_9tRHxKkrS5EGpWkyXnOuwTZ1SY9P2dpD1SxJfIizPOTxb5qOf2O81LI-F1O18VXD8rultJUIXGEZaKcpO8vpU\","
                   + "\"dq\":\"V6EP_vMzD5b707AMYVURFx7Fi3vX_pHvzJcVBrBW2P6wsGouvDjU_tygtMKCPoL3X_RdJbynfwgeMyihd-ujz0L2F2pjYUF8QP7ecoNvays9UbBpDbwBDbge_pCLLDlAeAqW5PT0UXSew7hcnUVAciGSchKT_Kt1siVrv72DT_M\","
                   + "\"qi\":\"w5fENzxOivbbbUbawAWSuLgWPtvbTKn2XuPzwr_JzZH08-nadWwQFChcvAiCs8V-306TQOh8NfY308QpGDIq-iRfrS7CEePOjRzpHJfsaQ1IFQqzgDZ9VGdJRDlZqRHx0DbqwMlleVKTC6ER6varalbr4lKU-ZPUQLCzj0e4PMs\""
                   + "}";
   
           JwtClaims claims = new JwtClaims();
           claims.setGeneratedJwtId(); // 自動產生 jti（JWT ID）
           claims.setIssuedAtToNow();  // 設定簽發時間（iat）為目前時間
   
           // 設定到期時間，並且小於7天
           NumericDate date = NumericDate.now();
           date.addSeconds(120 * 60); // 設定到期時間為目前時間+120分鐘
           claims.setExpirationTime(date);
           claims.setNotBeforeMinutesInThePast(1); // nbf 時間為目前時間往前推1分鐘
   
           // 添加自訂參數，所有值請都使用String類型
           // 設定消費者標識
           claims.setClaim("uid", "11215ac069234abcb8944232b79ae711");
   
           JsonWebSignature jws = new JsonWebSignature();
           // 設定密碼編譯演算法為 RSA-SHA256
           jws.setAlgorithmHeaderValue(AlgorithmIdentifiers.RSA_USING_SHA256);
   
           // 解析私密金鑰並設定到簽名器中
           PrivateKey privateKey = new RsaJsonWebKey(JsonUtil.parseJson(privateKeyJson)).getPrivateKey();
           jws.setKey(privateKey);
   
           // 設定 payload 內容
           jws.setPayload(claims.toJson());
   
           // 產生 JWT Token
           String jwtResult = jws.getCompactSerialization();
           System.out.println("Generate Json Web token , result is \n " + jwtResult);
       }
   }
   

   代碼相關設定說明：

   • 設定privateKeyJson、消費者標識、到期時間，同對稱式加密演算法。

     設定密碼編譯演算法，即jws.setAlgorithmHeaderValue(AlgorithmIdentifiers.RSA_USING_SHA256)。該密碼編譯演算法和JWKS保持一致。

     對於非對稱式加密演算法，要用其私密金鑰進行加密。

     ...
         jws.setAlgorithmHeaderValue(AlgorithmIdentifiers.RSA_USING_SHA256);
         PrivateKey privateKey = new RsaJsonWebKey(JsonUtil.parseJson(privateKeyJson)).getPrivateKey();
         jws.setKey(privateKey);
     ...

   • 根據自身業務需要，可以在JWKS的PAYLOAD中添加自訂參數。

步驟一：提取簽名串

用戶端需要從Http請求中提取出關鍵資料，組合成一個簽名串，產生的簽名串格式如下：

HTTPMethod
Accept
Content-MD5
Content-Type
Date
Headers
PathAndParameters

以上7個欄位構成整個簽名串，欄位之間使用\n間隔，如果Headers欄位為空白，則不需要加\n，其他欄位如果為空白都需要保留\n。簽名對大小寫敏感。下面介紹每個欄位的擷取規則：

• HTTPMethod：HTTP的方法，全部大寫，例如POST。

• Accept：請求中的Accept頭的值，可為空白。建議顯式設定Accept Header。當Accept為空白時，部分Http用戶端會給Accept設定預設值為 */*，導致簽名校正失敗。

• Content-MD5：請求中的Content-MD5頭的值，可為空白。只有在請求存在Body且Body為非Form形式時才計算Content-MD5頭，下面是Java的Content-MD5值的參考計算方式：

  String content-MD5 = Base64.encodeBase64(MD5(bodyStream.getbytes("UTF-8")));

• Content-Type：請求中的Content-Type頭的值，可為空白。

• Date：請求中的Date頭的值，當未開啟date_offset配置時，可為空白，否則將用於時間位移校正。

• Headers：使用者可以選取指定的Header參與簽名，關於Header的簽名串拼接方式有以下規則：

  • 參與簽名計算的Header的Key按照字典排序後使用如下方式拼接。

    HeaderKey1 + ":" + HeaderValue1 + "\n"\+
    HeaderKey2 + ":" + HeaderValue2 + "\n"\+
    ...
    HeaderKeyN + ":" + HeaderValueN + "\n"

  • 某個Header的Value為空白，則使用HeaderKey+":"+"\n"參與簽名，需要保留Key和英文冒號。

  • 所有參與簽名的Header的Key的集合使用英文逗號分割放到Key為X-Ca-Signature-Headers的Header中。

  • 以下Header不參與Header簽名計算：X-Ca-Signature、X-Ca-Signature-Headers、Accept、Content-MD5、Content-Type、Date。

• PathAndParameters: 這個欄位包含Path，Query和Form中的所有參數，具體組織形式如下：

  Path + "?" + Key1 + "=" + Value1 + "&" + Key2 + "=" + Value2 + ... "&" + KeyN + "=" + ValueN

  重要

  • Query和Form參數對的Key按照字典排序後使用上面的方式拼接。

  • Query和Form參數為空白時，則直接使用Path，不需要添加？。

  • 參數的Value為空白時只保留Key參與簽名，等號不需要再加入簽名。

  • Query和Form存在數組參數時（key相同，value不同的參數） ，取第一個Value參與簽名計算。

步驟二：加密簽名

用戶端從HTTP請求中提取出關鍵資料群組裝成簽名串後，需要對簽名串進行加密及編碼處理，形成最終的簽名。具體的加密形式如下，其中 stringToSign 為提取出來的簽名串，secret 為AK/SK認證身份配置中的SK，sign 為最終產生的簽名：

Mac hmacSha256 = Mac.getInstance("HmacSHA256");
byte[] secretBytes = secret.getBytes("UTF-8");
hmacSha256.init(new SecretKeySpec(secretBytes, 0, secretBytes.length, "HmacSHA256"));
byte[] result = hmacSha256.doFinal(stringToSign.getBytes("UTF-8"));
String sign = Base64.encodeBase64String(result);

總結：將 stringToSign 使用UTF-8解碼後得到Byte數組，然後使用密碼編譯演算法對Byte數組進行加密，使用Base64演算法進行編碼，形成最終的簽名。

步驟三：添加簽名

用戶端需要將以下四個Header放在HTTP請求中傳輸給API Gateway，進行簽名校正：

• x-ca-key：取值為AK/SK認證身份配置中的AK。

• x-ca-signature-method：簽名演算法，取值HmacSHA256或者HmacSHA1，可選，預設值為HmacSHA256。

• x-ca-signature-headers：所有簽名頭的Key的集合，使用英文逗號分隔，可選。

• x-ca-signature：簽名，必選。