1.20. 3scale WebAssembly モジュールの使用

注記

threescale-wasm-auth モジュールは、3scale API Management 2.11 以降と Red Hat OpenShift Service Mesh 2.1.0 以降のインテグレーションで実行されます。

threescale-wasm-auth モジュールは、アプリケーションバイナリーインターフェイス (ABI) と呼ばれるインターフェイスセットを使用する WebAssembly モジュールです。これは、ABI を実装するソフトウェアの一部を駆動する Proxy-WASM 仕様によって定義され、3scale に対する HTTP リクエストを承認できます。

ABI 仕様として、Proxy-WASM は、host という名前のソフトウェアと、モジュールプログラム、または拡張という名前のソフトウェアの間の相互作用を定義します 。ホストは、モジュールが使用するサービスセットを公開してタスクを実行し、この場合はプロキシーリクエストを処理します。

ホスト環境は、ソフトウェアの一部 (この場合は HTTP プロキシー) と対話する WebAssembly 仮想マシンで設定されています。

モジュール自体は、仮想マシンで実行する手順と Proxy-WASM によって指定された ABI を除き、外部環境とは独立して実行されます。これは、ソフトウェアを参照する拡張を提供するのに安全な方法です。拡張は、仮想マシンおよびホストと明確に定義された方法でのみ対話できます。対話により、コンピューティングモデルと、プロキシーが持つ外部への接続が提供されます。

1.20.1. 互換性

threescale-wasm-auth モジュールは、Proxy-WASM ABI 仕様のすべての実装と完全に互換性を持つように設計されています。ただし、この時点で、連携することが完全にテストされているのは Envoy リバースプロキシーだけです。

1.20.2. スタンドアロンモジュールとしての使用

その自己完結型設計により、このモジュールが Service Mesh と 3scale Istio アダプターのデプロイメントとは独立して Proxy-WASM プロキシーと連携するように設定できます。

1.20.3. 前提条件

  • このモジュールは、サポートされているすべての 3scale リリースで動作します。ただし、3scale 2.11 以降が必要な OpenID Connect (OIDC) を使用するようにサービスを設定する場合を除きます。

1.20.4. threescale-wasm-auth モジュールの設定

OpenShift Container Platform のクラスター管理者は、threescale-wasm-auth モジュールを設定し、アプリケーションバイナリーインターフェイス (ABI) を使用して 3scale API Management への HTTP 要求を承認することができます。ABI は、ホストとモジュール間の対話を定義し、ホストサービスを公開し、モジュールを使用してプロキシー要求を処理することができます。

1.20.4.1. WasmPlugin API 拡張機能

Service Mesh は、WasmPlugin と呼ばれるサイドカープロキシーに Proxy-WASM 拡張機能を指定して適用するためのカスタムリソース定義を提供します。Service Mesh は、3scale での HTTP API 管理を必要とするワークロードのセットにこのカスタムリソースを適用します。

詳細は、カスタムリソース定義 を参照してください。

注記

WebAssembly 拡張の設定は、現在手動プロセスです。3scale システムからサービスの設定を取得するサポートは、今後のリリースでご利用いただけます。

前提条件

  • このモジュールを適用する Service Mesh デプロイメントで Kubernetes ワークロードおよび namespace を特定します。
  • 3scale テナントアカウントが必要です。適合するサービスならびに該当するアプリケーションおよびメトリクスが定義された SaaS または オンプレミス型 3scale 2.11 を参照してください。
  • モジュールを info namespace の <product_page> マイクロサービスに適用する場合は、Bookinfo サンプルアプリケーション を参照してください。

    • 以下の例は、threescale-wasm-auth モジュールのカスタムリソースの YAML 形式です。この例では、アップストリームの Maistra バージョンの Service Mesh WasmPlugin API を参照します。モジュールが適用されるアプリケーションのセットを特定する selector とともに threescale-wasm-auth モジュールがデプロイされる namespace を宣言する必要があります。

      apiVersion: extensions.istio.io/v1alpha1
      kind: WasmPlugin
      metadata:
        name: <threescale_wasm_plugin_name>
        namespace: <info> 1
      spec:
        selector: 2
          labels:
            app: <product_page>
        pluginConfig: <yaml_configuration>
        url: oci://registry.redhat.io/3scale-amp2/3scale-auth-wasm-rhel8:0.0.3
        phase: AUTHZ
        priority: 100
      1
      namespace
      2
      selector
  • spec.pluginConfig フィールドはモジュール設定に依存し、直前の例では入力されません。この例では、<yaml_configuration> プレースホルダーの値を使用します。このカスタムリソースの例の形式を使用できます。

    • spec.pluginConfig フィールドはアプリケーションによって異なります。その他のフィールドはすべて、このカスタムリソースの複数のインスタンス間で永続します。以下に例を示します。

      • URL: 新しいバージョンのモジュールがデプロイされる場合にのみ変更されます。
      • phase: このモジュールは、OpenID Connect (OIDC) トークンの検証など、プロキシーがローカルの承認を行った後に呼び出す必要があるため、同じままです。
  • spec.pluginConfig と残りのカスタムリソースにモジュール設定を追加したら、oc apply コマンドでこれを適用します。

    $ oc apply -f threescale-wasm-auth-info.yaml

1.20.5. 3scale 外部 ServiceEntry オブジェクトの適用

threescale-wasm-auth モジュールに 3scale に対するクエストを承認させるには、モジュールは 3scale サービスにアクセスできる必要があります。Red Hat OpenShift Service Mesh 内でこれを行うには、外部の ServiceEntry オブジェクトと対応する DestinationRule オブジェクトを TLS 設定に適用して、HTTPS プロトコルを使用します。

カスタムリソース (CR) は、Service Management API および Account Management API のバックエンドおよびシステムコンポーネントのために、サービスメッシュ内から 3scale Hosted (SaaS) への安全なアクセスのためのサービスエントリーと宛先ルールを設定します。Service Management API は、各リクエストの承認ステータスのクエリーを受信します。Account Management API は、サービスの API 管理設定を提供します。

手順

  1. 以下の外部 ServiceEntry CR および関連する 3scale Hosted バックエンド 用の DestinationRule CR をクラスターに適用します。

    1. ServiceEntry CR を service-entry-threescale-saas-backend.yml というファイルに追加します。

      ServiceEntry CR

      apiVersion: networking.istio.io/v1beta1
      kind: ServiceEntry
      metadata:
        name: service-entry-threescale-saas-backend
      spec:
        hosts:
        - su1.3scale.net
        ports:
        - number: 443
          name: https
          protocol: HTTPS
        location: MESH_EXTERNAL
        resolution: DNS

    2. DestinationRule CR を destination-rule-threescale-saas-backend.yml というファイルに追加します。

      DestinationRule CR

      apiVersion: networking.istio.io/v1beta1
      kind: DestinationRule
      metadata:
        name: destination-rule-threescale-saas-backend
      spec:
        host: su1.3scale.net
        trafficPolicy:
          tls:
            mode: SIMPLE
            sni: su1.3scale.net

    3. 以下のコマンドを実行して、3scale Hosted バックエンドの外部 ServiceEntry CR をクラスターに適用して保存します。

      $ oc apply -f service-entry-threescale-saas-backend.yml
    4. 以下のコマンドを実行して、3scale Hosted バックエンドの外部 DestinationRule CR をクラスターに適用して保存します。

      $ oc apply -f destination-rule-threescale-saas-backend.yml
  2. 以下の外部 ServiceEntry CR および関連する 3scale Hosted システム 用の DestinationRule CR をクラスターに適用します。

    1. ServiceEntry CR を service-entry-threescale-saas-system.yml というファイルに追加します。

      ServiceEntry CR

      apiVersion: networking.istio.io/v1beta1
      kind: ServiceEntry
      metadata:
        name: service-entry-threescale-saas-system
      spec:
        hosts:
        - multitenant.3scale.net
        ports:
        - number: 443
          name: https
          protocol: HTTPS
        location: MESH_EXTERNAL
        resolution: DNS

    2. DestinationRule CR を destination-rule-threescale-saas-system.yml というファイルに追加します。

      DestinationRule CR

      apiVersion: networking.istio.io/v1beta1
      kind: DestinationRule
      metadata:
        name: destination-rule-threescale-saas-system
      spec:
        host: multitenant.3scale.net
        trafficPolicy:
          tls:
            mode: SIMPLE
            sni: multitenant.3scale.net

    3. 以下のコマンドを実行して、3scale Hosted システムの外部 ServiceEntry CR をクラスターに適用して保存します。

      $ oc apply -f service-entry-threescale-saas-system.yml
    4. 以下のコマンドを実行して、3scale Hosted システムの外部 DestinationRule CR をクラスターに適用して保存します。

      $ oc apply -f <destination-rule-threescale-saas-system.yml>

または、メッシュ内の 3scale サービスをデプロイできます。メッシュ内 3scale サービスをデプロイするには、3scale をデプロイしてデプロイにリンクすることにより、CR 内のサービスの場所を変更します。

1.20.6. 3scale WebAssembly モジュール設定

WasmPlugin カスタムリソース仕様は、Proxy-WASM モジュールが読み取る設定を提供します。

仕様はホストに組み込まれ、Proxy-WASM モジュールによって読み取られます。通常、設定は、解析するモジュールの JSON ファイル形式ですが、WasmPlugin リソースは仕様値を YAML として解釈し、モジュールで使用するために JSON に変換できます。

スタンドアロンモードで Proxy-WASM モジュールを使用する場合は、JSON 形式を使用して設定を作成する必要があります。JSON 形式を使用する場合は、host 設定ファイル内の必要な場所で、エスケープと引用を使用できます (例:Envoy)。WasmPlugin リソースで WebAssembly モジュールを使用する場合、設定は YAML 形式になります。この場合は、無効な設定により、JSON 表現に基づいて診断がモジュールによって強制的にサイドカーコンテナーのロギングストリームに表示されます。

重要

EnvoyFilter カスタムリソースは一部の 3scale Istio アダプターまたは Service Mesh リリースで使用できますが、このカスタムリソースはサポートされる API ではありません。EnvoyFilter カスタムリソースの使用は推奨されていません。EnvoyFilter カスタムリソースの代わりに WasmPlugin API を使用します。EnvoyFilter カスタムリソースを使用する必要がある場合は、仕様を JSON 形式で指定する必要があります。

1.20.6.1. 3scale WebAssembly モジュールの設定

3scale の WebAssembly モジュール設定のアーキテクチャーは、3scale アカウントおよび承認サービスや処理するサービスの一覧によって異なります。

前提条件

前提条件は、すべてのケースで最小の必須フィールドのセットです。

  • 3scale アカウントおよび承認サービス:backend-listener URL。
  • 処理するサービス一覧: サービス ID と少なくとも 1 つの認証情報の検索方法、およびその検索場所。
  • userkeyappidappkey、および OpenID Connect (OIDC) パターンを処理する例があります。
  • WebAssembly モジュールは、静的設定で指定した設定を使用します。たとえば、モジュールにマッピングルール設定を追加する場合は、3scale 管理ポータルにこのようなマッピングルールが設定されていない場合でも、常に適用されます。残りの WasmPlugin リソースは spec.pluginConfig YAML エントリーに存在します。

1.20.6.2. 3scale WebAssembly モジュール api オブジェクト

3scale WebAssembly モジュールからの api 最上位文字列は、モジュールが使用する設定のバージョンを定義します。

注記

存在しないバージョンまたはサポート対象外のバージョンの api オブジェクトの場合、レンダリングされた 3scale WebAssembly モジュールは操作不能になります。

api 最上位文字列の例

apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
  name: <threescale_wasm_plugin_name>
  namespace: <info>
spec:
  pluginConfig:
    api: v1
...

api エントリーは、設定の残りの値を定義します。許可される値は v1 のみです。現在の設定との互換性を壊す、または v1 を使用するモジュールが処理できないロジックを必要とする新しい設定には、異なる値が必要になります。

1.20.6.3. 3scale WebAssembly モジュール system オブジェクト

system 最上位オブジェクトは、特定のアカウントの 3scale Account Management API にアクセスする方法を指定します。upstream フィールドは、オブジェクトの最も重要な部分です。system オブジェクトはオプションですが、3scale のsystemコンポーネントへの接続を提供しない場合のオプションである 3scale WebAssembly モジュールに完全な静的設定を提供する場合を除き、推奨されます。

system オブジェクトに加えて静的設定オブジェクトを指定する場合は、静的な設定オブジェクトが優先されます。

apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
  name: <threescale_wasm_plugin_name>
spec:
  pluginConfig:
    system:
      name: <saas_porta>
      upstream: <object>
      token: <my_account_token>
      ttl: 300
  ...

表1.22 system オブジェクトフィールド

名前説明必須

name

3scale サービスの識別子 (現在、参照されていません)。

任意

upstream

問い合わせるネットワークホストの詳細。upstream は、system として知られる 3scale Account Management API ホストを参照します。

はい

token

読み取り権限を持つ 3scale の個人アクセストークン。

はい

ttl

新規の変更を取得する前に、このホストから取得した設定を有効なものと見なす最小時間 (秒数)。デフォルトは 600 秒 (10 分) です。注記: 最大の期間はありませんが、モジュールは通常、この TTL が経過した後に妥当な時間内に設定を取得します。

任意

1.20.6.4. 3scale WebAssembly モジュール upstream オブジェクト

upstream オブジェクトは、プロキシーが呼び出しを実行できる外部ホストを説明しています。

apiVersion: maistra.io/v1
upstream:
  name: outbound|443||multitenant.3scale.net
  url: "https://myaccount-admin.3scale.net/"
  timeout: 5000
...

表1.23 upstream オブジェクトフィールド

名前説明必須

name

name は自由形式の識別子ではありません。これは、プロキシー設定で定義される外部ホストの識別子です。スタンドアロン Envoy 設定の場合は、これは他のプロキシーの upstream とも呼ばれる クラスター 名にマッピングします。注記:Service Mesh および 3scale Istio アダプターコントロールプレーンは、複数のフィールドの区切り文字として垂直バー (|) を使用する形式に従って名前を設定します。この統合の目的上、常に outbound|<port>||<hostname> の形式を使用します。

はい

url

記述されたサービスにアクセスするための完全な URL。スキームによって暗示されていない限り、TCP ポートが含まれている必要があります。

はい

Timeout

応答にかかる時間がこの設定を超えたこのサービスへの接続がエラーとみなされるためのタイムアウト (ミリ秒単位)。デフォルトは 1000 秒です。

任意

1.20.6.5. 3scale WebAssembly モジュール backend オブジェクト

backend 最上位オブジェクトは、HTTP リクエストの承認および報告のために 3scale Service Management API にアクセスする方法を指定します。このサービスは、3scale の バックエンド コンポーネントによって提供されます。

apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
  name: <threescale_wasm_plugin_name>
spec:
  pluginConfig:
    ...
    backend:
      name: backend
      upstream: <object>
    ...

表1.24 backend オブジェクトフィールド

名前説明必須

name

3scale バックエンドの識別子 (現在、参照されていません)。

任意

upstream

問い合わせるネットワークホストの詳細。これは、system として知られる 3scale Account Management API ホストを参照する必要があります。

有効。最も重要な必須フィールドです。

1.20.6.6. 3scale WebAssembly モジュール services オブジェクト

services の最上位オブジェクトは、module のこの特定のインスタンスで処理されるサービス識別子を指定します。

アカウントには複数のサービスがあるため、どのサービスを処理するかを指定する必要があります。残りの設定は、サービスの設定方法に関するものです。

services フィールドは必須です。有用とするサービスを少なくとも 1 つ含める必要がある配列です。

apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
  name: <threescale_wasm_plugin_name>
spec:
  pluginConfig:
    ...
    services:
    - id: "2555417834789"
      token: service_token
      authorities:
        - "*.app"
        - 0.0.0.0
        - "0.0.0.0:8443"
      credentials: <object>
      mapping_rules: <object>
    ...

services 配列の各要素は、3scale サービスを表します。

表1.25 services オブジェクトフィールド

名前説明必須

ID

この 3scale サービスの識別子 (現在、参照されていません)。

はい

token

この token は、System 内のサービスのプロキシー設定にあるか、以下の curl コマンドを使用して System から取得できます。

curl https://<system_host>/admin/api/services/<service_id>/proxy/configs/production/latest.json?access_token=<access_token>" | jq '.proxy_config.content.backend_authentication_value

任意

authorities

文字列の配列。それぞれが一致する URL認証局 を表します。これらの文字列は、アスタリスク (*)、正符号 (+)、および疑問符 (?) マッチャーに対応する glob パターンを受け入れます。

はい

credentials

検索する認証情報の種類と場所を定義するオブジェクト。

はい

mapping_rules

ヒットするマッピングルールおよび 3scale メソッドを表すオブジェクトの配列。

任意

1.20.6.7. 3scale WebAssembly モジュール credentials オブジェクト

credentials オブジェクトは service オブジェクトのコンポーネントです。credentials は、検索する認証情報の種類と、このアクションを実行する手順を指定します。

すべてのフィールドはオプションですが、少なくとも 1 つの user_key または app_id を指定する必要があります。各認証情報を指定する順番は、モジュールによって事前確立されているために無関係です。各認証情報の 1 つのインスタンスのみを指定します。

apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
  name: <threescale_wasm_plugin_name>
spec:
  pluginConfig:
    ...
    services:
    - credentials:
        user_key: <array_of_lookup_queries>
        app_id: <array_of_lookup_queries>
        app_key: <array_of_lookup_queries>
    ...

表1.26 credentials オブジェクトフィールド

名前説明必須

user_key

これは、3scale ユーザーキーを定義する検索クエリーの配列です。ユーザーキーは、一般に API キーと呼ばれます。

任意

app_id

これは、3scale のアプリケーション識別子を定義する検索クエリーの配列です。アプリケーションの識別子は、3scale または Red Hat Single Sign-On (RH-SS0) や OpenID Connect (OIDC) などのアイデンティティープロバイダーを使用して提供されます。成功して 2 つの値に解決するたびに、ここで指定された検索クエリーの解決で、app_idapp_key が設定されます。

任意

app_key

これは、3scale のアプリケーションキーを定義する検索クエリーの配列です。解決される app_id のないアプリケーションキーは無意味なため、app_id が指定されている場合のみこのフィールドを指定します。

任意

1.20.6.8. 3scale WebAssembly モジュール検索クエリー

lookup query オブジェクトは、credentials オブジェクトのフィールドの一部になります。特定の認証情報フィールドが検出され、処理される方法を指定します。評価されると、解決に成功すると、1 つ以上の値が見つかったことを意味します。解決に失敗したことは、値が見つからなかったことを意味します。

lookup queries の配列は、ショートサーキットまたは関係を定義しています。いずれかのクエリーの正常な解決により、残りのクエリーの評価が停止され、値を指定の credential-type に割り当てます。アレイの各クエリーは、互いに独立しています。

lookup query は、1 つのフィールド (ソースオブジェクト) で設定されています。これは、複数のソースタイプの 1 つになります。以下の例を参照してください。

apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
  name: <threescale_wasm_plugin_name>
spec:
  pluginConfig:
    ...
    services:
    - credentials:
        user_key:
          - <source_type>: <object>
          - <source_type>: <object>
          ...
        app_id:
          - <source_type>: <object>
          ...
        app_key:
          - <source_type>: <object>
          ...
    ...

1.20.6.9. 3scale WebAssembly モジュール source オブジェクト

source オブジェクトは、任意の credentials オブジェクトフィールド内のソースの配列の一部として存在します。source-type として参照されるオブジェクトフィールド名は、以下のいずれかになります。

  • header: 検索クエリーは、HTTP リクエストヘッダーを入力として受け取ります。
  • query_string: lookup query は、URL クエリー文字列パラメーターを入力として受け取ります。
  • filter: lookup query は、フィルターメタデータをインプットとして受け取ります。

すべての source-type オブジェクトには、少なくとも以下の 2 つのフィールドがあります。

表1.27 source-type オブジェクトフィールド

名前説明必須

keys

文字列の配列。それぞれが key で、入力データで検索されたエントリーを参照します。

はい

ops

key エントリーの照合を行う operations の配列。配列は、操作が入力を受け取り、次の操作の出力を生成するパイプラインです。出力に失敗した operation は、lookup query を失敗として解決します。操作のパイプラインの順序により、評価の順序が決定されます。

任意

filter フィールド名には、データの検索に使用するメタデータのパスを表示するのに必要な path エントリーがあります。

キーが 入力データと一致する場合は、残りの鍵は評価されず、ソース解決アルゴリズムは、指定した operations (ops) の実行にジャンプします。ops を指定しないと、一致する key の結果値 (ある場合) が返されます。

Operations は、最初のフェーズが key を検索した後に、入力に対する特定の条件および変換を指定する方法を提供します。プロパティーを変換、デコード、および要求する必要があるときに、operations を使用しますが、すべてのニーズに対応する成熟した言語は提供されず、Turing-completeness はありません。

スタックは operations の出力を保存します。評価されると、認証情報が消費する値の数に応じて、スタックの下部に値を割り当てて、lookup query は終了します。

1.20.6.10. 3scale WebAssembly モジュール operations オブジェクト

特定の source type に属する ops 配列の各要素は、値に変換を適用するか、テストを実行する operation オブジェクトです。このようなオブジェクトに使用するフィールド名は operation 自体の名前で、値は operation に対するパラメーターです。これは、フィールドと値のマップ、リスト、または文字列など、構造化オブジェクトになります。

ほとんどの operations は、1 つ以上の入力を処理し、1 つ以上の出力を生成します。入力を使用したり、出力を生成したりする場合、それらは値のスタックで作業します。操作によって消費される各値は、値のスタックからポップアップされ、source マッチと共に初期入力されます。出力される値はスタックにプッシュされます。他の operations は、特定のプロパティーを要求する以外、出力を使用または生成しませんが、値のスタックを検査します。

注記

解決が完了すると、次の手順 (値を app_idapp_key、または user_key に割り当てるなど) でピックアップされる値はスタックの下部の値から取得されます。

operations カテゴリーはいくつかあります。

  • decode: 別の形式を取得するために、入力値をデコードして変換します。
  • string: 文字列値を入力として取り、変換を実行し、確認します。
  • stack: 入力の値のセットを取得し、複数のスタック変換とスタック内の特定の位置の選択を実行します。
  • check: 影響を及ぼさない方法で、操作セットに関するプロパティーを要求します。
  • control: 評価フローを変更できる操作を実施します。
  • format: 入力値の形式固有の構造を解析し、その値を検索します。

すべての操作は、name 識別子で文字列として指定されます。

関連情報

1.20.6.11. 3scale WebAssembly モジュール mapping_rules オブジェクト

mapping_rules オブジェクトは service オブジェクトの一部です。これは、REST パスパターンのセットならびに関連する 3scale メトリクスおよびパターンが一致する時に使用するカウント増分を指定します。

system 最上位オブジェクトに動的設定が提供されていない場合は、値が必要です。system 最上位エントリーに加えてオブジェクトが提供されると、mapping_rules オブジェクトが最初に評価されます。

mapping_rules は配列オブジェクトです。そのアレイの各要素は mapping_rule オブジェクトです。受信したリクエストの評価されたマッチするマッピングルールにより、承認およびAPIManager へのレポート用の 3scale methods のセットが提供されます。複数のマッチングルールが同じ methods を参照する場合は、3scale への呼び出し時に deltas の合算があります。たとえば、2 つのルールが、1 と 3 の deltasHits メソッドを 2 回増やすと、3scale にレポートする Hits の単一のメソッドエントリーの delta は 4 になります。

1.20.6.12. 3scale WebAssembly モジュール mapping_rule オブジェクト

mapping_rule オブジェクトは mapping_rules オブジェクトの配列の一部です。

mapping_rule オブジェクトフィールドは、以下の情報を指定します。

  • 照合する HTTP 要求メソッド
  • パスに一致するパターン。
  • 報告する量と共にレポートする 3scale メソッド。フィールドを指定する順番により、評価順序が決定されます。

表1.28 mapping_rule オブジェクトフィールド

名前説明必須

メソッド

HTTP リクエストメソッド (動詞) を表す文字列を指定します。許可される値は、許可される HTTP メソッド名の 1 つと一致し、大文字と小文字を区別しません。すべてのマッチのすべてのメソッドの特殊な値。

はい

pattern

HTTP リクエストの URI パスコンポーネントに一致するパターン。このパターンは、3scale で説明されている構文に従います。{this} などの中括弧間の文字のシーケンスを使用するワイルドカード (アスタリスク (*) 文字の使用) が許可されます。

はい

usages

usage オブジェクトの一覧。ルールがマッチすると、deltas を持つすべてのメソッドが、承認およびレポートのために 3scale に送信されるメソッドの一覧に追加されます。

以下の必須フィールドに usages オブジェクトを埋め込みます。

  • name: レポートする method のシステム名。
  • delta: その method の増分。

はい

last

このルールが正常にマッチした場合に、それ以外のマッピングルールの評価を停止する必要があるかどうか。

任意のブール値。デフォルトは false です。

以下の例は、3scale のメソッド間の既存の階層とは独立しています。つまり、3scale 側で実行されたすべての内容はこれには影響しません。たとえば、Hits メトリクスは、それらすべての親となる可能性があるため、承認されたリクエストで報告されたすべてのメソッドの合計により 4 ヒットを保管し、3scale Authrep API エンドポイントを呼び出します。

以下の例では、すべてのルールに一致する、パス /products/1/sold への GET リクエストを使用します。

mapping_rules GET リクエストの例

apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
  name: <threescale_wasm_plugin_name>
spec:
  pluginConfig:
    ...
    mapping_rules:
      - method: GET
        pattern: /
        usages:
          - name: hits
            delta: 1
      - method: GET
        pattern: /products/
        usages:
          - name: products
            delta: 1
      - method: ANY
        pattern: /products/{id}/sold
        usages:
          - name: sales
            delta: 1
          - name: products
            delta: 1
    ...

すべての usages は、モジュールが使用状況データを使用して 3scale に実施するリクエストに追加されます。

  • Hits: 1
  • products: 2
  • sales: 1

1.20.7. 認証情報ユースケースの 3scale WebAssembly モジュールの例

ほとんどの時間を費やして、設定手順を適用してサービスへのリクエストの認証情報を取得します。

以下は credentials の例です。これは、特定のユースケースに合わせて変更できます。

複数のソースオブジェクトと独自の lookup queries を指定する場合、これらはすべて組み合わせることができますが、いずれか 1 つが正しく解決されるまで、それらは順番に評価されます。

1.20.7.1. クエリー文字列パラメーターの API キー (user_key)

以下の例では、クエリー文字列パラメーターまたは同じ名前のヘッダーで user_key を検索します。

credentials:
  user_key:
    - query_string:
        keys:
          - user_key
    - header:
        keys:
          - user_key

1.20.7.2. アプリケーション ID およびキー

以下の例では、クエリーまたはヘッダーの app_key および app_id 認証情報を検索します。

credentials:
  app_id:
    - header:
        keys:
          - app_id
    - query_string:
        keys:
          - app_id
  app_key:
    - header:
        keys:
          - app_key
    - query_string:
        keys:
          - app_key

1.20.7.3. 認証ヘッダー

リクエストには、authorization ヘッダーに app_id および app_key が含まれます。最後に出力される値が 1 つまたは 2 つある場合は、app_key を割り当てることができます。

ここでの解決は、最後に出力された 1 つまたは 2 つの出力がある場合は app_key を割り当てます。

authorization ヘッダーは承認の種類で値を指定し、その値は Base64 としてエンコードされます。つまり、値を空白文字で分割し、2 番目の出力を取得して、コロン (:) をセパレーターとして使用して再度分割できます。たとえば、app_id:app_key という形式を使用する場合、ヘッダーは以下の credential の例のようになります。

aladdin:opensesame:  Authorization: Basic YWxhZGRpbjpvcGVuc2VzYW1l

以下の例のように、小文字のヘッダーフィールド名を使用する必要があります。

credentials:
  app_id:
    - header:
        keys:
          - authorization
        ops:
          - split:
              separator: " "
              max: 2
          - length:
              min: 2
          - drop:
              head: 1
          - base64_urlsafe
          - split:
              max: 2
  app_key:
    - header:
        keys:
          - app_key

前述のユースケースの例は、authorization のヘッダーを確認します。

  1. これは文字列の値を取り、スペースで分割し、credential-type および credential 自体の少なくとも 2 つの値を生成することを確認してから、credential-type をドロップします。
  2. 次に、必要なデータが含まれる 2 番目の値をデコードし、最初の app_id の後にもしあれば app_key が含まれる操作スタックとなるように、コロン (:) 文字を使用して分割します。

    1. app_key が認証ヘッダーに存在しない場合は、特定のソースがチェックされます (この場合は、キー app_key のヘッダーなど)。
  3. credentials に追加の条件を追加するには、Basic 認証を許可します。ここで、app_idaladdin もしくは admin、または 長さが 8 文字以上の任意の app_id になります。
  4. app_key には値が含まれ、以下の例のように最小で 64 文字を指定する必要があります。

    credentials:
      app_id:
        - header:
            keys:
              - authorization
            ops:
              - split:
                  separator: " "
                  max: 2
              - length:
                  min: 2
              - reverse
              - glob:
                - Basic
              - drop:
                  tail: 1
              - base64_urlsafe
              - split:
                  max: 2
              - test:
                  if:
                    length:
                      min: 2
                  then:
                    - strlen:
                        max: 63
                    - or:
                        - strlen:
                            min: 1
                        - drop:
                            tail: 1
              - assert:
                - and:
                  - reverse
                  - or:
                    - strlen:
                        min: 8
                    - glob:
                      - aladdin
                      - admin
  5. authorization ヘッダーの値を選択したら、タイプが上部に配置されるようにスタックを逆にして Basic credential-type を取得します。
  6. glob マッチを実行します。検証し、認証情報がデコードされ、分割されると、スタックの下部に app_id を取得し、上部に app_key を取得する可能性があります。
  7. test: を実行します。スタックに 2 つの値がある場合は、app_key が取得されたことになります。

    1. app_id および app_key を含め、文字列の長さが 1 から 63 文字になるようにします。キーの長さがゼロの場合は破棄し、キーが存在しないものとして続行します。app_id のみがあり、app_key がない場合、不明なブランチは、テストに成功し、評価が続行されます。

最後の操作は assert で、スタックに副作用がないことを示します。その後、スタックを変更できます。

  1. app_id が最上部になるように、スタックを逆にします。

    1. app_key が存在するかどうかで、スタックを逆にすると、app_id が上部になります。
  2. and を使用して、テスト間でスタックの内容を保持します。

    次に、以下のいずれかの方法を使用します。

    • app_id に 8 文字以上の文字列が設定されていることを確認してください。
    • app_idaladdin または admin と一致していることを確認します。

1.20.7.4. OpenID Connect (OIDC) のユースケース

Service Mesh および 3scale Istio アダプターの場合は、以下の例のように RequestAuthentication をデプロイし、独自のワークロードデータおよび jwtRules を入力する必要があります。

apiVersion: security.istio.io/v1beta1
kind: RequestAuthentication
metadata:
  name: jwt-example
  namespace: info
spec:
  selector:
    matchLabels:
      app: productpage
  jwtRules:
  - issuer: >-
      http://keycloak-keycloak.34.242.107.254.nip.io/auth/realms/3scale-keycloak
    jwksUri: >-
      http://keycloak-keycloak.34.242.107.254.nip.io/auth/realms/3scale-keycloak/protocol/openid-connect/certs

RequestAuthentication を適用するとき、JWT トークンを検証するためにネイティブプラグインEnvoy を設定します。プロキシーは、モジュールを実行する前にすべてを検証します。したがって、失敗したリクエストが 3scale WebAssembly モジュールに実行されません。

JWT トークンが検証されると、プロキシーはそのコンテンツを内部メタデータオブジェクトに格納します。エントリーのキーは、プラグインの特定の設定に依存します。このユースケースでは、不明なキー名が含まれる単一のエントリーを持つ構造化オブジェクトを検索できます。

OIDC の 3scale app_id は、OAuth client_id と一致します。これは JWT トークンの azp フィールドまたは aud フィールドにあります。

Envoy のネイティブ JWT 認証フィルターから app_id フィールドを取得するには、以下の例を参照してください。

credentials:
  app_id:
    - filter:
        path:
          - envoy.filters.http.jwt_authn
          - "0"
        keys:
          - azp
          - aud
        ops:
          - take:
              head: 1

この例では、モジュールに対し、filter ソースタイプを使用して Envoy 固有の JWT 認証ネイティブプラグインからオブジェクトのフィルターメタデータを検索するよう指示します。このプラグインには、1 つのエントリーと事前に設定された名前を持つ構造化オブジェクトの一部として JWT トークンが含まれます。0 を使用して、単一のエントリーのみにアクセスするように指定します。

結果の値は、以下の 2 つのフィールドを解決する構造です。

  • azp: app_id が見つけられる値。
  • aud: この情報も見つけられる値。

この操作により、割り当て用に 1 つの値のみが保持されます。

1.20.7.5. ヘッダーからの JWT トークンの取得

一部のセットアップには、JWT トークンの検証プロセスがあり、検証されたトークンが JSON 形式のヘッダーを介してこのモジュールに到達する場合があります。

app_id を取得するには、以下の例を参照してください。

credentials:
  app_id:
    - header:
        keys:
          - x-jwt-payload
        ops:
          - base64_urlsafe
          - json:
            - keys:
              - azp
              - aud
          - take:
              head: 1

1.20.8. 3scale WebAssembly モジュールの機能する最低限の設定

以下は、3scale WebAssembly モジュールの機能する最低限の設定の例です。これをコピーアンドペーストし、これを独自の設定で機能するように編集できます。

apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
  name: <threescale_wasm_plugin_name>
spec:
  url: oci://registry.redhat.io/3scale-amp2/3scale-auth-wasm-rhel8:0.0.3
  imagePullSecret: <optional_pull_secret_resource>
  phase: AUTHZ
  priority: 100
  selector:
    labels:
      app: <product_page>
  pluginConfig:
    api: v1
    system:
      name: <system_name>
      upstream:
        name: outbound|443||multitenant.3scale.net
        url: https://istiodevel-admin.3scale.net/
        timeout: 5000
      token: <token>
    backend:
      name: <backend_name>
      upstream:
        name: outbound|443||su1.3scale.net
        url: https://su1.3scale.net/
        timeout: 5000
      extensions:
      - no_body
    services:
    - id: '2555417834780'
      authorities:
      - "*"
      credentials:
        user_key:
          - query_string:
              keys:
                - <user_key>
          - header:
              keys:
                - <user_key>
        app_id:
          - query_string:
              keys:
                - <app_id>
          - header:
              keys:
                - <app_id>
        app_key:
          - query_string:
              keys:
                - <app_key>
          - header:
              keys:
                - <app_key>