API Gateway:コンシューマー認証と承認

次の Java の例は、トークンを生成する方法を示しています。他の言語の場合は、対応するツールを使用してキーペアを生成してください。

1. Maven プロジェクトを作成し、次の依存関係を追加します:

   まず、Maven プロジェクトを作成し、次の依存関係を追加します:

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

2. トークンを生成する方法を選択します。

   対称鍵または非対称鍵のいずれかを使用してトークンを生成できます。要件に合ったメソッドを選択してください。

   対称鍵を使用してトークンを生成する

   コード例:

   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 型である必要があります。
           // コンシューマー ID を設定
           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("Generated JSON Web Token result is: \n" + jwtResult);
       }
   }

   コード設定:

   • privateKeyJson: これは、コンシューマーを作成するときに使用される JSON Web Key Set (JWKS) です。コンシューマーを作成するときに JWKS を記録するか、後でコンシューマーの基本設定ページから取得できます。

   • コンシューマー ID を設定します。たとえば、claims.setClaim("uid", "11215ac069234abcb8944232b79ae711") です。コンソールは、コンシューマーを作成するときにデフォルトのコンシューマー ID を生成します。この ID は必要に応じて変更できます。コンシューマー ID は、コンシューマーの基本設定ページから取得することもできます。

   • 暗号化アルゴリズムを設定します。たとえば、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 日未満である必要があります。トークンの有効期限が切れたら、セキュリティを確保するために再生成する必要があります。

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

   • ビジネスニーズに合わせて、JWKS PAYLOAD にカスタムパラメーターを追加できます。

   非対称鍵を使用してトークンを生成する

   コード例:

   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 型である必要があります。
           // コンシューマー ID を設定
           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);
   
           // ペイロードコンテンツを設定
           jws.setPayload(claims.toJson());
   
           // JWT を生成
           String jwtResult = jws.getCompactSerialization();
           System.out.println("Generated JSON Web Token result is: \n" + jwtResult);
       }
   }
   

   コード設定:

   • privateKeyJson、コンシューマー ID、および有効期限を設定します。これは、対称暗号化アルゴリズムの場合と同じです。

     暗号化アルゴリズムを設定します。たとえば、jws.setAlgorithmHeaderValue(AlgorithmIdentifiers.RSA_USING_SHA256) です。このアルゴリズムは、JWKS のアルゴリズムと一致する必要があります。

     非対称鍵暗号化アルゴリズムを使用してデータを暗号化するには、秘密鍵を使用する必要があります。

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

   • 必要に応じて、JWT の PAYLOAD にカスタムパラメーターを追加できます。

ステップ 1: 署名対象文字列の抽出

クライアントは HTTP リクエストからキーデータを抽出し、それを組み合わせて署名対象文字列を作成する必要があります。生成される署名対象文字列のフォーマットは次のとおりです:

HTTPMethod
Accept
Content-MD5
Content-Type
Date
Headers
PathAndParameters

これら 7 つのフィールドが署名対象文字列全体を構成します。フィールドは改行 (`\n`) で区切られます。`Headers` フィールドが空の場合、`Headers` フィールドの後に改行を追加しないでください。他のすべての空のフィールドについては、改行を保持する必要があります。署名では大文字と小文字が区別されます。各フィールドを抽出するためのルールは次のとおりです:

• HTTPMethod: 大文字の HTTP メソッド。たとえば、POST です。

• Accept: リクエストの `Accept` ヘッダーの値。このフィールドは空にすることができます。`Accept` ヘッダーを明示的に設定する必要があります。このヘッダーが空の場合、一部の HTTP クライアントはデフォルト値の */* を設定するため、署名検証が失敗します。

• Content-MD5: リクエストの `Content-MD5` ヘッダーの値。このフィールドは空にすることができます。`Content-MD5` ヘッダーは、リクエストにフォーム形式ではないボディがある場合にのみ計算する必要があります。次の Java コードは、Content-MD5 値を計算する方法を示しています:

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

• Content-Type: リクエストの `Content-Type` ヘッダーの値。このフィールドは空にすることができます。

• Date: リクエストの `Date` ヘッダーの値。date_offset 設定が有効になっていない場合、このフィールドは空にすることができます。それ以外の場合、ゲートウェイはこのフィールドを時間オフセット検証に使用します。

• Headers: 署名に含める特定のヘッダーを選択できます。ヘッダー文字列を連結するためのルールは次のとおりです:

  • 署名計算に含まれるヘッダーのキーはアルファベット順にソートされ、次のように連結されます。

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

  • ヘッダーの値が空の場合は、署名に `HeaderKey+":"+"\n"` を使用します。キーとコロンは保持する必要があります。

  • 署名に含まれるすべてのヘッダーキーのカンマ区切りリストは、`X-Ca-Signature-Headers` ヘッダーに配置されます。

  • 次のヘッダーはヘッダー署名計算に含まれません: `X-Ca-Signature`、`X-Ca-Signature-Headers`、`Accept`、`Content-MD5`、`Content-Type`、および `Date`。

• PathAndParameters: このフィールドには、パスと、クエリおよびフォームのすべてのパラメーターが含まれます。次のように構成されます:

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

  重要

  • クエリとフォームのパラメーターペアのキーはアルファベット順にソートされ、上記のように連結されます。

  • クエリまたはフォームパラメーターがない場合は、パスのみを使用します。? は追加しないでください。

  • パラメーターの値が空の場合は、キーのみを署名に含めます。等号は追加しないでください。

  • クエリまたはフォームに配列パラメーター (同じキー、異なる値) が存在する場合、署名計算には最初の値を使用します。

ステップ 2: 署名の暗号化

クライアントが HTTP リクエストからキーデータを抽出し、署名対象文字列をアセンブルした後、文字列を暗号化し、結果をエンコードして最終的な署名を生成する必要があります。暗号化フォーマットは次のとおりです。ここで、stringToSign は抽出された署名対象文字列、secret はアクセスキー (AK)/SK 認証設定のシークレットキー (SK)、sign は最終的に生成された署名です:

Mac hmacSha256 = Mac.getInstance("HmacSHA256"); // Macインスタンスを取得
byte[] secretBytes = secret.getBytes("UTF-8"); // シークレットをバイト配列に変換
hmacSha256.init(new SecretKeySpec(secretBytes, 0, secretBytes.length, "HmacSHA256")); // HmacSHA256で初期化
byte[] result = hmacSha256.doFinal(stringToSign.getBytes("UTF-8")); // 署名文字列を暗号化
String sign = Base64.encodeBase64String(result); // 結果をBase64でエンコード

要約すると、stringToSign を UTF-8 を使用してエンコードしてバイト配列を取得します。指定されたアルゴリズムでバイト配列を暗号化します。次に、結果を Base64 を使用してエンコードし、最終的な署名を生成します。

ステップ 3: 署名を追加する

クライアントは、署名検証のために API Gateway に送信される HTTP リクエストに次の 4 つのヘッダーを含める必要があります:

• x-ca-key: 値は AK/SK 認証設定のアクセスキー (AK) です。

• x-ca-signature-method: 署名アルゴリズム。有効な値は `HmacSHA256` または `HmacSHA1` です。これはオプションです。デフォルト値は `HmacSHA256` です。

• x-ca-signature-headers: 署名されたすべてのヘッダーキーのカンマ区切りリスト。これはオプションです。

• x-ca-signature: 署名。これは必須です。