第4章 APIcast ポリシー

管理ポータルでは、3scale API プロダクトごとに 1 つ以上のポリシーを有効にすることができます。

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

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

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

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

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

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

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

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

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

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

設定プロパティー

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

{
  "name": "caching",
  "version": "builtin",
  "configuration": {
    "caching_type": "allow"
  }
}

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

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

3scale Batcher ポリシーを使用すると、承認ステータスがキャッシュされ使用状況レポートがバッチ処理されます。これにより、3scale バックエンドへのリクエスト数が大幅に削減されます。3scale Batcher ポリシーにより、レイテンシーを短縮しスループットを増やすことで、API キャストのパフォーマンスを改善できます。

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

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

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

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

3scale Referrer ポリシーを使用すると、参照元フィルター 機能が有効になります。サービスポリシーチェーンでこのポリシーが有効な場合には、APIcast は上流への AuthRep コールとして 3scale Referrer ポリシーの値をService Management API に送信します。3scale Referrer ポリシーの値は、呼び出しの referrer パラメーターで送信されます。

参照元フィルター機能の仕組みの詳細については、認証パターンの 参照元フィルター セクションを参照してください。

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

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

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

図4.1 Anonymous Access ポリシー

Camel Service ポリシーを使用して、定義した Apache Camel プロキシーを使用して 3scale のトラフィックを送信する HTTP プロキシー を定義することができます。この場合、Camel はリバース HTTP プロキシーとして機能し、APIcast は Camel にトラフィックを送信し、Camel がそのトラフィックを API バックエンドに送信します。

トラフィックフローの例を以下に示します。

3scale バックエンドに送信された APIcast トラフィックは、すべて Camel プロキシーを使用しません。このポリシーは、Camel プロキシーおよび APIcast と API バックエンド間の通信にのみ適用されます。

すべてのトラフィックをプロキシー経由で送信するには、HTTP_PROXY 環境変数を使用する必要があります。

"policy_chain": [
    {
      "name": "apicast.policy.apicast"
    },
    {
      "name": "apicast.policy.camel",
      "configuration": {
          "all_proxy": "http://192.168.15.103:8080/",
          "http_proxy": "http://192.168.15.103:8080/",
          "https_proxy": "http://192.168.15.103:8443/"
      }
    }
]

http_proxy または https_proxy が定義されていない場合は、all_proxy の値が使用されます。

一般的な HTTP プロキシーポリシー使用の詳細は、「Proxy Service」を参照してください。

Conditional ポリシーは、ポリシーチェーンが含まれるため、他の APIcast ポリシーとは異なります。このポリシーは、access、rewrite、log など、各 nginx フェーズ で評価される条件を定義します。条件が true の場合には、Conditional ポリシーは、チェーンに含まれるポリシーごとにフェーズを実行します。

以下の例では、Conditional ポリシーが the request method is POST の条件を定義していると仮定しています。

APIcast --> Caching --> Conditional --> Upstream

                             |
                             v

                          Headers

                             |
                             v

                       URL Rewriting

今回の例では、リクエストが POST の場合に、各フェーズの実行順序は以下のようになります。

リクエストが POST でない場合には、各フェーズの実行順序は以下のようになります。

以下の例では、リクエストパスが /example_path かどうかを確認します。

{
  "left": "{{ uri }}",
  "left_type": "liquid",
  "op": "==",
  "right": "/example_path",
  "right_type": "plain"
}

左側のオペランドと右のオペランドの両方を Liquid または plain 文字列として評価できます。デフォルトは、Plain 文字列です。

and または or を使用した操作を組み合わせることができます。この設定では、以前の例の内容に加え、Backend ヘッダーの値を確認します。

{
  "operations": [
    {
      "left": "{{ uri }}",
      "left_type": "liquid",
      "op": "==",
      "right": "/example_path",
      "right_type": "plain"
    },
    {
      "left": "{{ headers['Backend'] }}",
      "left_type": "liquid",
      "op": "==",
      "right": "test_upstream",
      "right_type": "plain"
    }
  ],
  "combine_op": "and"
}

詳細は、policy config schema を参照してください。

変数の更新リストは ngx_variable.lua を参照してください。

以下の例では、リクエストの Backend ヘッダーが staging の場合に、アップストリームポリシーを実行します。

{
   "name":"conditional",
   "version":"builtin",
   "configuration":{
      "condition":{
         "operations":[
            {
               "left":"{{ headers['Backend'] }}",
               "left_type":"liquid",
               "op":"==",
               "right":"staging"
            }
         ]
      },
      "policy_chain":[
         {
            "name":"upstream",
            "version": "builtin",
            "configuration":{
               "rules":[
                  {
                     "regex":"/",
                     "url":"http://my_staging_environment"
                  }
               ]
            }
         }
      ]
   }
}

Content Caching ポリシーにより、カスタムの条件に基づいてキャシングを有効および無効にすることができます。アップストリームレスポンスをポリシーに使用することができないクライアントリクエストにのみ、これらの条件を適用することができます。

Content Caching ポリシーがポリシーチェーンにある場合に、APIcast は要求をアップストリームに送信する前に HEAD 要求を GET 要求に変換します。この変換を希望しない場合は、ポリシーチェーンに Content Caching ポリシーを追加しないでください。

cache-control ヘッダーが送付される場合は、APIcast が設定するタイムアウトに優先します。

以下の設定例の場合、メソッドが GET の場合にレスポンスがキャッシュされます。

{
  "name": "apicast.policy.content_caching",
  "version": "builtin",
  "configuration": {
    "rules": [
      {
        "cache": true,
        "header": "X-Cache-Status-POLICY",
        "condition": {
          "combine_op": "and",
          "operations": [
            {
              "left": "{{method}}",
              "left_type": "liquid",
              "op": "==",
              "right": "GET"
            }
          ]
        }
      }
    ]
  }
}

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

CORS Request Handling ポリシーにより、指定されていない 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",
   "max_age" : 200
  }
}

ポリシーの設定方法に関する情報は、3scale 管理ポータルでのポリシーチェーンの変更を参照してください。

Custom Metrics ポリシーにより、アップストリーム API によって送信されるレスポンスの後にメトリクスを追加することができます。このポリシーの主なユースケースは、レスポンスコードのステータス、ヘッダー、またはさまざまな NGINX 変数に基づいてメトリクスを追加する場合です。

{
  "name": "apicast.policy.custom_metrics",
  "configuration": {
    "rules": [
      {
        "metric": "error",
        "increment": "{{ resp.headers['increment'] }}",
        "condition": {
          "operations": [
            {
              "right": "{{status}}",
              "right_type": "liquid",
              "left": "400",
              "op": "=="
            }
          ],
          "combine_op": "and"
        }
      }
    ]
  }
}

このポリシーは、アップストリーム API が 200 のステータスを返すと、status_code 情報により hits メトリックのカウントを増やします。

{
  "name": "apicast.policy.custom_metrics",
  "configuration": {
    "rules": [
      {
        "metric": "hits_{{status}}",
        "increment": "1",
        "condition": {
          "operations": [
            {
              "right": "{{status}}",
              "right_type": "liquid",
              "left": "200",
              "op": "=="
            }
          ],
          "combine_op": "and"
        }
      }
    ]
  }
}

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

設定プロパティー

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

{
  "name": "echo",
  "version": "builtin",
  "configuration": {
    "status": 404,
    "exit": "request"
  }
}

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

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

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

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

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

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

{
  "key": { "name": "{{ jwt.sub }}", "name_type": "liquid" },
  "count": 10,
  "window": 60
}

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

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

"condition": {
  "combine_op": "and",
  "operations": [
    {
      "op": "==",
      "right": "GET",
      "left_type": "liquid",
      "left": "{{ http_method }}",
      "right_type": "plain"
    }
  ]
}

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

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

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

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

{
  "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}}"
      }
    ]
  }
}

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

API プロバイダーは、HTTP Status Code Overwrite ポリシーを API プロダクトに追加できます。このポリシーにより、アップストリームのレスポンスコードを、指定したレスポンスコードに変更できます。3scale は、HTTP Status Code Overwrite ポリシーをアップストリームサービスから送信されたレスポンスコードに適用します。つまり、3scale が公開する API が状況に合わないコードを返す場合には、そのコードをアプリケーションに意味のあるレスポンスコードに変更するために、HTTP Status Code Overwrite ポリシーを設定することができます。

ポリシーチェーンでは、変更するレスポンスコードを生成するポリシーが HTTP Status Code Overwrite ポリシーの前にある必要があります。変更するステータスコードを生成するポリシーがない場合、HTTP Status Code Overwrite ポリシーのポリシーチェーンでの位置は重要ではありません。

管理ポータルで、HTTP Status Code Overwrite ポリシーをプロダクトのポリシーチェーンに追加します。ポリシーチェーンでポリシーをクリックし、変更するアップストリームレスポンスコードと、代わりに返したいレスポンスコードを指定します。上書きする追加のアップストリームレスポンスコードごとに正符号をクリックします。たとえば、HTTP Status Code Overwrite ポリシーを使用して、アップストリームの 201Created レスポンスコードを 200OK レスポンスコードに変更できます。

変更するレスポンスコードのもう 1 つの例は、コンテンツ制限を超える場合のレスポンスです。アップストリームが 413 payload too large を返す場合に、414 request-URI too long のレスポンスコードであれば役立ちます。

管理ポータルで HTTP Status Code Overwrite ポリシーを追加する代わりに、ポリシーチェーン設定ファイルと共に 3scale API を使用できます。

{
  "name": "statuscode_overwrite",
  "version": "builtin",
  "configuration": {
    "http_statuses": [
      {
        "upstream": 200,
        "apicast": 201
      },
      {
        "upstream": 413,
        "apicast": 414
      }
    ]
  }
}

HTTP2 エンドポイントポリシーは、リクエストと APIcast を送信するコンシューマーアプリケーション間の HTTP/2 プロトコルとリモートプロシージャコール (gRPC) 接続を有効にします。HTTP2 エンドポイントポリシーがプロダクトのポリシーチェーンにある場合、API キャストにリクエストを行うコンシューマーアプリケーションからアップストリームサービスへの通信フロー全体が HTTP/2 プロトコルおよび gRPC を使用することができます。

HTTP2 エンドポイントポリシーがポリシーチェーンにある場合:

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

設定プロパティー

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

{
  "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"
  }
}

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

JWT Claim Check ポリシーを使用すると、JSON Web Token (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"
          }
      ]
  }
}

このポリシーは 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",
        ...
      }
      ...
    }

Logging ポリシーには 2 つの目的があります。

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

また、Logging ポリシー機能に関する補足情報を以下に示します。

local cjson = require('cjson')
local PolicyChain = require('apicast.policy_chain')
local policy_chain = context.policy_chain

local logging_policy_config = cjson.decode([[
{
  "enable_access_logs": false,
  "custom_logging": "\"{{request}}\" to service {{service.id}} and {{service.name}}"
}
]])

policy_chain:insert( PolicyChain.load_policy('logging', 'builtin', logging_policy_config), 1)

return {
  policy_chain = policy_chain,
  port = { metrics = 9421 },
}

docker run --name apicast --rm -p 8080:8080 \
    -v $(pwd):/config \
    -e APICAST_ENVIRONMENT=/config/custom_env.lua \
    -e THREESCALE_PORTAL_ENDPOINT=https://ACCESS_TOKEN@ADMIN_PORTAL_DOMAIN \
    quay.io/3scale/apicast:master

{
  "name": "apicast.policy.logging",
  "configuration": {
    "enable_access_logs": false
  }
}

{
  "name": "apicast.policy.logging",
  "configuration": {
    "enable_access_logs": false,
    "custom_logging": "[{{time_local}}] {{host}}:{{server_port}} {{remote_addr}}:{{remote_port}} \"{{request}}\" {{status}} {{body_bytes_sent}} ({{request_time}}) {{post_action_impact}}",
  }
}

{
  "name": "apicast.policy.logging",
  "configuration": {
    "enable_access_logs": false,
    "custom_logging": "\"{{request}}\" to service {{service.id}} and {{service.serializable.name}}",
  }
}

{
  "name": "apicast.policy.logging",
  "configuration": {
    "enable_access_logs": false,
    "enable_json_logs": true,
    "json_object_config": [
      {
        "key": "host",
        "value": "{{host}}",
        "value_type": "liquid"
      },
      {
        "key": "time",
        "value": "{{time_local}}",
        "value_type": "liquid"
      },
      {
        "key": "custom",
        "value": "custom_method",
        "value_type": "plain"
      }
    ]
  }
}

{
  "name": "apicast.policy.logging",
  "configuration": {
    "enable_access_logs": false,
    "custom_logging": "\"{{request}}\" to service {{service.id}} and {{service.name}}",
    "condition": {
      "operations": [
        {"op": "==", "match": "{{status}}", "match_type": "liquid", "value": "200"}
      ],
      "combine_op": "and"
    }
  }
}

{
  "name": "apicast.policy.logging",
  "configuration": {
    "enable_access_logs": false,
    "custom_logging": "\"{{request}}\" to service {{service.id}} and {{service.name}}",
    "condition": {
      "operations": [
        {"op": "==", "match": "{{status}}", "match_type": "liquid", "value": "200"},
        {"op": "==", "match": "{{status}}", "match_type": "liquid", "value": "500"}
      ],
      "combine_op": "or"
    }
  }
}

Maintenance Mode ポリシーを使用すると、指定したステータスコードおよびメッセージと共に受信したリクエストを拒否することができます。このポリシーは、メンテナンス期間または API を一時的にブロックする場合に役立ちます。

設定プロパティー

設定可能なプロパティーおよびデフォルト値を、以下のリストに示します。

{
  "policy_chain": [
    {"name": "maintenance-mode", "version": "1.0.0",
    "configuration": {"message": "Be back soon..", "status": 503} },
  ]
}

{
    "name": "maintenance_mode",
    "version": "builtin",
    "configuration": {
        "message_content_type": "text/plain; charset=utf-8",
        "message": "Echo API /test is currently Unavailable",
        "condition": {
            "combine_op": "and",
            "operations": [
                {
                    "left_type": "liquid",
                    "right_type": "plain",
                    "op": "==",
                    "left": "{{ original_request.path }}",
                    "right": "/test"
                }
            ]
        },
        "status": 503
    }
}

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

NGINX は一部のリクエストヘッダーを自動的にチェックし、これらのヘッダーを検証できない場合にリクエストを拒否します。たとえば、NGINX は NGINX が検証できない If-Match ヘッダーのあるリクエストを拒否します。NGINX が特定のヘッダーの検証を省略するようにする場合は、NGINX Filter ポリシーを追加します。

NGINX Filter ポリシーを追加する場合、NGINX が検証をスキップするリクエストヘッダーを 1 つ以上指定します。指定するヘッダーごとに、ヘッダーをリクエストに残すかどうかを指定します。たとえば、以下の JSON コードは NGINX Filter ポリシーを追加して、If-Match ヘッダーの検証をスキップするが、アップストリームサーバーに転送されるリクエストに If-Match ヘッダーを保持するように設定することができます。

{ "name": "apicast.policy.nginx_filters",
  "configuration": {
    "headers": [
      {"name": "If-Match", "append": true}
    ]
  }
}

以下の例でも If-Match ヘッダーの検証をスキップしますが、このコードは、リクエストをアップストリームサーバーに送信する前に If-Match ヘッダーを削除するように NGINX に指示します。

{ "name": "apicast.policy.nginx_filters",
  "configuration": {
    "headers": [
      {"name": "If-Match", "append": false}
    ]
  }
}

アップストリームサーバーに送信されるリクエストに指定のヘッダーを追加するかどうかに関係なく、NGINX が指定したヘッダーを検証できない場合に NGINX 412 応答コードを回避します。

このポリシーは、全 API コールに対して OAuth 2.0 相互 TLS クライアント認証を実行します。

OAuth 2.0 Mutual TLS Client Authentication ポリシーの JSON の例を以下に示します。

{
  "$schema": "http://apicast.io/policy-v1/schema#manifest#",
  "name": "OAuth 2.0 Mutual TLS Client Authentication",
  "summary": "Configure OAuth 2.0 Mutual TLS Client Authentication.",
  "description": ["This policy executes OAuth 2.0 Mutual TLS Client Authentication ",
    "(https://tools.ietf.org/html/draft-ietf-oauth-mtls-12) for every API call."
  ],
  "version": "builtin",
  "configuration": {
    "type": "object",
    "properties": { }
  }
}

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

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

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

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

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

API プロバイダーは、On Fail ポリシーを API プロダクトに追加できます。On Fail ポリシーがポリシーチェーンにあり、特定の API コンシューマーリクエストに対してポリシーの実行に失敗すると、APIcast は以下の処理を行います。

On Fail ポリシーは、不適切な設定やカスタムポリシーのコンプライアンス違反のコードが原因で、APIcast がポリシーを処理できない場合に役立ちます。ポリシーチェーンに On Fail ポリシーがないと、APIcast はポリシーを適用できないポリシーをスキップし、チェーン内の他のポリシーを処理し、リクエストをアップストリーム API に送信します。ポリシーチェーンに On Fail ポリシーがあると、APIcast はリクエストを拒否します。

ポリシーチェーンでは、On Fail ポリシーを任意の場所に配置できます。

管理ポータルで、On Fail ポリシーをプロダクトのポリシーチェーンに追加します。ポリシーチェーンでポリシーをクリックし、On Fail ポリシーを適用する際に APIcast が返すステータスコードを指定します。たとえば、クライアントからの不適切なリクエストを示す 400 を指定できます。

Proxy Service ポリシーを使用して、定義したプロキシーを使用して 3scale のトラフィックを送信する一般的な HTTP プロキシー を定義することができます。この場合、プロキシーサービスはリバース HTTP プロキシーとして機能し、APIcast は HTTP プロキシーにトラフィックを送信し、プロキシーがそのトラフィックを API バックエンドに送信します。

トラフィックフローの例を以下に示します。

3scale バックエンドに送信された APIcast トラフィックは、すべてプロキシーを使用しません。このポリシーは、プロキシーおよび APIcast と API バックエンド間の通信にのみ適用されます。

すべてのトラフィックをプロキシー経由で送信するには、HTTP_PROXY 環境変数を使用する必要があります。

"policy_chain": [
    {
      "name": "apicast.policy.apicast"
    },
    {
      "name": "apicast.policy.http_proxy",
      "configuration": {
          "all_proxy": "http://192.168.15.103:8888/",
          "https_proxy": "https://192.168.15.103:8888/",
          "http_proxy": "https://192.168.15.103:8888/"
      }
    }
]

http_proxy または https_proxy が定義されていない場合は、all_proxy の値が使用されます。

アプリケーションが流量制御の設定されたアプリケーションプランにサブスクライブする際に、Rate Limit Headers ポリシーはレスポンスメッセージに RateLimit ヘッダーを追加します。これらのヘッダーは、設定されたリクエストクォータ制限、ならびに現在の時間枠での残りのリクエストクォータおよび秒数に関する有用な情報を提供します。

プロダクトのポリシーチェーンで、Rate Limit Headers ポリシーを追加する場合、3scale APIcast ポリシーの前に設定する必要があります。3scale APIcast ポリシーが Rate Limit Headers ポリシーの前にあると、Rate Limit Headers ポリシーは機能しません。

デフォルトでは、Rate Limit Headers ポリシーが設定されていない場合やアプリケーションプランに流量制御が設定されていない場合、レスポンスメッセージには流量制御に関するヘッダーがありません。

API プロバイダーは、Response/Request Content Limits ポリシーを API プロダクトに追加できます。このポリシーにより、アップストリーム API へのリクエストのサイズやアップストリーム API からのレスポンスのサイズを制限できます。このポリシーがない場合、リクエスト/レスポンスのサイズは無制限になります。

このポリシーは、以下の項目のオーバーロードを防ぐのに役立ちます。

3scale が Response/Request Content Limits ポリシーを適用するには、リクエストまたはレスポンスに content-length ヘッダーが必要です。

管理ポータルで Response/Request Content Limits ポリシーをプロダクトに追加したら、それをクリックして制限をバイト単位で指定します。リクエストの制限またはレスポンスの制限のいずれか、またはその両方を指定することができます。デフォルト値は 0 で、サイズが無制限であることを意味します。

または、以下のようにポリシーチェーン設定ファイルを更新して、このポリシーを追加することができます。

{
  "name": "apicast.policy.limits",
  "configuration":
  {
    "request": 100,
    "response": 100
  }
}

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

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
      }
    }
  }
}

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

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

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

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

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

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

Liquid Context Debug
JWT Claim Check
Routing
3scale APIcast

Liquid Context Debug
Routing
3scale APIcast
JWT Claim Check

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

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

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

以下の設定では、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"
              }
            ]
          }
        }
      ]
    }
  }

以下の設定では、リクエストのパスが /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"
              }
            ]
          }
        }
      ]
    }
  }

以下の設定では、リクエストのパスが /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"
              }
            ]
          }
        }
      ]
    }
  }

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

 {
    "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"
              }
            ]
          }
        }
      ]
    }
  }

以下の設定では、パスが /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": []
          }
        }
      ]
    }
  }

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

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

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

 {
    "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"
              }
            ]
          }
        }
      ]
    }
  }

以下の設定では、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": "/"
              }
            ]
          }
        }
      ]
    }
  }

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

設定プロパティー

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

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

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

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

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

3scale システムにアクセスできること。すべてのデプロイメントが完了していること。

付加手順:

変更を保存するには、Update Policy Chain をクリックします。

プレースホルダーの [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

変更を保存するには、Update Policy Chain をクリックします。

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

本セクションでは、Transport Layer Security (TLS) Termination ポリシーに関して、その概要、設定、検証、およびポリシーからのファイル削除について説明します。

TLS Termination ポリシーを使用すると、全 API 用の単一の証明書を使用せずにそれぞれの API ごとに TLS リクエストを終端するように、APIcast を設定することができます。APIcast は、クライアントへの接続を確立する前に設定をプルします。このようにして、APIcast はポリシーからの証明書を使用して TLS を終端させます。このポリシーは、以下のソースと共に機能します。

デフォルトでは、このポリシーはポリシーチェーンで有効になっていません。

以下の手順に従います。

付加手順:

変更を保存するには、Update Policy Chain をクリックします。

以下のコマンドを使用して、ポリシーが機能するかどうかをコマンドラインでテストすることができます。

curl “${public_URL}:${port}/?user_key=${user_key}" --cacert ${path_to_certificate}/ca.pem -v

ここで、

証明書を削除するには、以下の手順を実施します。

変更を保存するには、Update Policy Chain をクリックします。

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

例:

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

ポリシーチェーンの参照

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

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

      }
    ]
  }
}

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

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

Upstream Connection ポリシーを設定するには、以下の条件を満たす必要があります。

以下の手順に従います。

変更を保存するには、Update Policy Chain をクリックします。

Upstream Mutual TLS ポリシーを使用すると、設定で指定した証明書に基づいて、APIcast とアップストリーム API との間で相互 TLS 接続を確立して検証することができます。

verify フィールドを有効にすると、ポリシーはアップストリーム API からのサーバー証明書も検証します。ca_certificates には、APIcast がサーバーの検証に使用する -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- を含めた Privacy Enhanced Mail (PEM) 形式の証明書が含まれます。

ポリシーチェーンで Upstream Mutual TLS を設定するには、3scale システムにアクセスできる必要があります。

変更をプロモートするには、以下の手順を実施します。

v# は、プロモートされる設定のバージョン番号を表します。

{
  "name": "apicast.policy.upstream_mtls",
  "configuration": {
      "certificate": "/secrets/client.cer",
      "certificate_type": "path",
      "certificate_key": "/secrets/client.key",
      "certificate_key_type": "path"
  }
}

{
  "name": "apicast.policy.upstream_mtls",
  "configuration": {
    "certificate_type": "embedded",
    "certificate_key_type": "embedded",
    "certificate": "data:application/pkix-cert;name=client.cer;base64,XXXXXXXXXXX",
    "certificate_key": "data:application/x-iwork-keynote-sffkey;name=client.key;base64,XXXXXXXX"
  }
}

Upstream Mutual TLS に関する追加のフィールド、ca_certificates、および verify についての詳細は、ポリシー設定スキーマ を参照してください。

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

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

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

{
  "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"
      }
    ]
  }

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

https://api.example.com/api/v1/products/123/details?user_key=abc123secret&pusharg=first&setarg=original

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

https://api-backend.example.com/internal/products/123/details?pusharg=first&pusharg=pushvalue&setarg=setvalue

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

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

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

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

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

元の 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"
      }
    ]
  }
}

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

https://api.example.com/api/v1/products/123/details?user_key=abc123secret

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

https://api-backend.example.com/internal/products/details?user_key=abc123secret&extraparam=anyvalue&id=123

Websocket ポリシーは、アップストリーム API への WebSocket プロトコル接続を有効にします。WebSocket プロトコルを有効にする予定の場合は、以下を考慮してください。

WebSocket 接続を有効にするアップストリーム API については、そのバックエンドを http[s] または ws[s] として定義できます。

Websocket ポリシーをポリシーチェーンに追加する場合は、3scale APIcast ポリシーの前に Websocket ポリシーが設定されていることを確認してください。