Red Hat Summit Red Hat Summitサポートコンソール開発者トライアルの開始お問い合わせ

第4章 APIcast ポリシー

APIcast ポリシーとは、APIcast の動作を変更する機能の単位です。ポリシーを有効、無効、および設定して、APIcast 動作の変更を制御することができます。ポリシーを使用して、デフォルトの APIcast デプロイメントでは利用することのできない機能を追加します。自分専用のポリシーを作成することや、Red Hat 3scale の提供する 標準ポリシー を使用することができます。

以下のトピックでは、標準 APIcast ポリシー、専用のカスタム APIcast ポリシーの作成、およびポリシーチェーンの作成について説明します。

ポリシーチェーンを使用して、サービスに対するポリシーを制御します。ポリシーチェーンの機能を以下に示します。

  • APIcast が使用するポリシーを指定する
  • 3scale が使用するポリシーの設定情報を提供する
  • 3scale がポリシーを読み込む順番を指定する
注記

Red Hat 3scale でカスタムポリシーを追加することは可能ですが、そのカスタムポリシーはサポートの対象ではありません。

カスタムポリシーを使用して APIIcast の動作を変更するには、以下の操作が必要です。

  • カスタムポリシーを APIcast に追加する
  • APIcast ポリシーを設定するポリシーチェーンを定義する
  • ポリシーチェーンを APIcast に追加する

4.1. APIcast 標準ポリシー
リンクのコピー

3scale では、以下の標準ポリシーが利用可能です。

3scale API Management で標準ポリシーを 有効化および設定 することができます。

4.1.1. 3scale Auth Caching ポリシー
リンクのコピー

3scale Auth Caching ポリシーは、APIcast に送信された認証呼び出しをキャシュします。動作モードを選択して、キャッシュ操作を設定することができます。

3scale Auth Caching では、以下のモードを使用することができます。

1.strict: 承認された呼び出しだけをキャッシュします。

strict モードでは、承認された呼び出しだけがキャッシュされます。ポリシーを strict モードで実行中に呼び出しが失敗または拒否されると、ポリシーはキャッシュエントリーを無効にします。バックエンドにアクセスできなくなると、キャッシュステータスにかかわらず、キャッシュされたすべての呼び出しが拒否されます。

2.resilient: バックエンドの機能が停止している場合には、最後のリクエストに基づいて承認します。

resilient モードでは、承認された呼び出しおよび拒否された呼び出しの両方がキャッシュされます。ポリシーを resilient モードで実行中は、呼び出しに失敗しても既存のキャッシュエントリーは無効になりません。バックエンドにアクセスできなくなると、キャッシュにヒットする呼び出しは、キャッシュステータスに応じて承認/拒否の状態を維持します。

3.allow: バックエンドの機能が停止している場合には、過去に拒否されていない限りすべてを許可します。

allow モードでは、承認された呼び出しおよび拒否された呼び出しの両方がキャッシュされます。ポリシーを allow モードで実行中は、キャッシュされた呼び出しはキャッシュステータスに応じて拒否/許可の状態を維持します。ただし、新規の呼び出しは承認された呼び出しとしてキャッシュされます。

重要

allow モードで運用した場合には、セキュリティーの低下が懸念されます。これらの懸念に念頭に置き、注意した上で allow モードを使用してください。

4.none: キャッシュを無効にします。

none モードでは、キャッシュが無効になります。ポリシーを有効にしたままキャッシュの使用を止める場合に、このモードが役立ちます。

設定プロパティー

Expand
プロパティー説明値必須/任意

caching_type

caching_type プロパティーにより、キャッシュの動作モードを定義することができます。

データタイプ: 列挙文字列 [resilient, strict, allow, none]

必須

ポリシーオブジェクトの例 

{
  "name": "caching",
  "version": "builtin",
  "configuration": {
    "caching_type": "allow"
  }
}
Copy to Clipboard Toggle word wrap

ポリシーの設定方法に関する情報は、本書の 3scale でのポリシーチェーンの作成 セクションを参照してください。

4.1.2. 3scale Batcher ポリシー
リンクのコピー

標準の APIcast 承認メカニズムでは、APIcast が API リクエストを受け取るたびに、3scale バックエンド (Service Management API) に対して 1 回呼び出しが行われます。3scale Batcher ポリシーは、この標準メカニズムの代替手段を提供します。

3scale Batcher ポリシーを使用すると、3scale バックエンドへのリクエスト数が大幅に削減され、レイテンシーが減少しスループットが向上します。そのために、このポリシーは承認ステータスをキャッシュし、使用状況レポートをバッチ処理します。

3scale Batcher ポリシーが有効な場合には、APIcast は以下のフローを使用して承認を行います。

  1. それぞれのリクエストにおいて、ポリシーはクレデンシャルがキャッシュされているかどうかを確認します。

    • クレデンシャルがキャッシュされている場合には、ポリシーは 3scale バックエンドに呼び出しを行う代わりに、キャッシュされた承認ステータスを使用します。
    • クレデンシャルがキャッシュされていない場合には、ポリシーはバックエンドに呼び出しを行い、残存期間 (TTL) を設定して承認ステータスをキャッシュします。
  2. リクエストに対応する使用状況を直ちに 3scale バックエンドに報告する代わりに、ポリシーは使用状況のカウンターを累積して、バックエンドにバッチで報告します。累積した使用状況のカウンターは、独立したスレッドにより 1 回の呼び出しで 3scale バックエンドに報告されます (報告の頻度は設定が可能です)。

3scale Batcher ポリシーではスループットが向上しますが、精度は低下します。使用上限および現在の使用状況は 3scale に保存され、APIcast は 3scale バックエンドに呼び出しを行う時にのみ正しい承認ステータスを取得することができます。3scale Batcher ポリシーが有効な場合には、APIcast が 3scale に呼び出しを送信しない期間があります。この期間中、呼び出しを行うアプリケーションが定義された限度を超える可能性があります。

流量制御の精度よりもスループットが重要な場合には、高負荷の API に対してこのポリシーを使用します。報告頻度および承認の TTL が流量制御の期間よりはるかに短い場合には、3scale Batcher ポリシーにより優れた精度が得られます。たとえば、流量制御が 1 日あたりで、報告頻度および承認の TTL が数分に設定されている場合などです。

3scale Batcher ポリシーでは、以下の設定設定がサポートされます。

  • auths_ttl: 承認キャッシュの有効期限が切れる TTL を秒単位で設定します。

    現在の呼び出しの承認がキャッシュされている場合には、APIcast はキャッシュされた値を使用します。auths_ttl パラメーターで設定した時間が経過すると、APIcast はキャッシュを削除し、3scale バックエンドに呼び出しを行い承認のステータスを取得します。

  • batch_report_seconds: APIcast が 3scale バックエンドにバッチレポートを送信する頻度を設定します。デフォルト値は 10 秒です。
重要

このポリシーを使用するには、ポリシーチェーンで 3scale APIcast および 3scale Batcher ポリシーの両方を有効にします。

4.1.3. Anonymous Access ポリシー
リンクのコピー

Anonymous Access ポリシーでは、認証をせずにサービスが公開されます。このポリシーは、認証パラメーターを送信するように変更することのできないレガシーアプリケーション等の場合に有用です。Anonymous ポリシーは、API キーおよびアプリケーション ID/アプリケーションキーによる認証オプションを使用するサービスしかサポートしません。クレデンシャルをまったく持たない API リクエストに対してこのポリシーを有効にした場合には、APIcast はポリシーで設定されたデフォルトのクレデンシャルを使用して呼び出しを承認します。API の呼び出しが承認されるためには、クレデンシャルが設定されたアプリケーションが存在しアクティブでなければなりません。

アプリケーションプランを使用して、デフォルトのクレデンシャルに使用されるアプリケーションに流量制御を設定することができます。

注記

APIcast ポリシーおよび Anonymous Access ポリシーをポリシーチェーンで併用する場合には、APIcast ポリシーの前に Anonymous Access ポリシーを設定する必要があります。

ポリシーに必要な設定プロパティーを以下に示します。

  • auth_type: 以下に示す選択肢のいずれかの値を選択し、プロパティーが API に設定された認証オプションに対応している状態にします。

    • app_id_and_app_key: アプリケーション ID/アプリケーションキーによる認証オプション用
    • user_key: API キーによる認証オプション用
  • app_id (app_id_and_app_key 認証タイプにのみ有効): API の呼び出しにクレデンシャルが提供されていない場合に、承認に使用するアプリケーションのアプリケーション ID。
  • app_key (app_id_and_app_key 認証タイプにのみ有効): API の呼び出しにクレデンシャルが提供されていない場合に、承認に使用するアプリケーションのアプリケーションキー。
  • user_key (user_key 認証タイプにのみ有効): API の呼び出しにクレデンシャルが提供されていない場合に、承認に使用するアプリケーションの API キー。

図4.1 Anonymous Access ポリシー

Anonymous Access Policy
View larger image
Anonymous Access Policy

4.1.4. CORS Request Handling ポリシー
リンクのコピー

Cross Origin Resource Sharing (CORS) Request Handling ポリシーを使用すると、以下の項目を指定することができるので CORS の動作の制御が可能です。

  • 許可されるヘッダー
  • 許可されるメソッド
  • 許可されるクレデンシャル
  • 許可されるオリジンヘッダー

CORS Request Handling ポリシーにより、指定されていない CORS リクエストはすべてブロックされます。

注記

APIcast ポリシーおよび CORS Request Handling ポリシーをポリシーチェーンで併用する場合には、APIcast ポリシーの前に CORS Request Handling ポリシーを設定する必要があります。

設定プロパティー

Expand
プロパティー説明値必須/任意

allow_headers

allow_headers プロパティーでは、APIcast が許可する CORS ヘッダーを配列として指定することができます。

データタイプ: 文字列の配列 (CORS ヘッダーでなければなりません)

任意

allow_methods

allow_methods プロパティーでは、APIcast が許可する CORS メソッドを配列として指定することができます。

データタイプ: 列挙文字列の配列 [GET, HEAD, POST, PUT, DELETE, PATCH, OPTIONS, TRACE, CONNECT]

任意

allow_origin

allow_origin プロパティーでは、APIcast が許可するオリジンのドメインを指定することができます。

データタイプ: 文字列

任意

allow_credentials

allow_credentials プロパティーでは、APIcast がクレデンシャルの設定された CORS リクエストを許可するかどうかを指定することができます。

データタイプ: ブール値

任意

ポリシーオブジェクトの例 

{
  "name": "cors",
  "version": "builtin",
  "configuration": {
    "allow_headers": [
      "App-Id", "App-Key",
      "Content-Type", "Accept"
    ],
    "allow_credentials": true,
    "allow_methods": [
      "GET", "POST"
    ],
    "allow_origin": "https://example.com"
  }
}
Copy to Clipboard Toggle word wrap

ポリシーの設定方法に関する情報は、本書の 3scale でのポリシーチェーンの作成 セクションを参照してください。

4.1.5. Echo ポリシー
リンクのコピー

Echo ポリシーは、受信したリクエストを出力してクライアントに返します。また、オプションで任意の HTTP ステータスコードを返します。

設定プロパティー

Expand
プロパティー説明値必須/任意

status

Echo ポリシーがクライアントに返す HTTP ステータスコード

データタイプ: 整数

いいえ

exit

Echo ポリシーが使用する終了モードを指定します。request 終了モードは、受信したリクエストの処理を停止します。set 終了モードは書き換えフェーズを省略します。

データタイプ: 列挙文字列 [request, set]

必須

ポリシーオブジェクトの例 

{
  "name": "echo",
  "version": "builtin",
  "configuration": {
    "status": 404,
    "exit": "request"
  }
}
Copy to Clipboard Toggle word wrap

ポリシーの設定方法に関する情報は、本書の 3scale でのポリシーチェーンの作成 セクションを参照してください。

4.1.6. Edge Limiting ポリシー
リンクのコピー

Edge Limiting ポリシーの目的は、バックエンド API に送信されるトラフィックに対する柔軟な流量制御を提供することで、このポリシーをデフォルトの 3scale 承認メカニズムと共に使用することができます。このポリシーでサポートされるユースケースの例を以下に示します。

  • エンドユーザーの流量制御: リクエストの認証ヘッダーで渡される JWT トークンの sub(subject) クレームの値による流量制御 ({{ jwt.sub }} として設定します)。
  • 1 秒あたりのリクエスト数 (RPS) 流量制御
  • サービスごとのグローバル流量制御: アプリケーションごとではなく、サービスごとに流量制御を適用します。
  • 同時接続上限: 許容される同時接続の数を設定します。

4.1.6.1. 制限のタイプ
リンクのコピー

このポリシーでは、lua-resty-limit-traffic ライブラリーにより提供される以下の制限タイプがサポートされます。

  • leaky_bucket_limiters: 平均リクエスト数および最大バーストサイズをベースにした leaky_bucket アルゴリズムに基づきます。
  • fixed_window_limiters: 特定の期間 (最後の X 秒) に基づきます。
  • connection_limiters: 同時接続の数に基づきます。

すべての制限をサービスごとまたはグローバルに適用することができます。

4.1.6.2. 制限の定義
リンクのコピー

リミッターはキーを持ち、このキーで制限を定義するのに使用するエンティティーをエンコードします (IP、サービス、エンドポイント、ID、特定ヘッダーの値など)。キーは、リミッターの key パラメーターで指定します。

key は以下のプロパティーで定義されるオブジェクトです。

  • name: キーの名前です。スコープ内で一意でなければなりません。

  • scope: キーのスコープを定義します。サポートされるスコープは以下のとおりです。

    • service: 1 つのサービスに影響を及ぼすサービスごとのスコープ
    • global: すべてのサービスに影響を及ぼすグローバルスコープ

  • name_type:name の値がどのように評価されるかを定義します。

    • plain: プレーンテキストとして評価される。
    • liquid: Liquid として評価される。

それぞれの制限には、そのタイプに応じたパラメーターもあります。

  • leaky_bucket_limiters: rate および burst

    • rate: 遅延を生じることなく実行できる 1 秒あたりのリクエスト数を定義します。
    • burst: 許容レートを超えることのできる 1 秒あたりのリクエスト数を定義します。許容レート (rate で指定される) を超えるリクエストには、人為的な遅延が適用されます。1 秒あたりのリクエスト数が burst で定義されるレートを超えると、リクエストは拒否されます。
  • fixed_window_limiters: count、window。count は、window で定義される秒数あたりに実行できるリクエスト数を定義します。

  • connection_limiters: conn、burst、および delay

    • conn: 許容される同時接続の最大数を定義します。burst で定義される 1 秒あたりの接続数までこの値を超えることができます。
    • delay: 制限を超える接続を遅延させる秒数です。

例

  1. service_A に対するリクエストを毎分 10 回許可します。 

    {
  "key": { "name": "service_A" },
  "count": 10,
  "window": 60
}
    Copy to Clipboard Toggle word wrap

  2. burst および delay をそれぞれ 10 および 1 に設定して、100 の接続を許可します。 

    {
  "key": { "name": "service_A" },
  "conn": 100,
  "burst": 10,
  "delay": 1
}
    Copy to Clipboard Toggle word wrap

サービスごとにさまざまな制限を定義することができます。複数の制限を定義した場合には、少なくとも 1 つの制限に達すると、リクエストは拒否または遅延されます。

4.1.6.3. Liquid テンプレート
リンクのコピー

Edge Limiting ポリシーではキーに Liquid 変数がサポートされるので、動的なキーに制限を指定することができます。そのためには、キーの name_type パラメーターを liquid に設定する必要があります。これにより、name パラメーターに Liquid パラメーターを使用することができます。例: クライアント IP アドレスの場合は {{ remote_addr }}、JWT トークンの sub クレームの場合は {{ jwt.sub }}。

以下に例を示します。 

{
  "key": { "name": "{{ jwt.sub }}", "name_type": "liquid" },
  "count": 10,
  "window": 60
}
Copy to Clipboard Toggle word wrap

Liquid のサポートに関する詳細な情報は、「ポリシーでの変数およびフィルターの使用」を参照してください。

4.1.6.4. 条件の適用
リンクのコピー

条件は、API ゲートウェイがリミッターをいつ適用するかを定義します。各リミッターの condition プロパティーで少なくとも 1 つの操作を指定する必要があります。

以下のプロパティーで condition を定義します。

  • combine_op。演算のリストに適用されるブール演算子です。or および and の 2 つの値がサポートされます。

  • operations。評価する必要がある条件のリストです。各演算は、以下のプロパティーを持つオブジェクトにより表されます。

    • left: 演算の左側部分
    • left_type: left プロパティーがどのように評価されるか (plain または liquid)。
    • right: 演算の右側部分
    • right_type: right プロパティーがどのように評価されるか (plain または liquid)。
    • op: 左右の部分の間に適用される演算子。== (等しい) および != (等しくない) の 2 つの値がサポートされます。

以下に例を示します。 

"condition": {
  "combine_op": "and",
  "operations": [
    {
      "op": "==",
      "right": "GET",
      "left_type": "liquid",
      "left": "{{ http_method }}",
      "right_type": "plain"
    }
  ]
}
Copy to Clipboard Toggle word wrap

4.1.6.5. ストアの設定
リンクのコピー

デフォルトでは、Edge Limiting ポリシーは流量制御カウンターに OpenResty 共有ディクショナリーを使用します。ただし、共有ディクショナリーの代わりに外部の Redis サーバーを使用することができます。この設定は、複数の APIcast インスタンスが使用されている場合に役立ちます。Redis サーバーは、redis_url パラメーターを使用して設定することができます。

4.1.6.6. エラー処理
リンクのコピー

リミッターでは、エラーの処理方法を設定するために以下のパラメーターがサポートされます。

  • limits_exceeded_error: 設定した上限を超えた際にクライアントに返されるエラーステータスコードおよびメッセージを設定することができます。以下のパラメーターを設定する必要があります。

    • status_code: 上限を超えた際のリクエストのステータスコード。デフォルトは 429 です。

    • error_handling: 以下のオプションを使用して、エラーの処理方法を指定します。

      • exit: リクエストの処理を中止し、エラーメッセージを返します。
      • log: リクエストの処理を完了し、出力ログを返します。

  • configuration_error: 設定が正しくない場合にクライアントに返されるエラーステータスコードおよびメッセージを設定することができます。以下のパラメーターを設定する必要があります。

    • status_code: 設定に問題がある場合のステータスコード。デフォルトは 500 です。

    • error_handling: 以下のオプションを使用して、エラーの処理方法を指定します。

      • exit: リクエストの処理を中止し、エラーメッセージを返します。
      • log: リクエストの処理を完了し、出力ログを返します。

4.1.7. Header Modification ポリシー
リンクのコピー

Header Modification ポリシーを使用すると、受信したリクエストまたはレスポンスに関して、既存のヘッダーを変更する、補足のヘッダーを定義して追加する、またはヘッダーを削除することができます。レスポンスヘッダーおよびリクエストヘッダーの両方を変更することができます。

Header Modification ポリシーでは、以下の設定パラメーターがサポートされます。

  • request: リクエストヘッダーに適用する操作のリスト
  • response: レスポンスヘッダーに適用する操作のリスト

それぞれの操作は、以下のパラメーターで設定されます。

  • op: 適用する操作を指定します。add 操作は既存のヘッダーに値を追加します。set 操作はヘッダーおよび値を作成し、既存のヘッダーの値が既に存在する場合はその値を上書きします。push 操作はヘッダーおよび値を作成しますが、既存のヘッダーの値が既に存在していてもその値を上書きしません。その代わりに、push は既存のヘッダーに値を追加します。delete 操作はヘッダーを削除します。
  • header: 作成または変更するヘッダーを指定します。ヘッダー名には任意の文字列を使用することができます (例: Custom-Header)。
  • value_type: ヘッダーの値がどのように評価されるかを定義します。プレーンテキストの場合の plain または Liquid テンプレートとして評価する場合の liquid いずれかに設定します。詳細は、「ポリシーでの変数およびフィルターの使用」 を参照してください。
  • value: ヘッダーに使用される値を指定します。値のタイプが liquid の場合には、値は {{ variable_from_context }} の形式にする必要があります。削除する場合には不要です。

ポリシーオブジェクトの例 

{
  "name": "headers",
  "version": "builtin",
  "configuration": {
    "response": [
      {
        "op": "add",
        "header": "Custom-Header",
        "value_type": "plain",
        "value": "any-value"
      }
    ],
    "request": [
      {
        "op": "set",
        "header": "Authorization",
        "value_type": "plain",
        "value": "Basic dXNlcm5hbWU6cGFzc3dvcmQ="
      },
      {
        "op": "set",
        "header": "Service-ID",
        "value_type": "liquid",
        "value": "{{service.id}}"
      }
    ]
  }
}
Copy to Clipboard Toggle word wrap

ポリシーの設定方法に関する情報は、本書の 3scale でのポリシーチェーンの作成 セクションを参照してください。

4.1.8. IP Check ポリシー
リンクのコピー

IP Check ポリシーは、IP のリストに基づいてリクエストを拒否または許可するために使用します。

設定プロパティー

Expand
プロパティー説明データタイプ必須/任意

check_type

check_type プロパティーには、whitelist または blacklist の 2 つの値を指定することができます。blacklist は、リスト上の IP からのリクエストをすべて拒否します。whitelist は、リスト上に ない IP からのリクエストをすべて拒否します。

文字列 (whitelist または blacklist のどちらかでなければなりません)

必須

ips

ips プロパティーでは、ホワイトリストまたはブラックリストに登録する IP アドレスのリストを指定することができます。個別の IP および CIDR 範囲の両方を使用することができます。

文字列の配列 (有効な IP アドレスでなければなりません)

必須

error_msg

error_msg プロパティーを使用して、リクエストが拒否された時に返されるエラーメッセージを設定することができます。

文字列

いいえ

client_ip_sources

client_ip_sources プロパティーでは、クライアント IP の取得方法を設定することができます。デフォルトでは、最後に呼び出しを実施した IP が使用されます。これ以外のオプションは、X-Forwarded-For および X-Real-IP です。

文字列の配列。有効なオプションは、X-Forwarded-For、X-Real-IP、および last_caller です (複数の選択が可能です)。

いいえ

ポリシーオブジェクトの例 

{
  "name": "ip_check",
  "configuration": {
    "ips": [ "3.4.5.6", "1.2.3.0/4" ],
    "check_type": "blacklist",
    "client_ip_sources": ["X-Forwarded-For", "X-Real-IP", "last_caller"],
    "error_msg": "A custom error message"
  }
}
Copy to Clipboard Toggle word wrap

ポリシーの設定方法に関する情報は、本書の 3scale でのポリシーチェーンの作成 セクションを参照してください。

4.1.9. JWT Claim Check ポリシー
リンクのコピー

4.1.9.1. JWT Claim Check ポリシーの概要
リンクのコピー

JWT Claim Check ポリシーを使用すると、JSON Web Token (JWT) クレームに基づきリソースターゲットおよびメソッドをブロックする、新たなルールを定義することができます。

JWT クレームの値に基づいてルーティングするためには、ポリシーチェーンには、ポリシーが共有するコンテキストで JWT を検証してクレームを格納するポリシーが必要です。

JWT Claim Check ポリシーがリソースおよびメソッドをブロックしている場合には、ポリシーは JWT 操作も検証します。一方、メソッドおよびリソースがマッチしない場合には、リクエストはバックエンド API に送信されます。

以下の GET リクエストの例では、JWT には管理者として role クレームが必要です。もしなければ、リクエストは拒否されます。一方、GET 以外のリクエストは JWT 操作を検証しないため、POST リソースは JWT の制約なしに許可されます。 

{
  "name": "apicast.policy.jwt_claim_check",
  "configuration": {
      "error_message": "Invalid JWT check",
      "rules": [
          {
              "operations": [
                  {"op": "==", "jwt_claim": "role", "jwt_claim_type": "plain", "value": "admin"}
              ],
              "combine_op":"and",
              "methods": ["GET"],
              "resource": "/resource",
              "resource_type": "plain"
          }
      ]
  }
}
Copy to Clipboard Toggle word wrap

4.1.9.2. ポリシーチェーンへの JWT Claim Check ポリシーの設定
リンクのコピー

4.1.9.2.1. 前提条件
リンクのコピー
  • 3scale システムにアクセスできること。
  • すべてのデプロイメントが完了していること。
4.1.9.2.2. ポリシーの設定
リンクのコピー
  1. 管理ポータルでのポリシーの有効化 に記載の手順に従って JWT Claim Check を選択し、API に JWT Claim Check ポリシーを追加します。
  2. JWT Claim Check のリンクをクリックします。
  3. Enabled のチェックボックスを選択し、ポリシーを有効にします。
  4. ルールを追加するには、プラス (+) アイコンをクリックします。
  5. resource_type を指定します。
  6. 演算子を選択します。
  7. ルールによって制御される resource を指定します。
  8. 許可されるメソッドを追加するには、プラス (+) アイコンをクリックします。
  9. トラフィックがブロックされた時にユーザーに表示するエラーメッセージを入力します。
  10. API への JWT Claim Check ポリシーの設定が完了したら、Update Policy をクリックします。

付加手順:

  • 該当するセクションのプラス (+) アイコンをクリックして、さらにリソースタイプおよび許可されるメソッドを追加することができます。

変更を保存するには、Update & test in Staging Environment をクリックします。

4.1.10. Liquid Context Debug ポリシー
リンクのコピー

注記

Liquid Context Debug ポリシーの想定は、開発環境でのデバッグ用途のみで、実稼働環境での使用は意図されていません。

このポリシーは JSON を使用して API リクエストに応答します。コンテキストで利用可能なオブジェクトおよび値を含み、Liquid テンプレートの評価に使用することができます。3scale APIcast または Upstream ポリシーと組み合わせる場合には、正常な動作のためにポリシーチェーンではこれらのポリシーの前に Liquid Context Debug ポリシーを設定する必要があります。循環参照を避けるために、ポリシーには重複するオブジェクトは 1 回だけ含め、それをスタブ値で置き換えます。

このポリシーが有効な時に APIcast が返す値の例を以下に示します。 

{
  "jwt": {
    "azp": "972f7b4f",
    "iat": 1537538097,
    ...
    "exp": 1537574096,
    "typ": "Bearer"
  },
  "credentials": {
    "app_id": "972f7b4f"
  },
  "usage": {
    "deltas": {
      "hits": 1
    },
    "metrics": [
      "hits"
    ]
  },
  "service": {
    "id": "2",
    ...
  }
  ...
}
Copy to Clipboard Toggle word wrap

4.1.11. Logging ポリシー
リンクのコピー

Logging ポリシーにより、各 API サービスの APIcast (NGINX) アクセスログを個別に有効または無効にすることができます。デフォルトでは、このポリシーはポリシーチェーンで有効になっていません。

このポリシーは、enable_access_logs 設定パラメーターしかサポートしません。サービスのアクセスロギングを無効にするには、ポリシーを有効にし、enable_access_logs パラメーターの選択を解除して、Submit ボタンをクリックします。アクセスログを有効にするには、enable_access_logs パラメーターを選択するか、Logging ポリシーを無効にします。

ロギングポリシーの設定
View larger image
ロギングポリシーの設定

Logging ポリシーとアクセスログの場所のグローバル設定を組み合わせることができます。APIcast アクセスログの場所を設定するには、APICAST_ACCESS_LOG_FILE 環境変数を設定します。デフォルトでは、この変数は標準出力デバイスの /dev/stdout に設定されています。グローバル APIcast パラメーターに関する詳細な情報は、???を参照してください。

4.1.12. OAuth 2.0 Token Introspection ポリシー
リンクのコピー

OAuth 2.0 Token Introspection ポリシーを使用すると、OpenID Connect (OIDC) 認証オプションを用いるサービスに使用される JSON Web Token (JWT) トークンを検証することができます。この場合、トークン発行者 (Red Hat Single Sign-On) のトークンイントロスペクションエンドポイントを使用します。

トークンイントロスペクションエンドポイントおよびそのエンドポイントに呼び出しを行う際に APIcast が使用するクレデンシャルを定義する場合、auth_type フィールドでは以下の認証タイプがサポートされます。

  • use_3scale_oidc_issuer_endpoint: APIcast は、クライアントのクレデンシャル (クライアント ID および クライアントシークレット) ならびに Service Integration ページで定義した OIDC 発行者設定からのトークンイントロスペクションエンドポイントを使用します。APIcast は、token_introspection_endpoint フィールドからトークンイントロスペクションエンドポイントを検出します。このフィールドは、OIDC 発行者が返す .well-known/openid-configuration エンドポイントにあります。

例4.1 use_3scale_oidc_issuer_endpoint に設定された認証タイプ

"policy_chain": [
…​
  {
    "name": "apicast.policy.token_introspection",
    "configuration": {
      "auth_type": "use_3scale_oidc_issuer_endpoint"
    }
  }
…​
],
Copy to Clipboard Toggle word wrap

  • client_id+client_secret: このオプションでは、APIcast がトークン情報を要求するのに使用する クライアント ID および クライアントシークレット と共に、異なるトークンイントロスペクションエンドポイントを指定することができます。このオプションを使用する場合には、以下の設定パラメーターを定義します。

    • client_id: トークンイントロスペクションエンドポイント用のクライアント ID を設定します。
    • client_secret: トークンイントロスペクションエンドポイント用のクライアントシークレットを設定します。
    • introspection_url: イントロスペクションエンドポイントの URL を設定します。

例4.2 client_id+client_secret に設定された認証タイプ

"policy_chain": [
…​
  {
    "name": "apicast.policy.token_introspection",
    "configuration": {
      "auth_type": "client_id+client_secret",
      "client_id": "myclient",
      "client_secret": "mysecret",
      "introspection_url": "http://red_hat_single_sign-on/token/introspection"
    }
  }
…​
],
Copy to Clipboard Toggle word wrap

auth_type フィールドの設定にかかわらず、APIcast は Basic 認証を使用してトークンイントロスペクションの呼び出しを承認します (Authorization: Basic <token> ヘッダー、ここで <token> は Base64 でエンコードされた <client_id>:<client_secret> 設定です)。

OAuth 2.0 Token Introspection Configuration
View larger image
OAuth 2.0 Token Introspection Configuration

トークンイントロスペクションエンドポイントのレスポンスには、active 属性が含まれます。APIcast はこの属性の値を確認します。属性の値に応じて、APIcast は呼び出しを承認または拒否します。

  • true: 呼び出しを承認します
  • false: Authentication Failed エラーと共に呼び出しを拒否します

このポリシーを使用すると、トークンのキャッシュを有効にして、同じ JWT トークンに対する呼び出しのたびにトークンイントロスペクションエンドポイントに呼び出しを行うのを避けることができます。Token Introspection ポリシーのトークンキャッシュを有効にするには、max_cached_tokens フィールドを 0 (機能は無効) から 10000 までの値に設定します。さらに、max_ttl_tokens フィールドで、トークンの残存期間 (TTL) の値を 1 から 3600 秒に設定することができます。

4.1.13. Prometheus メトリクス
リンクのコピー

Prometheus はスタンドアロンのオープンソースのシステムモニターリングおよびアラート用ツールキットです。

重要

Red Hat 3scale の本リリースでは、Prometheus のインストールおよび設定はサポートされていません。オプションとして、コミュニティーバージョンの Prometheus を使用して、APIcast 管理下の API サービスのメトリクスおよびアラートを視覚化することができます。

Prometheus メトリクスの可用性

APIcast と Prometheus のインテグレーションは、以下のデプロイメントオプションで利用することができます。

  • Self-managed APIcast (ホスト型 API Management およびオンプレミス型 API Management 両方との組み合わせに対応)
  • Embedded APIcast (オンプレミス型 API Management)
注記

APIcast と Prometheus のインテグレーションは、ホスト型 API Management と Hosted APIcast の組み合わせでは利用することができません。

Prometheus メトリクスのリスト

以下のメトリクスは常に使用可能です。

Expand
メトリクス説明タイプラベル

nginx_http_connections

HTTP 接続の数

ゲージ

state (accepted、active、handled、reading、total、waiting、writing)

nginx_error_log

APIcast エラー

カウンター

level (debug、info、notice、warn、error、crit、alert、emerg)

openresty_shdict_capacity

ワーカー間で共有されるディクショナリーの容量

ゲージ

dict (すべてのディクショナリーで共通)

openresty_shdict_free_space

ワーカー間で共有されるディクショナリーの空き容量

ゲージ

dict (すべてのディクショナリーで共通)

nginx_metric_errors_total

メトリクスを管理する Lua ライブラリーのエラーの数

カウンター

-

total_response_time_seconds

クライアントにレスポンスを送信するのに必要な時間 (秒単位)

注記: service_id および service_system_name ラベルにアクセスするためには、APICAST_EXTENDED_METRICS 環境変数を true に設定する必要があります。

ヒストグラム

service_id、service_system_name

upstream_response_time_seconds

アップストリームサーバーからの応答時間 (秒単位)

注記: service_id および service_system_name ラベルにアクセスするためには、APICAST_EXTENDED_METRICS 環境変数を true に設定する必要があります。

ヒストグラム

service_id、service_system_name

upstream_status

アップストリームサーバーからの HTTP ステータス

注記: service_id および service_system_name ラベルにアクセスするためには、APICAST_EXTENDED_METRICS 環境変数を true に設定する必要があります。

カウンター

status、service_id、service_system_name

threescale_backend_calls

3scale バックエンド (Apisonator) に対する承認および報告リクエスト

カウンター

エンドポイント (authrep、auth、report)、ステータス (2xx、4xx、5xx)

以下のメトリクスは、3scale Batcher ポリシーを使用する場合にのみ使用可能です。

Expand
メトリクス説明タイプラベル

batching_policy_auths_cache_hits

3scale Batcher ポリシーの承認キャッシュのヒット数

カウンター

-

batching_policy_auths_cache_misses

3scale Batcher ポリシーの承認キャッシュのミス数

カウンター

-

値を持たないメトリクス

メトリクスが値を持たない場合には、メトリクスは非表示になります。たとえば、nginx_error_log に報告するエラーがない場合、nginx_error_log メトリックは表示されません。値を持った場合にのみ表示されます。

4.1.14. Referrer ポリシー
リンクのコピー

Referrer ポリシーを使用すると、参照元フィルター機能が有効になります。サービスポリシーチェーンでこのポリシーが有効な場合には、APIcast は今後のリクエストの Referer ポリシーの値を referrer パラメーターで Service Management API (AuthRep 呼び出し) に送信します。参照元フィルター機能の仕組みの詳細については、Authentication Patternsの Referrer filtering セクションを参照してください。

4.1.15. Retry ポリシー
リンクのコピー

Retry ポリシーは、アップストリーム API へのリトライリクエストの回数を設定します。Retry ポリシーはサービスごとに設定されるため、ユーザーは必要な数のサービスに対してリトライを有効にすることができ、またそれぞれのサービスに異なるリトライ数を設定することもできます。

重要

3scale 2.6 では、リトライするケースをポリシーから設定することはできません。この動作を制御する環境変数 APICAST_UPSTREAM_RETRY_CASES は、すべてのサービスにリトライリクエストを適用します。この点についての詳細は、APICAST_UPSTREAM_RETRY_CASES をご確認ください。

Retry ポリシー JSON の例を以下に示します。 

{
  "$schema": "http://apicast.io/policy-v1/schema#manifest#",
  "name": "Retry",
  "summary": "Allows retry requests to the upstream",
  "description": "Allows retry requests to the upstream",
  "version": "builtin",
  "configuration": {
    "type": "object",
    "properties": {
      "retries": {
        "description": "Number of retries",
        "type": "integer",
        "minimum": 1,
        "maximum": 10
      }
    }
  }
}
Copy to Clipboard Toggle word wrap

4.1.16. RH-SSO/Keycloak Role Check ポリシー
リンクのコピー

OpenID Connect 認証オプションと共に使用した場合、このポリシーによりロールの確認機能が追加されます。このポリシーは、Red Hat Single Sign-On (RH-SSO) により発行されたアクセストークンのレルムロールおよびクライアントロールを確認します。レルムロールを指定すると、3scale のすべてのクライアントリソースにロールの確認機能が追加されます。

ポリシー設定の type プロパティーで指定するロールの確認には、2 つのタイプがあります。

  • whitelist (デフォルト): whitelist が使用されると、APIcast は指定したスコープが JWT トークンに含まれるかどうかを確認し、JWT にそのスコープがなければ呼び出しを拒否します。
  • blacklist: blacklist が使用された場合には、JWT トークンにブラックリスト登録したスコープが含まれていれば APIcast は呼び出しを拒否します。

同じポリシーに blacklist および whitelist 両方のチェックを設定することはできませんが、APIcast ポリシーチェーンに複数の RH-SSO/Keycloak Role Check ポリシーインスタンスを追加することができます。

ポリシー設定の scopes プロパティーを使用して、スコープのリストを設定することができます。

それぞれの scope オブジェクトには、以下のプロパティーがあります。

  • resource: ロールによって制御されるリソース (エンドポイント)。これは、マッピングルールと同じフォーマットです。文字列の先頭からパターンの照合を行います。完全一致の場合には、最後に $ を追加する必要があります。

  • resource_type: このプロパティーで、resource の値がどのように評価されるかを定義します。

    • プレーンテキストとして (plain): resource の値をプレーンテキストとして評価します。たとえば /api/v1/products$。
    • Liquid テキストとして (liquid): resource の値に Liquid を使用することを許可します。たとえば、/resource_{{ jwt.aud }} は、クライアント ID が含まれるリソースへのアクセスを管理します。

  • methods: RH-SSO のユーザーロールに基づいて APIcast で許可される HTTP メソッドを一覧表示する場合に、このパラメーターを使用します。たとえば、以下のロールを持つメソッドを許可することができます。

    • /resource1 にアクセスするための role1 レルムロール。このレルムロールを持たないメソッドの場合には、blacklist を指定する必要があります。
    • /resource1 にアクセスするための role1 という client1 ロール
    • /resource1 にアクセスするための role1 および role2 レルムロール。realm_roles でロールを指定します。各ロールのスコープを指定することもできます。
    • /resource1 にアクセスするための、アプリケーションクライアントの role1 というクライアントロール (アクセストークンの受領者)。クライアントに JSON Web Token (JWT) 情報を指定するには、liquid クライアントタイプを使用します。
    • /resource1 にアクセスするための、アプリケーションクライアントのクライアント ID が含まれるクライアントロール (アクセストークンの受領者)。クライアントロールの name に JWT 情報を指定するには、liquid クライアントタイプを使用します。
    • アプリケーションのクライアント ID が含まれるリソースにアクセスするための、role1 というクライアントロール。resource に JWT 情報を指定するには、liquid クライアントタイプを使用します。

  • realm_roles: レルムロールを確認する場合に使用します (Red Hat Single Sign-On のレルムロール に関するドキュメントを参照してください)。

    レルムロールは、Red Hat Single Sign-On により発行された JWT にあります。 

      "realm_access": {
    "roles": [
      "<realm_role_A>", "<realm_role_B>"
    ]
  }
    Copy to Clipboard Toggle word wrap

    実際のロールは、ポリシーで指定する必要があります。 

    "realm_roles": [
  { "name": "<realm_role_A>" }, { "name": "<realm_role_B>" }
]
    Copy to Clipboard Toggle word wrap

    realm_roles 配列の各オブジェクトでは、以下のプロパティーを使用することができます。

  • name: ロールの名前を指定します。
  • name_type: plain または liquid のどちらかを指定して、name がどのように評価されるかを定義します (resource_type の場合と同じように機能します)。

  • client_roles: クライアント namespace に特定のアクセ出力ルがあるかどうかを確認する場合に、client_roles を使用します (Red Hat Single Sign-On のクライアントロール に関するドキュメントを参照してください)。

    クライアントロールは、JWT の resource_access クレームのセクションにあります。 

      "resource_access": {
    "<client_A>": {
      "roles": [
        "<client_role_A>", "<client_role_B>"
      ]
    },
    "<client_B>": {
      "roles": [
        "<client_role_A>", "<client_role_B>"
      ]
    }
  }
    Copy to Clipboard Toggle word wrap

    ポリシーでクライアントロールを指定します。 

    "client_roles": [
  { "name": "<client_role_A>", "client": "<client_A>" },
  { "name": "<client_role_B>", "client": "<client_A>" },
  { "name": "<client_role_A>", "client": "<client_B>" },
  { "name": "<client_role_B>", "client": "<client_B>" }
]
    Copy to Clipboard Toggle word wrap

    client_roles 配列の各オブジェクトでは、以下のプロパティーを使用することができます。

  • name: ロールの名前を指定します。
  • name_type: plain または liquid のどちらかを指定して、name の値がどのように評価されるかを定義します (resource_type の場合と同じように機能します)。
  • client: ロールのクライアントを指定します。定義しなければ、このポリシーはクライアントに aud クレームを使用します。
  • client_type: plain または liquid のどちらかを指定して、client の値がどのように評価されるかを定義します (resource_type の場合と同じように機能します)。

4.1.17. Routing ポリシー
リンクのコピー

Routing ポリシーを使用すると、リクエストをさまざまなターゲットエンドポイントにルーティングすることができます。ターゲットエンドポイントを定義すると、正規表現を使用して UI から受信したリクエストをターゲットエンドポイントにルーティングできるようになります。

ルーティングは、以下のルールに基づきます。

APIcast ポリシーと組み合わせる場合には、ポリシーチェーンでは APIcast ポリシーの前に Routing ポリシーを設定する必要があります。2 つのポリシーのうち始めのポリシーがレスポンスにコンテンツを出力するためです。2 番目のポリシーにコンテンツフェーズを実行する変更が加えられても、リクエストはすでにクライアントに送信されるため、レスポンスには何も出力されません。

4.1.17.1. ルーティングルール
リンクのコピー

  • 複数のルールが存在する場合には、Routing ポリシーは最初のマッチに適用されます。これらのルールは並べ替えることができます。
  • マッチするルールがなければ、ポリシーはアップストリームを変更せず、サービス設定で定義済みのプライベートベース URL を使用します。

4.1.17.2. リクエストパスルール
リンクのコピー

以下の設定では、パスが /accounts の場合に http://example.com にルーティングします。 

{
   "name": "routing",
   "version": "builtin",
   "configuration": {
     "rules": [
       {
         "url": "http://example.com",
         "condition": {
           "operations": [
             {
               "match": "path",
               "op": "==",
               "value": "/accounts"
             }
           ]
         }
       }
     ]
   }
 }
Copy to Clipboard Toggle word wrap

4.1.17.3. ヘッダールール
リンクのコピー

以下の設定では、ヘッダー Test-Header の値が 123 の場合に http://example.com にルーティングします。 

{
   "name": "routing",
   "version": "builtin",
   "configuration": {
     "rules": [
       {
         "url": "http://example.com",
         "condition": {
           "operations": [
             {
               "match": "header",
               "header_name": "Test-Header",
               "op": "==",
               "value": "123"
             }
           ]
         }
       }
     ]
   }
 }
Copy to Clipboard Toggle word wrap

4.1.17.4. クエリー引数ルール
リンクのコピー

以下の設定では、クエリー引数 test_query_arg の値が 123 の場合に http://example.com にルーティングします。 

{
   "name": "routing",
   "version": "builtin",
   "configuration": {
     "rules": [
       {
         "url": "http://example.com",
         "condition": {
           "operations": [
             {
               "match": "query_arg",
               "query_arg_name": "test_query_arg",
               "op": "==",
               "value": "123"
             }
           ]
         }
       }
     ]
   }
 }
Copy to Clipboard Toggle word wrap

4.1.17.5. JWT クレームルール
リンクのコピー

JWT クレームの値に基づいてルーティングするためには、ポリシーチェーンには、ポリシーが共有するコンテキストで JWT を検証して格納するポリシーが必要です。

以下の設定では、JWT クレーム test_claim の値が 123 の場合に http://example.com にルーティングします。 

{
   "name": "routing",
   "version": "builtin",
   "configuration": {
     "rules": [
       {
         "url": "http://example.com",
         "condition": {
           "operations": [
             {
               "match": "jwt_claim",
               "jwt_claim_name": "test_claim",
               "op": "==",
               "value": "123"
             }
           ]
         }
       }
     ]
   }
 }
Copy to Clipboard Toggle word wrap

4.1.17.6. 複数演算ルール
リンクのコピー

ルールに複数の演算を設定し、すべてが true と評価される場合にだけ (andcombine_op を使用) 指定したアップストリームにルーティングすることや、少なくとも 1 つが true と評価される場合に (orcombine_op を使用) 指定したアップストリームにルーティングすることができます。combine_op のデフォルト値は and です。

以下の設定では、リクエストのパスが /accounts で、かつヘッダー Test-Header の値が 123 の場合に、http://example.com にルーティングします。 

{
   "name": "routing",
   "version": "builtin",
   "configuration": {
     "rules": [
       {
         "url": "http://example.com",
         "condition": {
           "combine_op": "and",
           "operations": [
             {
               "match": "path",
               "op": "==",
               "value": "/accounts"
             },
             {
               "match": "header",
               "header_name": "Test-Header",
               "op": "==",
               "value": "123"
             }
           ]
         }
       }
     ]
   }
 }
Copy to Clipboard Toggle word wrap

以下の設定では、リクエストのパスが /accounts であるか、またはヘッダー Test-Header の値が 123 の場合に、http://example.com にルーティングします。 

{
   "name": "routing",
   "version": "builtin",
   "configuration": {
     "rules": [
       {
         "url": "http://example.com",
         "condition": {
           "combine_op": "or",
           "operations": [
             {
               "match": "path",
               "op": "==",
               "value": "/accounts"
             },
             {
               "match": "header",
               "header_name": "Test-Header",
               "op": "==",
               "value": "123"
             }
           ]
         }
       }
     ]
   }
 }
Copy to Clipboard Toggle word wrap

4.1.17.7. ルールの結合
リンクのコピー

ルールを組み合わせることができます。複数のルールがある場合、選択されるアップストリームは、true と評価される最初のルールです。

複数のルールで設定される設定を以下に示します。 

{
   "name": "routing",
   "version": "builtin",
   "configuration": {
     "rules": [
       {
         "url": "http://some_upstream.com",
         "condition": {
           "operations": [
             {
               "match": "path",
               "op": "==",
               "value": "/accounts"
             }
           ]
         }
       },
       {
         "url": "http://another_upstream.com",
         "condition": {
           "operations": [
             {
               "match": "path",
               "op": "==",
               "value": "/users"
             }
           ]
         }
       }
     ]
   }
 }
Copy to Clipboard Toggle word wrap

4.1.17.8. キャッチオールルール
リンクのコピー

演算のないルールは常にマッチします。これは、キャッチオールルールを定義するのに役立ちます。

以下の設定では、パスが /abc の場合にはリクエストを http://some_upstream.com にルーティングし、パスが /def の場合には http://another_upstream.com にルーティングし、上記ルールのどちらも true と評価されない場合には http://default_upstream.com にルーティングします。 

{
   "name": "routing",
   "version": "builtin",
   "configuration": {
     "rules": [
       {
         "url": "http://some_upstream.com",
         "condition": {
           "operations": [
             {
               "match": "path",
               "op": "==",
               "value": "/abc"
             }
           ]
         }
       },
       {
         "url": "http://another_upstream.com",
         "condition": {
           "operations": [
             {
               "match": "path",
               "op": "==",
               "value": "/def"
             }
           ]
         }
       },
       {
         "url": "http://default_upstream.com",
         "condition": {
           "operations": []
         }
       }
     ]
   }
 }
Copy to Clipboard Toggle word wrap

4.1.17.9. サポートされる操作
リンクのコピー

サポートされる演算は、==、!=、および matches です。最後の演算は正規表現を使用する文字列との照合を行い、ngx.re.match を使用して実装されます。

以下の設定では、!= が使用されています。パスが /accounts ではない場合に http://example.com にルーティングします。 

{
   "name": "routing",
   "version": "builtin",
   "configuration": {
     "rules": [
       {
         "url": "http://example.com",
         "condition": {
           "operations": [
             {
               "match": "path",
               "op": "!=",
               "value": "/accounts"
             }
           ]
         }
       }
     ]
   }
 }
Copy to Clipboard Toggle word wrap

4.1.17.10. Liquid テンプレート
リンクのコピー

設定の値に liquid テンプレートを使用することができます。これにより、チェーン内のポリシーがコンテキストにキー my_var を保存する場合には、動的な値を使用してルールを定義することができます。

以下の設定では、リクエストをルーティングするのにその値が使用されています。 

{
   "name": "routing",
   "version": "builtin",
   "configuration": {
     "rules": [
       {
         "url": "http://example.com",
         "condition": {
           "operations": [
             {
               "match": "header",
               "header_name": "Test-Header",
               "op": "==",
               "value": "{{ my_var }}",
               "value_type": "liquid"
             }
           ]
         }
       }
     ]
   }
 }
Copy to Clipboard Toggle word wrap

4.1.17.11. Host ヘッダーで使用されるホストの設定
リンクのコピー

リクエストがルーティングされる際に、デフォルトでは、ポリシーはマッチしたルールの URL のホストを使用して Host ヘッダーを設定します。host_header 属性を使用して別のホストを指定することができます。

以下の設定では、Host ヘッダーのホストに some_host.com が指定されています。 

{
   "name": "routing",
   "version": "builtin",
   "configuration": {
     "rules": [
       {
         "url": "http://example.com",
         "host_header": "some_host.com",
         "condition": {
           "operations": [
             {
               "match": "path",
               "op": "==",
               "value": "/"
             }
           ]
         }
       }
     ]
   }
 }
Copy to Clipboard Toggle word wrap

4.1.18. SOAP ポリシー
リンクのコピー

SOAP ポリシーでは、ポリシーで指定したマッピングルールを使用して、HTTP リクエストの SOAPAction または Content-Type ヘッダーにより提供される SOAP アクション URI との照合を行います。

設定プロパティー

Expand
プロパティー説明値必須/任意

pattern

pattern プロパティーにより、APIcast がマッチを探す SOAPAction URI の文字列を指定することができます。

データタイプ: 文字列

必須

metric_system_name

metric_system_name プロパティーを使用して、マッチしたパターンがヒットを登録する 3scale バックエンドメトリクスを指定することができます。

データタイプ: 文字列 (有効な メトリクス でなければなりません)

必須

ポリシーオブジェクトの例 

{
  "name": "soap",
  "version": "builtin",
  "configuration": {
    "mapping_rules": [
      {
        "pattern": "http://example.com/soap#request",
        "metric_system_name": "soap",
        "delta": 1
      }
    ]
  }
}
Copy to Clipboard Toggle word wrap

ポリシーの設定方法に関する情報は、本書の 3scale でのポリシーチェーンの作成 セクションを参照してください。

4.1.19. TLS Client Certificate Validation ポリシー
リンクのコピー

4.1.19.1. TLS Client Certificate Validation ポリシーの概要
リンクのコピー

TLS Client Certificate Validation ポリシーでは、APIcast は TLS ハンドシェイクを実装し、ホワイトリストに対してクライアント証明書を検証します。ホワイトリストには、認証局 (CA) によって署名された証明書、または単なるクライアント証明書が含まれます。証明書の有効期限が切れている、または証明書が無効な場合には、リクエストは拒否され他のポリシーは処理されません。

クライアントは APIcast に接続してリクエストを送信し、クライアント証明書を提供します。APIcast は、ポリシー設定に従って受信したリクエストで提供された証明書の信ぴょう性を検証します。アップストリームに接続する際に独自のクライアント証明書を使用するように、APIcast を設定することもできます。

4.1.19.2. TLS Client Certificate Validation ポリシーに対応する APIcast の設定
リンクのコピー

TLS を終端するように APIcast を設定する必要があります。以下の手順に従って、Client Certificate Validation ポリシーが設定された APIcast でユーザーが提供するクライアント証明書を検証するように設定します。

4.1.19.2.1. 前提条件:
リンクのコピー
  • 3scale システムにアクセスできること。
  • すべてのデプロイメントが完了していること。
4.1.19.2.2. ポリシーに対応する APIcast のセットアップ
リンクのコピー

APIcast をセットアップし TLS を終端するように設定するには、以下の手順に従います。

  1. OpenShift テンプレートを使用した APIcast のデプロイ に記載の手順に従って、アクセストークンを取得し Self-managed APIcast をデプロイする必要があります。

    注記

    ゲートウェイ全体で特定の証明書を使用するように APIcast インスタンスを再設定しなければならないので、Self-managed APIcast のデプロイメントが必要です。

  2. テストを簡素化するために、--param フラグを指定してレイジーローダー、キャッシュなし、およびステージング環境を使用することができます (ただし、テスト目的の場合のみ)。 

    oc new-app -f https://raw.githubusercontent.com/3scale/3scale-amp-openshift-templates/2.6.0.GA/apicast-gateway/apicast.yml --param CONFIGURATION_LOADER=lazy --param DEPLOYMENT_ENVIRONMENT=staging --param CONFIGURATION_CACHE=0
    Copy to Clipboard Toggle word wrap
  3. テスト用途の証明書を生成します。なお、実稼働環境のデプロイメントの場合には、認証局から提供された証明書を使用することができます。

  4. TLS 証明書を使用してシークレットを作成します。 

    oc create secret tls apicast-tls
--cert=ca/certs/server.crt
--key=ca/keys/server.key
    Copy to Clipboard Toggle word wrap

  5. APIcast デプロイメント内にシークレットをマウントします。 

    oc set volume dc/apicast --add --name=certificates --mount-path=/var/run/secrets/apicast --secret-name=apicast-tls
    Copy to Clipboard Toggle word wrap

  6. HTTPS 用ポート 8443 のリッスンを開始するように APIcast を設定します。 

    oc set env dc/apicast APICAST_HTTPS_PORT=8443 APICAST_HTTPS_CERTIFICATE=/var/run/secrets/apicast/tls.crt APICAST_HTTPS_CERTIFICATE_KEY=/var/run/secrets/apicast/tls.key
    Copy to Clipboard Toggle word wrap

  7. サービスでポート 8443 を公開します。 

    oc patch service apicast -p '{"spec":{"ports":[{"name":"https","port":8443,"protocol":"TCP"}]}}'
    Copy to Clipboard Toggle word wrap

  8. デフォルトルートを削除します。 

    oc delete route api-apicast-staging
    Copy to Clipboard Toggle word wrap

  9. apicast サービスをルートとして公開します。 

    oc create route passthrough --service=apicast --port=https --hostname=api-3scale-apicast-staging.$WILDCARD_DOMAIN
    Copy to Clipboard Toggle word wrap
    注記

    このステップは、使用するすべての API で実施する必要があります (それぞれの API のドメインに変更してください)。

  10. プレースホルダーの [Your_user_key] に実際のキーを指定して、上記のステップでデプロイしたゲートウェイが機能し、設定が保存されていることを確認します。 

    curl https://api-3scale-apicast-staging.$WILDCARD_DOMAIN?user_key=[Your_user_key] -v --cacert ca/certs/ca.crt
    Copy to Clipboard Toggle word wrap

4.1.19.3. ポリシーチェーンへの TLS Client Certificate Validation ポリシーの設定
リンクのコピー

4.1.19.3.1. 前提条件
リンクのコピー
4.1.19.3.2. ポリシーの設定
リンクのコピー
  1. 管理ポータルでのポリシーの有効化 に記載の手順に従って TLS Client Certificate Validation を選択し、API に TLS Client Certificate Validation ポリシーを追加します。
  2. TLS Client Certificate Validation のリンクをクリックします。
  3. Enabled のチェックボックスを選択し、ポリシーを有効にします。
  4. 証明書をホワイトリストに追加するには、プラス (+) アイコンをクリックします。
  5. -----BEGIN CERTIFICATE----- および -----END CERTIFICATE----- を含めて、証明書を指定します。
  6. API への TLS Client Certificate Validation ポリシーの設定が完了したら、Update Policy をクリックします。

付加手順:

  • プラス (+) アイコンをクリックして、さらに証明書を追加することができます。
  • 上/下矢印を使用して、証明書の順番を入れ替えることもできます。

変更を保存するには、Update & test in Staging Environment をクリックします。

4.1.19.4. TLS Client Certificate Validation ポリシー機能の確認
リンクのコピー

4.1.19.4.1. 前提条件
リンクのコピー
4.1.19.4.2. ポリシー機能の確認
リンクのコピー

プレースホルダーの [Your_user_key] に実際のキーを指定して、適用したポリシーを確認することができます。 

curl https://api-3scale-apicast-staging.$WILDCARD_DOMAIN\?user_key\=[Your_user_key] -v --cacert ca/certs/ca.crt --cert ca/certs/client.crt --key ca/keys/client.key

curl https://api-3scale-apicast-staging.$WILDCARD_DOMAIN\?user_key\=[Your_user_key] -v --cacert ca/certs/ca.crt --cert ca/certs/server.crt --key ca/keys/server.key

curl https://api-3scale-apicast-staging.$WILDCARD_DOMAIN\?user_key\=[Your_user_key] -v --cacert ca/certs/ca.crt
Copy to Clipboard Toggle word wrap

4.1.19.5. ホワイトリストからの証明書の削除
リンクのコピー

4.1.19.5.1. 前提条件
リンクのコピー
4.1.19.5.2. 証明書の削除
リンクのコピー
  1. TLS Client Certificate Validation のリンクをクリックします。
  2. x アイコンをクリックし、ホワイトリストから証明書を削除します。
  3. 証明書の削除が完了したら、Update Policy をクリックします。

変更を保存するには、Update & test in Staging Environment をクリックします。

4.1.19.6. リファレンス資料
リンクのコピー

証明書の操作についての詳細は、Red Hat Certificate System のドキュメント を参照してください。

4.1.20. Upstream ポリシー
リンクのコピー

Upstream ポリシーでは、正規表現を使用して Host リクエストヘッダーを解析し、プライベートベース URL で定義されたアップストリーム URL を別の URL に置き換えることができます。

例:

正規表現 /foo および URL フィールド newexample.com が設定されたポリシーが、URL https://www.example.com/foo/123/ を newexample.com に置き換える

ポリシーチェーンの参照

Expand
プロパティー説明値必須/任意

regex

regex プロパティーを使用して、Upstream ポリシーがリクエストパスを照合する際に使用する正規表現を指定することができます。

データタイプ: 文字列 (有効な正規表現の構文でなければなりません)

必須

url

url プロパティーを使用して、マッチした場合に置き換える URL を指定することができます。Upstream ポリシーはこの URL が有効かどうかを確認しない点に注意してください。

データタイプ: 文字列 (有効な URL でなければなりません)

必須

ポリシーオブジェクトの例 

{
  "name": "upstream",
  "version": "builtin",
  "configuration": {
    "rules": [
      {
        "regex": "^/v1/.*",
        "url": "https://api-v1.example.com",

      }
    ]
  }
}
Copy to Clipboard Toggle word wrap

ポリシーの設定方法に関する情報は、本書の 3scale でのポリシーチェーンの作成 セクションを参照してください。

4.1.21. Upstream Connection ポリシー
リンクのコピー

4.1.21.1. Upstream Connection ポリシーの概要
リンクのコピー

Upstream Connection ポリシーを使用すると、3scale システムでの API バックエンドサーバーの設定に応じて、API ごとに以下のディレクティブのデフォルト値を変更することができます。

  • proxy_connect_timeout
  • proxy_send_timeout
  • proxy_read_timeout

4.1.21.2. ポリシーチェーンへの Upstream Connection ポリシーの設定
リンクのコピー

4.1.21.2.1. 前提条件
リンクのコピー
  • 3scale システムにアクセスできること。
  • すべてのデプロイメントが完了していること。
4.1.21.2.2. ポリシーの設定
リンクのコピー
  1. 管理ポータルでのポリシーの有効化 に記載の手順に従って Upstream Connection を選択し、API に Upstream Connection ポリシーを追加します。
  2. Upstream connection のリンクをクリックします。
  3. Enabled のチェックボックスを選択し、ポリシーを有効にします。

  4. アップストリームへの接続に関するオプションを設定します。

    • send_timeout
    • connect_timeout
    • read_timeout
  5. API への Upstream Connection ポリシーの設定が完了したら、Update Policy をクリックします。

変更を保存するには、Update & test in Staging Environment をクリックします。

4.1.22. URL Rewriting ポリシー
リンクのコピー

URL Rewriting ポリシーを使用すると、リクエストのパスおよびクエリー文字列を変更することができます。

3scale APIcast ポリシーと組み合わせる場合には、ポリシーチェーンで URL Rewriting ポリシーを 3scale APIcast ポリシーの前に設定すると、APIcast のマッピングルールは変更したパスに適用されます。ポリシーチェーンで URL Rewriting ポリシーを APIcast ポリシーの後に設定すると、マッピングルールは元のパスに適用されます。

このポリシーでは、以下の 2 つの操作セットがサポートされます。

  • commands: リクエストのパスを書き換えるために適用されるコマンドのリスト。
  • query_args_commands: リクエストのクエリー文字列を書き換えるために適用されるコマンドのリスト。

4.1.22.1. パスを書き換えるためのコマンド
リンクのコピー

commands リストの各コマンドは、以下の設定パラメーターで設定されます。

  • op: 適用される操作。設定可能なオプションは sub および gsub です。sub 操作では、指定した正規表現との最初のマッチだけが置き換えられます。gsub 操作では、指定した正規表現とのマッチがすべて置き換えられます。sub および gsub 操作に関するドキュメントを参照してください。
  • regex: 照合される Perl 互換の正規表現
  • replace: マッチした際に置き換えられる文字列
  • options (オプション): 正規表現との照合がどのように行われるかを定義するオプション。設定可能なオプションに関する情報は、OpenResty Lua モジュールプロジェクトのドキュメントの ngx.re.match セクションを参照してください。
  • break (オプション): true に設定すると (チェックボックスを選択する)、コマンドが URL を書き換えた場合、それが適用される最後のコマンドになります (リスト内の後続コマンドはすべて破棄されます)。

4.1.22.2. クエリー文字列を書き換えるためのコマンド
リンクのコピー

query_args_commands リストの各コマンドは、以下の設定パラメーターで設定されます。

  • op: クエリー引数に適用される操作。以下のオプションを設定することができます。

    • add: 既存の引数に値を追加します。
    • set: 引数が設定されていなければ作成し、設定されていればその値を置き換えます。
    • push: 引数が設定されていなければ作成し、設定されていれば値を追加します。
    • delete: 引数を削除します。
  • arg: 操作が適用されるクエリー引数の名前
  • value: クエリー引数に使用される値を指定します。値のタイプが liquid の場合には、値は {{ variable_from_context }} の形式にする必要があります。delete 操作の場合には、値を考慮する必要はありません。
  • value_type (オプション): クエリー引数の値がどのように評価されるかを定義します。プレーンテキストの場合の plain または Liquid テンプレートとして評価する場合の liquid いずれかに設定します。詳細は、「ポリシーでの変数およびフィルターの使用」 を参照してください。指定しなければ、デフォルトではタイプ plain が使用されます。

例

URL Rewriting ポリシーは、以下のように設定します。 

{
  "name": "url_rewriting",
  "version": "builtin",
  "configuration": {
    "query_args_commands": [
      {
        "op": "add",
        "arg": "addarg",
        "value_type": "plain",
        "value": "addvalue"
      },
      {
        "op": "delete",
        "arg": "user_key",
        "value_type": "plain",
        "value": "any"
      },
      {
        "op": "push",
        "arg": "pusharg",
        "value_type": "plain",
        "value": "pushvalue"
      },
      {
        "op": "set",
        "arg": "setarg",
        "value_type": "plain",
        "value": "setvalue"
      }
    ],
    "commands": [
      {
        "op": "sub",
        "regex": "^/api/v\\d+/",
        "replace": "/internal/",
        "options": "i"
      }
    ]
  }
Copy to Clipboard Toggle word wrap

APIcast に送信される元のリクエスト URI: 

https://api.example.com/api/v1/products/123/details?user_key=abc123secret&pusharg=first&setarg=original
Copy to Clipboard Toggle word wrap

URL の書き換えを適用した後に APIcast が API バックエンドに送信する URI: 

https://api-backend.example.com/internal/products/123/details?pusharg=first&pusharg=pushvalue&setarg=setvalue
Copy to Clipboard Toggle word wrap

以下の変換が適用されます。

  1. サブストリング /api/v1/ はパス書き換えコマンドだけにマッチし、/internal/ に置き換えられます。
  2. user_key クエリー引数は削除されます。
  3. 値 pushvalue は追加の値として pusharg クエリー引数に追加されます。
  4. クエリー引数 setarg の値 original は、設定した値 setvalue に置き換えられます。
  5. クエリー引数 addarg は元の URL に存在しないため、コマンド add は適用されませんでした。

ポリシーの設定方法に関する情報は、本書の 3scale でのポリシーチェーンの作成 セクションを参照してください。

4.1.23. URL Rewriting with Captures ポリシー
リンクのコピー

URL Rewriting with Captures ポリシーは「URL Rewriting ポリシー」ポリシーの代替で、API リクエストの URL を API バックエンドに渡す前に書き換えることができます。

URL Rewriting with Captures ポリシーは URL の引数を取得し、その値を書き換えられる URL で使用します。

このポリシーでは transformations 設定パラメーターがサポートされます。これは、リクエスト URL に適用される変換を定義するオブジェクトのリストです。それぞれの変換オブジェクトは、以下の 2 つのプロパティーで設定されます。

  • match_rule: このルールは受信したリクエストの URL と照合されます。このルールには {nameOfArgument} 形式の名前付き引数を含めることができ、これらの引数を書き換えられる URL で使用することができます。URL は正規表現として match_rule と比較されます。名前付き引数と照合する値には、[\w-.~%!$&'()*+,;=@:]+ の文字しか使用することができません (PCRE 正規表現表記)。他の正規表現トークンを match_rule の表記で使用することができます。たとえば、文字列先頭の ^ および文字列末尾の $ 等です。
  • template: URL のテンプレートで、これにより元の URL が書き換えられます。match_rule からの名前付き引数を使用することができます。

元の URL のクエリーパラメーターは、template で指定したクエリーパラメーターとマージされます。

例

URL Rewriting with Captures ポリシーは、以下のように設定します。 

{
  "name": "rewrite_url_captures",
  "version": "builtin",
  "configuration": {
    "transformations": [
      {
        "match_rule": "/api/v1/products/{productId}/details",
        "template": "/internal/products/details?id={productId}&extraparam=anyvalue"
      }
    ]
  }
}
Copy to Clipboard Toggle word wrap

APIcast に送信される元のリクエスト URI: 

https://api.example.com/api/v1/products/123/details?user_key=abc123secret
Copy to Clipboard Toggle word wrap

URL の書き換えを適用した後に APIcast が API バックエンドに送信する URI: 

https://api-backend.example.com/internal/products/details?user_key=abc123secret&extraparam=anyvalue&id=123
Copy to Clipboard Toggle word wrap
トップに戻る
Red Hat logoGithubredditYoutubeTwitter

詳細情報

試用、購入および販売

コミュニティー

Red Hat ドキュメントについて

Red Hat をお使いのお客様が、信頼できるコンテンツが含まれている製品やサービスを活用することで、イノベーションを行い、目標を達成できるようにします。 最新の更新を見る.

多様性を受け入れるオープンソースの強化

Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。このような変更は、段階的に実施される予定です。詳細情報: Red Hat ブログ.

会社概要

Red Hat は、企業がコアとなるデータセンターからネットワークエッジに至るまで、各種プラットフォームや環境全体で作業を簡素化できるように、強化されたソリューションを提供しています。

Theme

© 2025 Red Hat