API Gateway:JWT ベースのトークン認証

1. トークンベースの認証

ワークフロー

API Gateway は、JWT 認証プラグインを使用して認証を処理します。ワークフローは次のとおりです。

1. クライアントは、トークンを含むリクエストを API Gateway に送信します。

2. API Gateway は、JWT 認証プラグインに設定された公開鍵を使用してトークンを検証します。トークンが有効な場合、API Gateway はリクエストをバックエンドサービスに渡します。

3. バックエンドサービスはリクエストを処理し、レスポンスを返します。

4. API Gateway は、バックエンドサービスからのレスポンスをクライアントに返します。

このプロセス全体を通じて、API Gateway はトークン認証を使用し、お客様独自のユーザーシステムに基づいて API アクセスを認可します。以降のセクションでは、API Gateway が認証に使用する JSON Web トークン (JWT) について説明します。

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ

{
  'typ': 'JWT',
  'alg': 'HS256'
}

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9

iss：発行者。トークンを発行したプリンシパル。このクレームは文字列です。
sub：サブジェクト。トークンのサブジェクトであるプリンシパル。この値は、発行者のスコープ内で一意です。大文字と小文字を区別する文字列で、最大長は 255 ASCII 文字です。
aud：オーディエンス。トークンの対象となる受信者。これは、大文字と小文字を区別する文字列の配列です。
exp：有効期限。この時刻を過ぎるとトークンは無効と見なされます。このクレームは、1970-01-01T00:00:00Z からの秒数を表す整数です。
iat：発行日時。トークンが発行された時刻。このクレームは、1970-01-01T00:00:00Z からの秒数を表す整数です。
jti：JWT ID。トークンの一意の識別子。この値は、同じ発行者によって作成された各トークンに対して一意であり、衝突を避けるために暗号学的にランダムな値であることがよくあります。この値は、攻撃者が取得できないランダムなエントロピーコンポーネントを構造化トークンに追加し、トークンの推測やリプレイ攻撃を防ぐのに役立ちます。

{
  "sub": "1234567890",
  "name": "John Doe"
}

JTdCJTBBJTIwJTIwJTIyc3ViJTIyJTNBJTIwJTIyMTIzNDU2Nzg5MCUyMiUyQyUwQSUyMCUyMCUyMm5hbWUlMjIlM0ElMjAlMjJKb2huJTIwRG9lJTIyJTBBJTdE

// JavaScript
var encodedString = base64UrlEncode(header) + '.' + base64UrlEncode(payload);
var signature = HMACSHA256(encodedString, '$secret');

2. JWT プラグインによる API の保護

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

RsaJsonWebKey rsaJsonWebKey = RsaJwkGenerator.generateJwk(2048);
rsaJsonWebKey.setKeyId("uniq_key");
final String publicKeyString = rsaJsonWebKey.toJson(JsonWebKey.OutputControlLevel.PUBLIC_ONLY);
final String privateKeyString = rsaJsonWebKey.toJson(JsonWebKey.OutputControlLevel.INCLUDE_PRIVATE);

---
parameter: X-Token         # JWT を取得するパラメーター。これは API パラメーターに対応します。
parameterLocation: header  # JWT を読み取る場所。API がマッピングモードの場合はこのパラメーターはオプションですが、パススルーモードの場合は必須です。有効な値：「query」および「header」。
claimParameters:           # クレームパラメーターのマッピング。API Gateway は JWT クレームをバックエンドパラメーターにマッピングします。
- claimName: aud           # クレーム名。パブリッククレームとプライベートクレームがサポートされています。
  parameterName: X-Aud     # マッピングされたパラメーターの名前。
  location: header         # マッピングされたパラメーターの場所。有効な値：「query」、「header」、「path」、「formData」。
- claimName: userId        # クレーム名。パブリッククレームとプライベートクレームがサポートされています。
  parameterName: userId    # マッピングされたパラメーターの名前。
  location: query          # マッピングされたパラメーターの場所。有効な値：「query」、「header」、「path」、「formData」。
preventJtiReplay: false    # `jti` クレームに対してアンチリプレイチェックを有効にするかどうかを指定します。デフォルト値： false。
# セクション 2.1 で生成された JSON Web キー (JWK) の公開鍵。
jwk:
  kty: RSA
  e: AQAB
  use: sig
  kid: uniq_key
  alg: RS256
  n: qSVxcknOm0uCq5vGsOmaorPDzHUubBmZZ4UXj-9do7w9X1uKFXAnqfto4TepSNuYU2bA_-tzSLAGBsR-BqvT6w9SjxakeiyQpVmexxnDw5WZwpWenUAcYrfSPEoNU-0hAQwFYgqZwJQMN8ptxkd0170PFauwACOx4Hfr-9FPGy8NCoIO4MfLXzJ3mJ7xqgIZp3NIOGXz-GIAbCf13ii7kSStpYqN3L_zzpvXUAos1FJ9IPXRV84tIZpFVh2lmRh0h8ImK-vI42dwlD_hOIzayL1Xno2R0T-d5AwTSdnep7g-Fwu8-sj4cCRWq3bd61Zs2QOJ8iustH0vSRMYdP5oYQ

3. トークン発行サービスのサンプルコード

import java.security.PrivateKey; 
import org.jose4j.json.JsonUtil;
import org.jose4j.jwk.RsaJsonWebKey;
import org.jose4j.jwk.RsaJwkGenerator;
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;
public class GenerateJwtDemo {
    public static void main(String[] args) throws JoseException  {
          // API Gateway で設定した keyId を使用します。
        String keyId = "uniq_key";
          // セクション 2.1 で生成したキーペアを使用します。
        String privateKeyJson = "{\n"
            + "  \"kty\": \"RSA\",\n"
            + "  \"d\": "
            +
            "\"O9MJSOgcjjiVMNJ4jmBAh0mRHF_TlaVva70Imghtlgwxl8BLfcf1S8ueN1PD7xV6Cnq8YenSKsfiNOhC6yZ_fjW1syn5raWfj68eR7cjHWjLOvKjwVY33GBPNOvspNhVAFzeqfWneRTBbga53Agb6jjN0SUcZdJgnelzz5JNdOGaLzhacjH6YPJKpbuzCQYPkWtoZHDqWTzCSb4mJ3n0NRTsWy7Pm8LwG_Fd3pACl7JIY38IanPQDLoighFfo-Lriv5z3IdlhwbPnx0tk9sBwQBTRdZ8JkqqYkxUiB06phwr7mAnKEpQJ6HvhZBQ1cCnYZ_nIlrX9-I7qomrlE1UoQ\",\n"
            + "  \"e\": \"AQAB\",\n"
            + "  \"kid\": \"uniq_key\",\n"
            + "  \"alg\": \"RS256\",\n"
            + "  \"n\": \"vCuB8MgwPZfziMSytEbBoOEwxsG7XI3MaVMoocziP4SjzU4IuWuE_DodbOHQwb_thUru57_Efe"
            +
            "--sfATHEa0Odv5ny3QbByqsvjyeHk6ZE4mSAV9BsHYa6GWAgEZtnDceeeDc0y76utXK2XHhC1Pysi2KG8KAzqDa099Yh7s31AyoueoMnrYTmWfEyDsQL_OAIiwgXakkS5U8QyXmWicCwXntDzkIMh8MjfPskesyli0XQD1AmCXVV3h2Opm1Amx0ggSOOiINUR5YRD6mKo49_cN-nrJWjtwSouqDdxHYP-4c7epuTcdS6kQHiQERBd1ejdpAxV4c0t0FHF7MOy9kw\"\n"
            + "}";
        JwtClaims claims = new JwtClaims();
        claims.setGeneratedJwtId();
        claims.setIssuedAtToNow();
        // 有効期限は7日未満で設定する必要があります。
        NumericDate date = NumericDate.now();
        date.addSeconds(120*60);
        claims.setExpirationTime(date);
        claims.setNotBeforeMinutesInThePast(1);
        claims.setSubject("YOUR_SUBJECT");
        claims.setAudience("YOUR_AUDIENCE");
        // カスタムパラメーターを追加します。すべての値は String 型にする必要があります。
        claims.setClaim("userId", "1213234");
        claims.setClaim("email", "userEm***@youapp.com");
        JsonWebSignature jws = new JsonWebSignature();
        jws.setAlgorithmHeaderValue(AlgorithmIdentifiers.RSA_USING_SHA256);
          // このパラメーターは必須です。
        jws.setKeyIdHeaderValue(keyId);
        jws.setPayload(claims.toJson());
        PrivateKey privateKey = new RsaJsonWebKey(JsonUtil.parseJson(privateKeyJson)).getPrivateKey();
        jws.setKey(privateKey);
        String jwtResult = jws.getCompactSerialization();
        System.out.println("JSON Web トークンを生成しました。結果は " + jwtResult);
    }
}

次の点にご注意ください。

1. keyId はグローバルに一意である必要があり、次の 3 つの場所で一致させる必要があります。

• 「2.1 JSON Web キー (JWK) ペアの生成」セクションでキーペアを生成するときに指定する keyId。

• 「2.3 JWT プラグインの設定」セクションで JWT 認証プラグインに設定する kid。

• コード内の keyId。これは JsonWebSignature オブジェクトの KeyIdHeaderValue プロパティの値です。このプロパティは必須です。

2. privateKeyJson には、秘密鍵の JWK JSON 文字列を使用します。これは、「セクション 2.1」でオンラインで生成したもの、またはキーペアをローカルで生成した場合は privateKeyString JSON 文字列を使用できます。

   privateKeyString は JSON 文字列です。

3. 有効期間は必須で、7日未満に設定する必要があります。

4. すべてのカスタムパラメーターの値は String 型にしてください。

4. API Gateway のエラーレスポンス

予期しないステータスコードを受け取った場合は、X-Ca-Error-Code レスポンスヘッダーで ErrorCode を、X-Ca-Error-Message ヘッダーで ErrorMessage を確認してください。エラーコードが A403JT または I400JD の場合は、jwt.io を使用して token の有効性とフォーマットを検証してください。