API Gateway:JWT認証

1. JWKを取得する

RFC 7517準拠のJWKは、JWTの署名と認証に使用されます。 を設定する場合は、JWT认证プラグイン、有効なJWK手動またはオンラインを使用してJWKの発電機そのようなs mkjwk.org。 次の例は、有効なJWKを示しています。 JWKの例では、秘密鍵を使用してトークンに署名し、公開鍵をJWT認証プラグインで設定して署名を認証します。

{
  "kty": "RSA",
  "e": "AQAB",
  "kid": "O9fpdhrViq2zaaaBEWZITz",
  "use": "sig",
  "alg": "RS256",
  "n": "qSVxcknOm0uCq5vGsOmaorPDzHUubBmZZ4UXj-9do7w9X1uKFXAnqfto4TepSNuYU2bA_-tzSLAGBsR-BqvT6w9SjxakeiyQpVmexxnDw5WZwpWenUAcYrfSPEoNU-0hAQwFYgqZwJQMN8ptxkd0170PFauwACOx4Hfr-9FPGy8NCoIO4MfLXzJ3mJ7xqgIZp3NIOGXz-GIAbCf13ii7kSStpYqN3L_zzpvXUAos1FJ9IPXRV84tIZpFVh2lmRh0h8ImK-vI42dwlD_hOIzayL1Xno2R0T-d5AwTSdnep7g-Fwu8-sj4cCRWq3bd61Zs2QOJ8iustH0vSRMYdP5oYQ"
}        

上記のJWKはJSON形式です。 JWT認証プラグインをYAML形式で設定する場合は、JWKをYAML形式で使用する必要があります。*

• JWT認証プラグインの場合、公開鍵を設定するだけで済みます。 秘密鍵を安全に保管してください。 次の表に、JWT認証プラグインでサポートされている署名アルゴリズムを示します。

2. プラグインの設定

JWT認証プラグインはJSON形式またはYAML形式で構成できます。これらの2つの形式は同じスキーマであるためです。 yaml to jsonツールを使用して、プラグインの構成形式を変換できます。 次の例は、YAML形式のプラグイン構成テンプレートを示しています。

---
parameter: X-Token           # The parameter from which the JWT is read. It corresponds to an API parameter. 
parameterLocation: header    # The location from which the JWT is read. Valid values: query and header. This parameter is optional if Request Mode for the bound API is set to Map (Filter Out Unknown Parameters) or Map (Pass-through Unknown Parameters). This parameter is required if Request Mode for the bound API is set to Pass-through.
preventJtiReplay: false      # Controls whether to enable the anti-replay check for jti. Default value: false.
bypassEmptyToken: false      # Controls whether to forward requests that do not include tokens to backend services without verification.
ignoreExpirationCheck: false # Controls whether to ignore the verification of the exp setting.
orAppAuth: false # The default value is false. Both the Alibaba Cloud App authentication and JWT authentication are required. If the value is true, the other authentication method is not required if one authentication is passed.
claimParameters:             # The conversion of claims to parameters. API Gateway maps JWT claims to backend parameters.
- claimName: aud             # The name of the JWT claim, which can be public or private.
  parameterName: X-Aud       # The name of the backend parameter, to which the JWT claim is mapped.
  location: header           # The location of the backend parameter, to which the JWT claim is mapped. Valid values: query, header, path, and formData.
- claimName: userId          # The name of the JWT claim, which can be public or private.
  parameterName: userId      # The name of the backend parameter, to which the JWT claim is mapped.
  location: query            # The location of the backend parameter, to which the JWT claim is mapped. Valid values: query, header, path, and formData.
#
# Public key in the JWK
jwk:
  kty: RSA
  e: AQAB
  use: sig
  alg: RS256
  n: qSVxcknOm0uCq5vGsOmaorPDzHUubBmZZ4UXj-9do7w9X1uKFXAnqfto4TepSNuYU2bA_-tzSLAGBsR-BqvT6w9SjxakeiyQpVmexxnDw5WZwpWenUAcYrfSPEoNU-0hAQwFYgqZwJQMN8ptxkd0170PFauwACOx4Hfr-9FPGy8NCoIO4MfLXzJ3mJ7xqgIZp3NIOGXz-GIAbCf13ii7kSStpYqN3L_zzpvXUAos1FJ9IPXRV84tIZpFVh2lmRh0h8ImK-vI42dwlD_hOIzayL1Xno2R0T-d5AwTSdnep7g-Fwu8-sj4cCRWq3bd61Zs2QOJ8iustH0vSRMYdP5oYQ
#
# You can configure multiple JWKs and use them together with the jwk field.
# If multiple JWKs are configured, kid is required. If the JWT does not include kid, the consistency check on kid fails.
jwks:
- kid: O9fpdhrViq2zaaaBEWZITz 	# If only one JWK is configured, kid is optional. If the JWT includes kid, API Gateway checks the consistency of kid.
  kty: RSA
  e: AQAB
  use: sig
  alg: RS256
  n: qSVxcknOm0uCq5v....
- kid: 10fpdhrViq2zaaaBEWZITz         # If only one JWK is configured, kid is optional. If the JWT includes kid, API Gateway checks the consistency of kid.
  kty: RSA
  e: AQAB
  use: sig
  alg: RS256
  n: qSVxcknOm0uCq5v...                

• JWT認証プラグインは、parameterとparameterLocationの設定に基づいてJWTを取得します。 たとえば、parameterがX-Tokenに設定され、parameterLocationがheaderに設定されている場合、JWTはX-Tokenヘッダーから読み取られます。

• APIで設定されたパラメーターがparameterで指定されたパラメーターと同じ名前の場合は、parameterLocationを指定しないでください。 それ以外の場合、APIが呼び出されるとエラーが報告されます。

• Authorization bearer {token} などのAuthorizationヘッダーでトークンを送信する場合は、parameterをAuthorizationに設定し、parameterLocationをヘッダーに設定して、トークン情報を正しく読み取ることができます。

• preventJtiReplayがtrueに設定されている場合、JWT認証プラグインはクレーム内のjtiを使用してアンチリプレイチェックを実行します。

• bypassEmptyTokenがtrueに設定され、トークンがリクエストに含まれていない場合、API Gatewayはチェックをスキップし、リクエストをバックエンドサービスに直接転送します。

• ignoreExpirationCheckがtrueに設定されている場合、API Gatewayはexp設定の検証をスキップします。 それ以外の場合、API Gatewayはトークンの有効期限を確認します。

• トークン内のクレームをバックエンドサービスに転送するためにAPI Gatewayが必要な場合は、tokenParametersを設定して、次のパラメーターを転送するように設定できます。

  • claimName: トークン内のクレームの名前。 HS256、HS384、またはHS512タイプのキーを設定すると、キー値はbase64urlエンコードされます。 署名が無効な場合は、キーがトークンの生成に使用されたキーと同じ形式であるかどうかを確認します。 kid設定がサポートされています。

  • parameterName: バックエンドサービスに転送されるパラメーターの名前。

  • location: バックエンドサービスに転送されるパラメーターの場所。 有効な値: header、query、path、formData。

    • このパラメーターがpathに設定されている場合、バックエンドパスには /path/{userId} などの同じ名前のパラメーターが含まれている必要があります。

    • このパラメーターがformDataに設定されている場合、バックエンドサービスで受信したリクエストの本文はFormタイプである必要があります。

• jwkフィールドで設定できるキーは1つだけです。 jwksフィールドで複数のキーを設定することもできます。

  • kidを指定せずに1つのキーのみを設定できます。

  • kidを指定して複数のキーを設定できます。 子供はユニークでなければなりません。

3. 検証ルール

• JWT認証プラグインは、parameterとparameterTokenの設定に基づいてトークンを取得します。 トークンがリクエストに含まれていない場合でも、API Gatewayがバックエンドサービスにリクエストを転送する必要がある場合は、bypassEmptyTokenをtrueに設定します。

• 複数のキーを設定する場合は、次の原則に従います。

  • 署名と認証のために、トークンのkidの値と同じIDを持つキーを優先的に選択します。

  • kidを指定しない場合、設定できるキーは1つだけです。 トークンのkidの値と同じIDのキーが存在しない場合は、署名と認証に指定されたkidを持たないキーを使用します。

  • 構成されたすべてのキーにkid設定が指定されていて、リクエスト内のトークンにkidが含まれていないか、kidに一致するキーがない場合、A403JKエラーが報告されます。

• トークンにiat、nbf、およびexpが含まれている場合、JWT認証プラグインは時間形式の有効性を検証します。 時間の単位は秒です。

• デフォルトでは、API Gatewayはexpの設定を検証します。 検証をスキップする場合は、ignoreExpirationCheckをtrueに設定します。

• tokenParametersは、トークンのクレームから必要なパラメーターを抽出するように設定されています。 これらのパラメーターはバックエンドサービスに転送されます。

4. 設定例

4.1. 単一のJWKの設定

---
parameter: X-Token         # The parameter from which the JWT is read. It corresponds to a parameter in an API request.
parameterLocation: header  # The location from which the JWT is read. Valid values: query and header. This parameter is optional if Request Mode for the bound API is set to Map (Filter Out Unknown Parameters) or Map (Pass-through Unknown Parameters). This parameter is required if Request Mode for the bound API is set to Pass-through.
claimParameters:           # The claims to be converted into parameters. API Gateway maps JWT claims to backend parameters.
- claimName: aud           # The name of the JWT claim, which can be public or private.
  parameterName: X-Aud     # The name of the backend parameter, to which the JWT claim is mapped.
  location: header         # The location of the backend parameter, to which the JWT claim is mapped. Valid values: query, header, path, and formData.
- claimName: userId        # The name of the JWT claim, which can be public or private.
  parameterName: userId    # The name of the backend parameter, to which the JWT claim is mapped.
  location: query          # The location of the backend parameter, to which the JWT claim is mapped. Valid values: query, header, path, and formData.
preventJtiReplay: false    # Controls whether to enable the anti-replay check for jti. Default value: false.
#
# Public key in the JWK
jwk:
  kty: RSA
  e: AQAB
  use: sig
  alg: RS256
  n: qSVxcknOm0uCq5vGsOmaorPDzHUubBmZZ4UXj-9do7w9X1uKFXAnqfto4TepSNuYU2bA_-tzSLAGBsR-BqvT6w9SjxakeiyQpVmexxnDw5WZwpWenUAcYrfSPEoNU-0hAQwFYgqZwJQMN8ptxkd0170PFauwACOx4Hfr-9FPGy8NCoIO4MfLXzJ3mJ7xqgIZp3NIOGXz-GIAbCf13ii7kSStpYqN3L_zzpvXUAos1FJ9IPXRV84tIZpFVh2lmRh0h8ImK-vI42dwlD_hOIzayL1Xno2R0T-d5AwTSdnep7g-Fwu8-sj4cCRWq3bd61Zs2QOJ8iustH0vSRMYdP5oYQ
                        

4.2。 複数のJWKの設定

---
parameter: Authorization   # The parameter from which the token is obtained. 
parameterLocation: header  # The location from which the token is obtained.
claimParameters:           # The claims to be converted into parameters. API Gateway maps JWT claims to backend parameters.
- claimName: aud           # The name of the JWT claim, which can be public or private.
  parameterName: X-Aud     # The name of the backend parameter, to which the JWT claim is mapped.
  location: header         # The location of the backend parameter, to which the JWT claim is mapped. Valid values: query, header, path, and formData.
- claimName: userId        # The name of the JWT claim, which can be public or private.
  parameterName: userId    # The name of the backend parameter, to which the JWT claim is mapped.
  location: query          # The location of the backend parameter, to which the JWT claim is mapped. Valid values: query, header, path, and formData.
preventJtiReplay: true     # Controls whether to enable the anti-replay check for jti. Default value: false.
jwks:
- kid: O9fpdhrViq2zaaaBEWZITz 	# kid must be set to different values for different JWKs.
  kty: RSA
  e: AQAB
  use: sig
  alg: RS256
  n: qSVxcknOm0uCq5v....
- kid: 10fpdhrViq2zaaaBEWZITz 	# kid must be set to different values for different JWKs.
  kty: RSA
  e: AQAB
  use: sig
  alg: RS256
  n: qSVxcknOm0uCq5v...

4.3. リクエストのcookieのフィールドからトークンを読み取ります。

---
parameter: cookie         # The parameter from which the JWT is read. It corresponds to a parameter in an API request.
parameterLocation: header  # The location from which the JWT is read. Valid values: query and header. This parameter is optional if Request Mode for the bound API is set to Map (Filter Out Unknown Parameters) or Map (Pass-through Unknown Parameters). This parameter is required if Request Mode for the bound API is set to Pass-through.
parameterSection: token    # For example, the value of the cookie parameter is username=tom ; token=abcsef.
claimParameters:           # The claims to be converted into parameters. API Gateway maps JWT claims to backend parameters.
- claimName: aud           # The name of the JWT claim, which can be public or private.
  parameterName: X-Aud     # The name of the backend parameter, to which the JWT claim is mapped.
  location: header         # The location of the backend parameter, to which the JWT claim is mapped. Valid values: query, header, path, and formData.
- claimName: userId        # The name of the JWT claim, which can be public or private.
  parameterName: userId    # The name of the backend parameter, to which the JWT claim is mapped.
  location: query          # The location of the backend parameter, to which the JWT claim is mapped. Valid values: query, header, path, and formData.
preventJtiReplay: true     # Controls whether to enable the anti-replay check for jti. Default value: false.
jwks:
- kid: O9fpdhrViq2zaaaBEWZITz 	# kid must be set to different values for different JWKs.
  kty: RSA
  e: AQAB
  use: sig
  alg: RS256
  n: qSVxcknOm0uCq5v....
- kid: 10fpdhrViq2zaaaBEWZITz 	# kid must be set to different values for different JWKs.
  kty: RSA
  e: AQAB
  use: sig
  alg: RS256
  n: qSVxcknOm0uCq5v...

一部のwebシナリオでは、セキュリティを確保するために、Cookieパラメーターの指定されたフィールドにトークンを保存することができます。 API GatewayのJWTプラグインを使用すると、Cookieパラメーターのフィールドからトークンを読み取ることができます。 parameterSectionパラメーターを使用して、トークンを保存するフィールドを指定できます。 次の例では、API GatewayはCookieヘッダーからトークンを読み取ることができます。

Cookie: acw_tc=123; token=0QzRCMDBBQUYwRjE1MjYxQzU0QjY4NEM5MTc1NTQ1OUVCOTIzNzA4RDk3MDg5MzlDOTMQTVENDZCRUI1NkYyMEUyO; csrf=073957d8d2823be4f6c0cad23c764558

4.4。 ブラックリストの設定

JWT認証プラグインは、ブラックリストを使用して、ブラックリストに追加されたが公式トークンを取得したユーザーから送信されたリクエストをブロックします。 プラグインはデータセット機能と連携して、トークンから復号化されたクレームパラメーターに基づいてリクエストを拒否します。 さらに、API Gatewayでは、拒否されたリクエストに対するカスタム応答を設定できます。 次のコードは、JWT認証プラグインでブラックリストを設定する方法の例を示しています。 ブロックで始まるパラメータ定義に注意してください。

---
parameter: Authorization   # The parameter from which the token is obtained. 
parameterLocation: header  # The location from which the token is obtained.
claimParameters:           # The claims to be converted into parameters. API Gateway maps JWT claims to backend parameters.
- claimName: aud           # The name of the JWT claim, which can be public or private.
  parameterName: X-Aud     # The name of the backend parameter, to which the JWT claim is mapped.
  location: header         # The location of the backend parameter, to which the JWT claim is mapped. Valid values: query, header, path, and formData.
- claimName: userId        # The name of the JWT claim, which can be public or private.
  parameterName: userId    # The name of the backend parameter, to which the JWT claim is mapped.
  location: query          # The location of the backend parameter, to which the JWT claim is mapped. Valid values: query, header, path, and formData.
blockClaimParameterName: userId  # The location of the backend parameter, to which the JWT claim is mapped. Valid values: query, header, path, and formData.
blockByDataSet: 87 b65008e92541938537b1a4a236eda5  # The location of the backend parameter, to which the JWT claim is mapped. Valid values: query, header, path, and formData.
blockStatusCode: 403       # The status code of the response that is returned to a rejected request.
blockResponseHeaders:      # The header of the response that is returned to a rejected request.
  Content-Type: application/xml
blockResponseBody:         # The body of the response that is returned to a rejected request.
  <Reason>be blocked</Reason>
jwks:
- kid: O9fpdhrViq2zaaaBEWZITz          # kid must be set to different values for different JWKs.
  kty: RSA
  e: AQAB
  use: sig
  alg: RS256
  n: qSVxcknOm0uCq5v....

5. エラーコード

HTTP応答メッセージに、X-Ca-Error-codeヘッダーにErrorCodeで指定されたA403JTやI400JDなどの予期しない応答コードが含まれている場合は、jwt.io Webサイトにアクセスしてトークンの有効性と形式を確認します。

6. 制限事項

• 単一のプラグインのメタデータのサイズは50 KBを超えることはできません。

• 最大16個のパラメーターを転送するように設定できます。 claimNameパラメーターとparameterNameパラメーターはどちらも32文字を超えることはできません。 次の正規表現のみがサポートされています: [A-Za-z0-9-_] 。

• algは、JWKの場合、RS256、RS384、RS512、ES256、ES512、HS256、HS384、またはHS512に設定できます。