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 Auth Caching」
- 「3scale Batcher」
- 「3scale Referrer」
- 「Anonymous Access」
- 「Conditional ポリシー」
- 「CORS Request Handling」
- 「Echo」
- 「Edge Limiting」
- 「Header Modification」
- 「IP Check」
- 「JWT Claim Check」
- 「Liquid Context Debug」
- 「Logging」
- 「Maintenance Mode」
- 「OAuth 2.0 Mutual TLS Client Authentication」
「OAuth 2.0 Token Introspection」
注記: Prometheus についての詳細は、「9章Prometheus への 3scale APIcast メトリクスの公開」を参照してください。
- 「Proxy Service」
- 「Retry」
- 「RH-SSO/Keycloak Role Check」
- 「Routing」
- 「SOAP」
- 「TLS Client Certificate Validation」
- 「TLS Termination」
- 「Upstream」
- 「Upstream Connection」
- 「Upstream Mutual TLS」
- 「URL Rewriting」
- 「URL Rewriting with Captures」
3scale の標準ポリシーを 有効化および設定する ことができます。
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」モードでは、キャッシュが無効になります。ポリシーを有効にしたままキャッシュの使用を止める場合に、このモードが役立ちます。
設定プロパティー
| プロパティー | 説明 | 値 | 必須/任意 |
|---|---|---|---|
| caching_type |
| データタイプ: 列挙文字列 [resilient, strict, allow, none] | 必須 |
ポリシーオブジェクトの例
ポリシーの設定方法に関する情報は、本書の「3scale でのポリシーチェーンの作成」セクションを参照してください。
4.1.2. 3scale Batcher
標準の APIcast 承認メカニズムでは、APIcast が API リクエストを受け取るたびに、3scale バックエンド (Service Management API) に対して 1 回呼び出しが行われます。3scale Batcher ポリシーは、この標準メカニズムの代替手段を提供します。
3scale Batcher ポリシーを使用すると、承認ステータスがキャッシュされ使用状況レポートがバッチ処理されます。これにより、3scale バックエンドへのリクエスト数が大幅に削減されます。3scale Batcher ポリシーにより、レイテンシーを短縮しスループットを増やすことで、API キャストのパフォーマンスを改善できます。
3scale Batcher ポリシーが有効な場合には、APIcast は以下のフローを使用して承認を行います。
それぞれのリクエストにおいて、ポリシーはクレデンシャルがキャッシュされているかどうかを確認します。
- クレデンシャルがキャッシュされている場合には、ポリシーは 3scale バックエンドに呼び出しを行う代わりに、キャッシュされた承認ステータスを使用します。
- クレデンシャルがキャッシュされていない場合には、ポリシーはバックエンドに呼び出しを行い、残存期間 (TTL) を設定して承認ステータスをキャッシュします。
- リクエストに対応する使用状況を直ちに 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. 3scale Referrer
3scale Referrer ポリシーを使用すると、参照元フィルター 機能が有効になります。サービスポリシーチェーンでこのポリシーが有効な場合には、APIcast は上流への AuthRep コールとして 3scale Referrer ポリシーの値をService Management API に送信します。3scale Referrer ポリシーの値は、呼び出しの referrer パラメーターで送信されます。
参照元フィルター機能の仕組みの詳細については、「認証パターン」の「参照元フィルター」セクションを参照してください。
4.1.4. 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 ポリシー
4.1.5. Conditional ポリシー
Conditional ポリシーは、ポリシーチェーンが含まれるため、他の APIcast ポリシーとは異なります。このポリシーは、access、rewrite、log など、各 nginx フェーズ で評価される条件を定義します。条件が true の場合には、Conditional ポリシーは、チェーンに含まれるポリシーごとにフェーズを実行します。
APIcast の Conditional ポリシーはテクノロジープレビュー機能です。テクノロジープレビューの機能は、Red Hat の実稼働環境のサービスレベルアグリーメント (SLA) の対象外であり、機能的に完全ではないことがあります。Red Hat は実稼働環境でこれらを使用することを推奨していません。これらの機能は、近々発表予定の製品機能をリリースに先駆けてご提供することにより、開発プロセスの中でお客様に機能性のテストとフィードバックをしていただくことを目的としています。Red Hat のテクノロジープレビュー機能のサポート範囲に関する詳細は、「テクノロジプレビュー機能のサポート範囲」を参照してください。
以下の例では、Conditional ポリシーが the request method is POST の条件を定義していると仮定しています。
今回の例では、リクエストが POST の場合に、各フェーズの実行順序は以下のようになります。
- APIcast
- Caching
- Headers
- URL Rewriting
- Upstream
リクエストが POST でない場合には、各フェーズの実行順序は以下のようになります。
- APIcast
- Caching
- Upstream
4.1.5.1. 条件
Conditional ポリシーチェーンでポリシーを実行するかどうかを判断する条件は、JSON を使用して表現でき、Liquid テンプレートを使用します。
以下の例では、リクエストパスが /example_path かどうかを確認します。
左側のオペランドと右のオペランドの両方を Liquid または plain 文字列として評価できます。デフォルトは、Plain 文字列です。
and または or を使用した操作を組み合わせることができます。この設定では、以前の例の内容に加え、Backend ヘッダーの値を確認します。
詳細は、policy config schema を参照してください。
4.1.5.1.1. Liquid でサポートされている変数
- uri
- host
- remote_addr
- headers['Some-Header']
変数の更新リストは ngx_variable.lua を参照してください。
以下の例では、リクエストの Backend ヘッダーが staging の場合に、アップストリームポリシーを実行します。
4.1.6. CORS Request Handling
Cross Origin Resource Sharing (CORS) Request Handling ポリシーを使用すると、以下の項目を指定することができるので CORS の動作の制御が可能です。
- 許可されるヘッダー
- 許可されるメソッド
- 許可されるクレデンシャル
- 許可されるオリジンヘッダー
CORS Request Handling ポリシーにより、指定されていない CORS リクエストはすべてブロックされます。
APIcast ポリシーおよび CORS Request Handling ポリシーをポリシーチェーンで併用する場合には、APIcast ポリシーの前に CORS Request Handling ポリシーを設定する必要があります。
設定プロパティー
| プロパティー | 説明 | 値 | 必須/任意 |
|---|---|---|---|
| allow_headers |
| データタイプ: 文字列の配列 (CORS ヘッダーでなければなりません) | 任意 |
| allow_methods |
| データタイプ: 列挙文字列の配列 [GET, HEAD, POST, PUT, DELETE, PATCH, OPTIONS, TRACE, CONNECT] | 任意 |
| allow_origin |
| データタイプ: 文字列 | 任意 |
| allow_credentials |
| データタイプ: ブール値 | 任意 |
ポリシーオブジェクトの例
ポリシーの設定方法に関する情報は、本書の「3scale でのポリシーチェーンの作成」セクションを参照してください。
4.1.7. Echo
Echo ポリシーは、受信したリクエストを出力してクライアントに返します。また、オプションで任意の HTTP ステータスコードを返します。
設定プロパティー
| プロパティー | 説明 | 値 | 必須/任意 |
|---|---|---|---|
| status | Echo ポリシーがクライアントに返す HTTP ステータスコード | データタイプ: 整数 | 任意 |
| exit |
Echo ポリシーが使用する終了モードを指定します。 | データタイプ: 列挙文字列 [request, set] | 必須 |
ポリシーオブジェクトの例
ポリシーの設定方法に関する情報は、本書の「3scale でのポリシーチェーンの作成」セクションを参照してください。
4.1.8. Edge Limiting
Edge Limiting ポリシーの目的は、バックエンド API に送信されるトラフィックに対する柔軟な流量制御を提供することで、このポリシーをデフォルトの 3scale 承認メカニズムと共に使用することができます。このポリシーでサポートされるユースケースの例を以下に示します。
-
エンドユーザーの流量制御: リクエストの認証ヘッダーで渡される JWT トークンの「sub」(subject) クレームの値による流量制御 (
{{ jwt.sub }}として設定します)。 - 1 秒あたりのリクエスト数 (RPS) 流量制御
- サービスごとのグローバル流量制御: アプリケーションごとではなく、サービスごとに流量制御を適用します。
- 同時接続上限: 許容される同時接続の数を設定します。
4.1.8.1. 制限のタイプ
このポリシーでは、lua-resty-limit-traffic ライブラリーにより提供される以下の制限タイプがサポートされます。
-
leaky_bucket_limiters: 平均リクエスト数および最大バーストサイズをベースにした「leaky_bucket」アルゴリズムに基づきます。 -
fixed_window_limiters: 特定の期間 (最後の X 秒) に基づきます。 -
connection_limiters: 同時接続の数に基づきます。
すべての制限をサービスごとまたはグローバルに適用することができます。
4.1.8.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は、ウィンドウで定義された秒数あたりに実行できるリクエスト数を定義します。 connection_limiters:conn、burst、およびdelay-
conn: 許容される同時接続の最大数を定義します。burstで定義される 1 秒あたりの接続数までこの値を超えることができます。 -
delay: 制限を超える接続を遅延させる秒数です。
-
例
service_A に対するリクエストを毎分 10 回許可します。
{ "key": { "name": "service_A" }, "count": 10, "window": 60 }{ "key": { "name": "service_A" }, "count": 10, "window": 60 }Copy to Clipboard Copied! Toggle word wrap Toggle overflow burst および delay をそれぞれ 10 および 1 に設定して、100 の接続を許可します。
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
サービスごとにさまざまな制限を定義することができます。複数の制限を定義した場合には、少なくとも 1 つの制限に達すると、リクエストは拒否または遅延されます。
4.1.8.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
}
{
"key": { "name": "{{ jwt.sub }}", "name_type": "liquid" },
"count": 10,
"window": 60
}Liquid のサポートに関する詳細な情報は、「ポリシーでの変数およびフィルターの使用」を参照してください。
4.1.8.4. 条件の適用
以下のプロパティーで condition を定義します。
-
combine_op: 演算の一覧に適用されるブール演算子です。orおよびandの値がサポートされます。 operations: 評価する必要がある条件のリストです。各演算は、以下のプロパティーを持つオブジェクトにより表されます。-
left: 演算の左側部分 -
left_type:leftプロパティーがどのように評価されるか (plain または liquid)。 -
right: 演算の右側部分 -
right_type:rightプロパティーがどのように評価されるか (plain または liquid)。 -
op: 左右の部分の間に適用される演算子。==(等しい) および!=(等しくない) の 2 つの値がサポートされます。
-
例:
4.1.8.5. ストアの設定
デフォルトでは、Edge Limiting ポリシーは流量制御カウンターに OpenResty 共有ディクショナリーを使用します。ただし、共有ディクショナリーの代わりに外部の Redis サーバーを使用することができます。この設定は、複数の APIcast インスタンスが使用されている場合に役立ちます。Redis サーバーは、redis_url パラメーターを使用して設定することができます。
4.1.8.6. エラー処理
リミッターでは、エラーの処理方法を設定するために以下のパラメーターがサポートされます。
limits_exceeded_error: 設定した上限を超えた際にクライアントに返されるエラーステータスコードおよびメッセージを設定することができます。以下のパラメーターを設定する必要があります。-
status_code: 上限を超えた際のリクエストのステータスコード。デフォルトは429です。 error_handling: 以下のオプションを使用して、エラーの処理方法を指定します。-
exit: リクエストの処理を中止し、エラーメッセージを返します。 -
log: リクエストの処理を完了し、出力ログを返します。
-
-
configuration_error: 設定が正しくない場合にクライアントに返されるエラーステータスコードおよびメッセージを設定することができます。以下のパラメーターを設定する必要があります。-
status_code: 設定に問題がある場合のステータスコード。デフォルトは500です。 error_handling: 以下のオプションを使用して、エラーの処理方法を指定します。-
exit: リクエストの処理を中止し、エラーメッセージを返します。 -
log: リクエストの処理を完了し、出力ログを返します。
-
-
4.1.9. 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 }}の形式にする必要があります。削除する場合には不要です。
ポリシーオブジェクトの例
ポリシーの設定方法に関する情報は、本書の「3scale でのポリシーチェーンの作成」セクションを参照してください。
4.1.10. IP Check
IP Check ポリシーは、IP のリストに基づいてリクエストを拒否または許可するために使用します。
設定プロパティー
| プロパティー | 説明 | データタイプ | 必須/任意 |
|---|---|---|---|
| check_type |
|
文字列 ( | 必須 |
| ips |
| 文字列の配列 (有効な IP アドレスでなければなりません) | 必須 |
| error_msg |
| 文字列 | 任意 |
| client_ip_sources |
|
文字列の配列。有効なオプションは、 | 任意 |
ポリシーオブジェクトの例
ポリシーの設定方法に関する情報は、本書の「3scale でのポリシーチェーンの作成」セクションを参照してください。
4.1.11. JWT Claim Check
JWT Claim Check ポリシーを使用すると、JSON Web Token (JWT) クレームに基づきリソースターゲットおよびメソッドをブロックする、新たなルールを定義することができます。
4.1.11.1. JWT Claim Check ポリシーの概要
JWT クレームの値に基づいてルーティングするためには、ポリシーチェーンには、ポリシーが共有するコンテキストで JWT を検証してクレームを格納するポリシーが必要です。
JWT Claim Check ポリシーがリソースおよびメソッドをブロックしている場合には、ポリシーは JWT 操作も検証します。一方、メソッドおよびリソースがマッチしない場合には、リクエストはバックエンド API に送信されます。
以下の GET リクエストの例では、JWT には管理者として role クレームが必要です。もしなければ、リクエストは拒否されます。一方、GET 以外のリクエストは JWT 操作を検証しないため、POST リソースは JWT の制約なしに許可されます。
4.1.11.2. ポリシーチェーンへの JWT Claim Check ポリシーの設定
ポリシーチェーンで JWT Claim Check ポリシーを設定するには、以下を行います。
前提条件:
- 3scale システムにアクセスできること。
- すべてのデプロイメントが完了していること。
4.1.11.2.1. ポリシーの設定
- 「標準ポリシーの有効化」に記載の手順に従って JWT Claim Check を選択し、API に JWT Claim Check ポリシーを追加します。
- JWT Claim Check のリンクをクリックします。
- Enabled のチェックボックスを選択し、ポリシーを有効にします。
-
ルールを追加するには、プラス (
+) アイコンをクリックします。 - resource_type を指定します。
- 演算子を選択します。
- ルールによって制御される resource を指定します。
-
許可されるメソッドを追加するには、プラス (
+) アイコンをクリックします。 - トラフィックがブロックされた時にユーザーに表示するエラーメッセージを入力します。
API への JWT Claim Check ポリシーの設定が完了したら、Update Policy をクリックします。
-
該当するセクションのプラス (
+) アイコンをクリックして、さらにリソースタイプおよび許可されるメソッドを追加することができます。
-
該当するセクションのプラス (
- Update Policy Chain をクリックして変更を保存します。
4.1.12. Liquid Context Debug
Liquid Context Debug ポリシーの想定は、開発環境でのデバッグ用途のみで、実稼働環境での使用は意図されていません。
このポリシーは JSON を使用して API リクエストに応答します。コンテキストで利用可能なオブジェクトおよび値を含み、Liquid テンプレートの評価に使用することができます。3scale APIcast または Upstream ポリシーと組み合わせる場合には、正常な動作のためにポリシーチェーンではこれらのポリシーの前に Liquid Context Debug ポリシーを設定する必要があります。循環参照を避けるために、ポリシーには重複するオブジェクトは 1 回だけ含め、それをスタブ値で置き換えます。
このポリシーが有効な時に APIcast が返す値の例を以下に示します。
4.1.13. Logging
Logging ポリシーには 2 つの目的があります。
- アクセスログの出力を有効および無効にする。
- それぞれのサービスごとにカスタムアクセスログのフォーマットを作成し、カスタムアクセスログ書き込みの条件を設定できるようにする。
Logging ポリシーとアクセスログの場所のグローバル設定を組み合わせることができます。APIcast アクセスログの場所を設定するには、APICAST_ACCESS_LOG_FILE 環境変数を設定します。デフォルトでは、この変数は標準出力デバイスの /dev/stdout に設定されています。グローバル APIcast パラメーターに関する詳細な情報は、「???」を参照してください。
また、Logging ポリシー機能に関する補足情報を以下に示します。
-
このポリシーは、
enable_access_logs設定パラメーターしかサポートしません。 -
アクセスログを有効にするには、
enable_access_logsパラメーターを選択するか、Logging ポリシーを無効にします。 API のアクセスログを無効にするには、以下の手順を実施します。
- ポリシーを有効にします。
-
enable_access_logsパラメーターの選択を解除します。 -
Submitボタンをクリックします。
- デフォルトでは、このポリシーはポリシーチェーンで有効になっていません。
4.1.13.1. すべての API に対するグローバル設定
Logging オプションは、API でログが正しくフォーマットされない問題を避けるのに役立ちます。カスタム APIcast 環境変数を設定して、すべての API に Logging ポリシーを実装することができます。すべてのサービスに読み込まれるポリシーの例を以下に示します (custom_env.lua)。
この特定の環境を指定して APIcast を実行するには、以下のコマンドを実行します。
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
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考慮すべき Docker コマンドの重要な概念を以下に示します。
-
有効な Lua ファイルをコンテナーに共有する必要がある (
-v $(pwd):/config)。 -
APICAST_ENVIRONMENT 変数を
/configディレクトリーに保存される Lua ファイルに設定する必要がある。
4.1.13.2. 例
本セクションでは、Logging ポリシーを使用した例について説明します。ここに示す例では、以下の条件を考慮しています。
-
custom_loggingまたはenable_json_logsプロパティーが有効な場合には、デフォルトのアクセスログは無効になる。 -
enable_json_logsが有効な場合には、custom_loggingフィールドは省略される。
アクセスログの無効化
カスタムアクセスログの有効化
サービスを識別した上でのカスタムアクセスログの有効化
JSON 形式でのアクセスログの設定
正常なリクエストのみに対するカスタムアクセスログの設定
レスポンスのステータスが 200 または 500 のいずれかにマッチする場合のアクセスログのカスタマイズ
4.1.13.3. カスタムロギングに関する補足情報
カスタムロギングでは、エクスポートした変数と共に Liquid テンプレートを使用することができます。この変数の例を以下に示します。
-
NGINX デフォルトディレクティブ変数: log_format。たとえば
{{remote_addr}}。 レスポンスおよびリクエストヘッダー:
-
{{req.headers.FOO}}: リクエストの FOO ヘッダーを取得する。 -
{{res.headers.FOO}}: レスポンスの FOO ヘッダーを取得する。
-
サービス情報 (例:
{{service.id}})、および以下のパラメーターにより提供されるすべてのサービスプロパティー:- THREESCALE_CONFIG_FILE
- THREESCALE_PORTAL_ENDPOINT
4.1.14. Maintenance Mode
Maintenance Mode ポリシーを使用すると、指定したステータスコードおよびメッセージと共に受信したリクエストを拒否することができます。このポリシーは、メンテナンス期間または API を一時的にブロックする場合に役立ちます。
設定プロパティー
設定可能なプロパティーおよびデフォルト値を、以下のリストに示します。
| プロパティー | 値 | デフォルト | 説明 |
|---|---|---|---|
| status | 整数 (オプション) | 503 | レスポンスコード |
| message | 文字列 (オプション) | 503 Service Unavailable - Maintenance | レスポンスのメッセージ |
Maintenance Mode ポリシーの例
ポリシーの設定方法に関する情報は、本書の「3scale でのポリシーチェーンの作成」セクションを参照してください。
4.1.15. OAuth 2.0 Mutual TLS Client Authentication
このポリシーは、全 API コールに対して OAuth 2.0 相互 TLS クライアント認証を実行します。
OAuth 2.0 Mutual TLS Client Authentication ポリシーの JSON の例を以下に示します。
4.1.16. 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 に設定された認証タイプ
client_id+client_secret: このオプションでは、APIcast がトークン情報を要求するのに使用する クライアント ID および クライアントシークレット と共に、異なるトークンイントロスペクションエンドポイントを指定することができます。このオプションを使用する場合には、以下の設定パラメーターを定義します。-
client_id: トークンイントロスペクションエンドポイント用のクライアント ID を設定します。 -
client_secret: トークンイントロスペクションエンドポイント用のクライアントシークレットを設定します。 -
introspection_url: イントロスペクションエンドポイントの URL を設定します。
-
例4.2 client_id+client_secret に設定された認証タイプ
auth_type フィールドの設定にかかわらず、APIcast は Basic 認証を使用してトークンイントロスペクションの呼び出しを承認します (Authorization: Basic <token> ヘッダー、ここで <token> は Base64 でエンコードされた <client_id>:<client_secret> 設定です)。
トークンイントロスペクションエンドポイントのレスポンスには、active 属性が含まれます。APIcast はこの属性の値を確認します。属性の値に応じて、APIcast は呼び出しを承認または拒否します。
-
true: 呼び出しを承認します -
false:Authentication Failedエラーと共に呼び出しを拒否します
このポリシーを使用すると、トークンのキャッシュを有効にして、同じ JWT トークンに対する呼び出しのたびにトークンイントロスペクションエンドポイントに呼び出しを行うのを避けることができます。Token Introspection ポリシーのトークンキャッシュを有効にするには、max_cached_tokens フィールドを 0 (機能は無効) から 10000 までの値に設定します。さらに、max_ttl_tokens フィールドで、トークンの残存期間 (TTL) の値を 1 から 3600 秒に設定することができます。
4.1.17. Proxy Service
Proxy Service ポリシーを使用すると、定義したプロキシーを使用してトラフィックを送信するように、HTTP proxy を定義できます。
以下は、トラフィックフローの例を示しています。
3scale バックエンドへの APIcast トラフィックはいずれもプロキシーを使用しないため、このポリシーは、サービスおよび、APIcast と API バックエンド間の通信にのみ適用されます。
Proxy Service ポリシーを指定してすべてのトラフィックを使用する場合は、HTTP_PROXY 環境変数を使用する必要があります。
4.1.17.1. 設定
以下の例は、ポリシー変更の設定を示しています。
http_proxy または https_proxy が定義されていない場合は、all_proxy が使用されます。
4.1.17.1.1. 注意事項
- Proxy Service ポリシーは、全負荷分散ポリシーを無効にし、トラフィックがプロキシーに送信されます。
-
このポリシーは、
HTTP_PROXY、HTTPS_PROXYまたはALL_PROXYパラメーターが定義されている場合には、これらのパラメーターの値を上書きします。 - プロキシー接続では、認証はサポートされません。
4.1.17.1.2. ユースケースの例
Proxy Service ポリシーは、より詳細なポリシーを適用し、Apache Camel を使用した変換ができるように設計されています。
プロジェクトの例
GitHub の camel-netty-proxy の例を参照してください。このプロジェクトは、API バックエンドが渡した応答ボディーをすべて大文字に変換する HTTP プロキシー です。
4.1.18. Retry
Retry ポリシーは、アップストリーム API へのリトライリクエストの回数を設定します。Retry ポリシーはサービスごとに設定されるため、ユーザーは必要な数のサービスに対してリトライを有効にすることができ、またそれぞれのサービスに異なるリトライ数を設定することもできます。
3scale 2.8 では、リトライするケースをポリシーから設定することはできません。この動作を制御する環境変数 APICAST_UPSTREAM_RETRY_CASES は、すべてのサービスにリトライリクエストを適用します。この点についての詳細は、「APICAST_UPSTREAM_RETRY_CASES」をご確認ください。
Retry ポリシー JSON の例を以下に示します。
4.1.19. 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>" ] }"realm_access": { "roles": [ "<realm_role_A>", "<realm_role_B>" ] }Copy to Clipboard Copied! Toggle word wrap Toggle overflow 実際のロールは、ポリシーで指定する必要があります。
"realm_roles": [ { "name": "<realm_role_A>" }, { "name": "<realm_role_B>" } ]"realm_roles": [ { "name": "<realm_role_A>" }, { "name": "<realm_role_B>" } ]Copy to Clipboard Copied! Toggle word wrap Toggle overflow realm_roles 配列の各オブジェクトでは、以下のプロパティーを使用することができます。
- name: ロールの名前を指定します。
- name_type: plain または liquid のどちらかを指定して、name がどのように評価されるかを定義します (resource_type の場合と同じように機能します)。
client_roles: クライアント namespace に特定のアクセスロールがあるかどうかを確認する場合に、client_roles を使用します (Red Hat Single Sign-On のクライアントロール に関するドキュメントを参照してください)。
クライアントロールは、JWT の resource_access クレームのセクションにあります。
Copy to Clipboard Copied! Toggle word wrap Toggle overflow ポリシーでクライアントロールを指定します。
Copy to Clipboard Copied! Toggle word wrap Toggle overflow client_roles 配列の各オブジェクトでは、以下のプロパティーを使用することができます。
- name: ロールの名前を指定します。
- name_type: plain または liquid のどちらかを指定して、name の値がどのように評価されるかを定義します (resource_type の場合と同じように機能します)。
- client: ロールのクライアントを指定します。定義しなければ、このポリシーはクライアントに aud クレームを使用します。
- client_type: plain または liquid のどちらかを指定して、client の値がどのように評価されるかを定義します (resource_type の場合と同じように機能します)。
4.1.20. Routing
Routing ポリシーを使用すると、リクエストをさまざまなターゲットエンドポイントにルーティングすることができます。ターゲットエンドポイントを定義すると、正規表現を使用して UI から受信したリクエストをターゲットエンドポイントにルーティングできるようになります。
ルーティングは、以下のルールに基づきます。
APIcast ポリシーと組み合わせる場合には、ポリシーチェーンでは APIcast ポリシーの前に Routing ポリシーを設定する必要があります。2 つのポリシーのうち始めのポリシーがレスポンスにコンテンツを出力するためです。2 番目のポリシーにコンテンツフェーズを実行する変更が加えられても、リクエストはすでにクライアントに送信されるため、レスポンスには何も出力されません。
4.1.20.1. ルーティングルール
- 複数のルールが存在する場合には、Routing ポリシーは最初のマッチに適用されます。これらのルールは並べ替えることができます。
- マッチするルールがなければ、ポリシーはアップストリームを変更せず、サービス設定で定義済みのプライベートベース URL を使用します。
4.1.20.2. リクエストパスルール
以下の設定では、パスが /accounts の場合に http://example.com にルーティングします。
4.1.20.3. ヘッダールール
以下の設定では、ヘッダー Test-Header の値が 123 の場合に http://example.com にルーティングします。
4.1.20.4. クエリー引数ルール
以下の設定では、クエリー引数 test_query_arg の値が 123 の場合に http://example.com にルーティングします。
4.1.20.5. JWT クレームルール
JWT クレームの値に基づいてルーティングするためには、ポリシーチェーンには、ポリシーが共有するコンテキストで JWT を検証して格納するポリシーが必要です。
以下の設定では、JWT クレーム test_claim の値が 123 の場合に http://example.com にルーティングします。
4.1.20.6. 複数演算ルール
ルールに複数の演算を設定し、すべてが true と評価される場合にだけ (「and」combine_op を使用) 指定したアップストリームにルーティングすることや、少なくとも 1 つが true と評価される場合に (「or」combine_op を使用) 指定したアップストリームにルーティングすることができます。combine_op のデフォルト値は「and」です。
以下の設定では、リクエストのパスが /accounts で、かつヘッダー Test-Header の値が 123 の場合に、http://example.com にルーティングします。
以下の設定では、リクエストのパスが /accounts であるか、またはヘッダー Test-Header の値が 123 の場合に、http://example.com にルーティングします。
4.1.20.7. ルールの結合
ルールを組み合わせることができます。複数のルールがある場合、選択されるアップストリームは、true と評価される最初のルールです。
複数のルールで構成される設定を以下に示します。
4.1.20.8. キャッチオールルール
演算のないルールは常にマッチします。これは、キャッチオールルールを定義するのに役立ちます。
以下の設定では、パスが /abc の場合にはリクエストを http://some_upstream.com にルーティングし、パスが /def の場合には http://another_upstream.com にルーティングし、上記ルールのどちらも true と評価されない場合には http://default_upstream.com にルーティングします。
4.1.20.9. サポートされる演算
サポートされる演算は、==、!=、および matches です。最後の演算は正規表現を使用する文字列との照合を行い、ngx.re.match を使用して実装されます。
以下の設定では、!= が使用されています。パスが /accounts ではない場合に http://example.com にルーティングします。
4.1.20.10. Liquid テンプレート
設定の値に liquid テンプレートを使用することができます。これにより、チェーン内のポリシーがコンテキストにキー my_var を保存する場合には、動的な値を使用してルールを定義することができます。
以下の設定では、リクエストをルーティングするのにその値が使用されています。
4.1.20.11. host_header で使用されるホストの設定
リクエストがルーティングされる際に、デフォルトでは、ポリシーはマッチしたルールの URL のホストを使用して Host ヘッダーを設定します。host_header 属性を使用して別のホストを指定することができます。
以下の設定では、Host ヘッダーのホストに some_host.com が指定されています。
4.1.21. SOAP
SOAP ポリシーでは、ポリシーで指定したマッピングルールを使用して、HTTP リクエストの SOAPAction または Content-Type ヘッダーにより提供される SOAP アクション URI との照合を行います。
設定プロパティー
| プロパティー | 説明 | 値 | 必須/任意 |
|---|---|---|---|
| pattern |
| データタイプ: 文字列 | 必須 |
| metric_system_name |
| データタイプ: 文字列 (有効な メトリクス でなければなりません) | 必須 |
ポリシーオブジェクトの例
ポリシーの設定方法に関する情報は、本書の「3scale でのポリシーチェーンの作成」セクションを参照してください。
4.1.22. TLS Client Certificate Validation
TLS Client Certificate Validation ポリシーでは、APIcast は TLS ハンドシェイクを実装し、ホワイトリストに対してクライアント証明書を検証します。ホワイトリストには、認証局 (CA) によって署名された証明書、または単なるクライアント証明書が含まれます。証明書の有効期限が切れている、または証明書が無効な場合には、リクエストは拒否され他のポリシーは処理されません。
クライアントは APIcast に接続してリクエストを送信し、クライアント証明書を提供します。APIcast は、ポリシー設定に従って受信したリクエストで提供された証明書の信ぴょう性を検証します。アップストリームに接続する際に独自のクライアント証明書を使用するように、APIcast を設定することもできます。
4.1.22.1. TLS Client Certificate Validation ポリシーに対応する APIcast の設定
TLS を終端するように APIcast を設定する必要があります。以下の手順に従って、Client Certificate Validation ポリシーが設定された APIcast でユーザーが提供するクライアント証明書を検証するように設定します。
前提条件:
- 3scale システムにアクセスできること。
- すべてのデプロイメントが完了していること。
4.1.22.1.1. ポリシーに対応する APIcast のセットアップ
APIcast をセットアップし TLS を終端するように設定するには、以下の手順に従います。
『3scale のインストール』の「OpenShift テンプレートを使用した APIcast のデプロイ」に記載の手順に従って、アクセストークンを取得し Self-managed APIcast をデプロイする必要があります。
注記ゲートウェイ全体で特定の証明書を使用するように APIcast インスタンスを再設定しなければならないので、Self-managed APIcast のデプロイメントが必要です。
テストを簡素化するために、
--paramフラグを指定してレイジーローダー、キャッシュなし、およびステージング環境を使用することができます (ただし、テスト目的の場合のみ)。oc new-app -f https://raw.githubusercontent.com/3scale/3scale-amp-openshift-templates/master/apicast-gateway/apicast.yml --param CONFIGURATION_LOADER=lazy --param DEPLOYMENT_ENVIRONMENT=staging --param CONFIGURATION_CACHE=0
oc new-app -f https://raw.githubusercontent.com/3scale/3scale-amp-openshift-templates/master/apicast-gateway/apicast.yml --param CONFIGURATION_LOADER=lazy --param DEPLOYMENT_ENVIRONMENT=staging --param CONFIGURATION_CACHE=0Copy to Clipboard Copied! Toggle word wrap Toggle overflow - テスト用途の証明書を生成します。なお、実稼働環境のデプロイメントの場合には、認証局から提供された証明書を使用することができます。
TLS 証明書を使用してシークレットを作成します。
oc create secret tls apicast-tls --cert=ca/certs/server.crt --key=ca/keys/server.key
oc create secret tls apicast-tls --cert=ca/certs/server.crt --key=ca/keys/server.keyCopy to Clipboard Copied! Toggle word wrap Toggle overflow APIcast デプロイメント内にシークレットをマウントします。
oc set volume dc/apicast --add --name=certificates --mount-path=/var/run/secrets/apicast --secret-name=apicast-tls
oc set volume dc/apicast --add --name=certificates --mount-path=/var/run/secrets/apicast --secret-name=apicast-tlsCopy to Clipboard Copied! Toggle word wrap Toggle overflow 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
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.keyCopy to Clipboard Copied! Toggle word wrap Toggle overflow サービスでポート 8443 を公開します。
oc patch service apicast -p '{"spec":{"ports":[{"name":"https","port":8443,"protocol":"TCP"}]}}'oc patch service apicast -p '{"spec":{"ports":[{"name":"https","port":8443,"protocol":"TCP"}]}}'Copy to Clipboard Copied! Toggle word wrap Toggle overflow デフォルトルートを削除します。
oc delete route api-apicast-staging
oc delete route api-apicast-stagingCopy to Clipboard Copied! Toggle word wrap Toggle overflow apicastサービスをルートとして公開します。oc create route passthrough --service=apicast --port=https --hostname=api-3scale-apicast-staging.$WILDCARD_DOMAIN
oc create route passthrough --service=apicast --port=https --hostname=api-3scale-apicast-staging.$WILDCARD_DOMAINCopy to Clipboard Copied! Toggle word wrap Toggle overflow 注記このステップは、使用するすべての API で実施する必要があります (それぞれの API のドメインに変更してください)。
プレースホルダーの [Your_user_key] に実際のキーを指定して、上記のステップでデプロイしたゲートウェイが機能し、設定が保存されていることを確認します。
curl https://api-3scale-apicast-staging.$WILDCARD_DOMAIN?user_key=[Your_user_key] -v --cacert ca/certs/ca.crt
curl https://api-3scale-apicast-staging.$WILDCARD_DOMAIN?user_key=[Your_user_key] -v --cacert ca/certs/ca.crtCopy to Clipboard Copied! Toggle word wrap Toggle overflow
4.1.22.2. ポリシーチェーンへの TLS Client Certificate Validation ポリシーの設定
ポリシーチェーンで TLS Client Certificate Validation を設定するには、以下を行います。
前提条件
- 3scale へのログインクレデンシャルが必要です。
- TLS Client Certificate Validation ポリシーに対応するように APIcast を設定 している必要があります。
4.1.22.2.1. ポリシーの設定
- 「管理ポータルでのポリシーの有効化」に記載の手順に従って TLS Client Certificate Validation を選択し、API に TLS Client Certificate Validation ポリシーを追加します。
- TLS Client Certificate Validation のリンクをクリックします。
- Enabled のチェックボックスを選択し、ポリシーを有効にします。
-
証明書をホワイトリストに追加するには、プラス (
+) アイコンをクリックします。 -
-----BEGIN CERTIFICATE-----および-----END CERTIFICATE-----を含めて、証明書を指定します。 - API への TLS Client Certificate Validation ポリシーの設定が完了したら、Update Policy をクリックします。
付加手順:
-
プラス (
+) アイコンをクリックして、さらに証明書を追加することができます。 - 上/下矢印を使用して、証明書の順番を入れ替えることもできます。
変更を保存するには、Update Policy Chain をクリックします。
4.1.22.3. TLS Client Certificate Validation ポリシー機能の確認
TLS Client Certificate Validation ポリシーの機能を確認するには、以下を実行します。
前提条件:
- 3scale へのログインクレデンシャルが必要です。
- TLS Client Certificate Validation ポリシーに対応するように APIcast を設定 している必要があります。
4.1.22.3.1. ポリシー機能の確認
プレースホルダーの [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
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.crt4.1.22.4. ホワイトリストからの証明書の削除
ホワイトリストから証明書を削除するには、以下を行います。
前提条件
- 3scale へのログインクレデンシャルが必要です。
- TLS Client Certificate Validation ポリシーに対応するように APIcast を設定 している必要があります。
- ポリシーチェーンに TLS Client Certificate Validation ポリシーを設定 して、証明書をホワイトリストに追加している必要があります。
4.1.22.4.1. 証明書の削除
- TLS Client Certificate Validation のリンクをクリックします。
-
xアイコンをクリックし、ホワイトリストから証明書を削除します。 - 証明書の削除が完了したら、Update Policy をクリックします。
変更を保存するには、Update Policy Chain をクリックします。
4.1.22.5. リファレンス資料
証明書の操作についての詳細は、Red Hat Certificate System のドキュメント を参照してください。
4.1.23. TLS Termination
本セクションでは、Transport Layer Security (TLS) Termination ポリシーに関して、その概要、設定、検証、およびポリシーからのファイル削除について説明します。
TLS Termination ポリシーを使用すると、全 API 用の単一の証明書を使用せずにそれぞれの API ごとに TLS リクエストを終端するように、APIcast を設定することができます。APIcast は、クライアントへの接続を確立する前に構成設定をプルします。このようにして、APIcast はポリシーからの証明書を使用して TLS を終端させます。このポリシーは、以下のソースと共に機能します。
- ポリシー設定内に保管されるソース
- ファイルシステム上に保管されるソース
デフォルトでは、このポリシーはポリシーチェーンで有効になっていません。
4.1.23.1. ポリシーチェーンへの TLS Termination ポリシーの設定
本セクションでは、ポリシーチェーンに TLS Termination ポリシーを設定するための前提条件および手順について説明します。なお、設定には Privacy Enhanced Mail (PEM) 形式の証明書を使用します。
前提条件
- ユーザーの発行した証明書
- PEM 形式のサーバー証明書
- PEM 形式の証明書の秘密鍵
4.1.23.1.1. ポリシーの設定
- 「管理ポータルでのポリシーの有効化」に記載の手順に従って TLS Termination を選択し、API に TLS Termination ポリシーを追加します。
- TLS Termination のリンクをクリックします。
- Enabled のチェックボックスを選択し、ポリシーを有効にします。
-
TLS 証明書をポリシーに追加するには、プラス (
+) アイコンをクリックします。 証明書のソースを選択します。
- Embedded certificate: サーバー証明書へのパスおよび証明書の秘密鍵へのパスを指定します。
- Certificate from local file system: 証明書の秘密鍵およびサーバー証明書のファイルを参照します。
- API への TLS Termination ポリシーの設定が完了したら、Update Policy をクリックします。
付加手順:
-
プラス (
+) アイコンをクリックして、さらに証明書を追加することができます。 - 上/下矢印を使用して、証明書の順番を入れ替えることもできます。
変更を保存するには、Update Policy Chain をクリックします。
4.1.23.2. TLS Termination ポリシー機能の確認
前提条件
- 3scale へのログインクレデンシャルが必要です。
- APIcast に TLS Termination ポリシーを設定 している必要があります。
4.1.23.2.1. ポリシー機能の確認
以下のコマンドを使用して、ポリシーが機能するかどうかをコマンドラインでテストすることができます。
curl “${public_URL}:${port}/?user_key=${user_key}" --cacert ${path_to_certificate}/ca.pem -v
curl “${public_URL}:${port}/?user_key=${user_key}" --cacert ${path_to_certificate}/ca.pem -vここでは、以下のようになります。
-
public_URL: ステージング環境用の公開ベース URL -
port: ポート番号 -
user_key: 認証に使用するユーザーキー -
path_to_certificate: ローカルファイルシステムに保管された CA 証明書へのパス
4.1.23.3. TLS Termination ポリシーからのファイルの削除
本セクションでは、TLS Termination ポリシーから証明書およびキーファイルを削除する手順について説明します。
前提条件
- 3scale へのログインクレデンシャルが必要です。
- APIcast に TLS Termination ポリシーを設定 して、証明書をポリシーに追加している必要があります。
4.1.23.3.1. 証明書の削除
- TLS Termination のリンクをクリックします。
-
xアイコンをクリックして、証明書およびキーを削除します。 - 証明書の削除が完了したら、Update Policy をクリックします。
変更を保存するには、Update Policy Chain をクリックします。
4.1.24. Upstream
Upstream ポリシーでは、正規表現を使用して Host リクエストヘッダーを解析し、プライベートベース URL で定義されたアップストリーム URL を別の URL に置き換えることができます。
例:
正規表現 /foo および URL フィールド newexample.com が設定されたポリシーが、URL https://www.example.com/foo/123/ を newexample.com に置き換える
ポリシーチェーンの参照
| プロパティー | 説明 | 値 | 必須/任意 |
|---|---|---|---|
| regex |
| データタイプ: 文字列 (有効な正規表現の構文でなければなりません) | 必須 |
| url |
| データタイプ: 文字列 (有効な URL でなければなりません) | 必須 |
ポリシーオブジェクトの例
ポリシーの設定方法に関する情報は、本書の「3scale でのポリシーチェーンの作成」セクションを参照してください。
4.1.25. Upstream Connection
Upstream Connection ポリシーを使用すると、3scale システムでの API バックエンドサーバーの設定に応じて、API ごとに以下のディレクティブのデフォルト値を変更することができます。
-
proxy_connect_timeout -
proxy_send_timeout -
proxy_read_timeout
4.1.25.1. ポリシーチェーンへの Upstream Connection ポリシーの設定
本セクションでは、ポリシーチェーンで Upstream Connection ポリシーを設定する手順を説明します。
前提条件
- 3scale システムにアクセスできること。
- すべてのデプロイメントが完了していること。
4.1.25.1.1. ポリシーの設定
- 「管理ポータルでのポリシーの有効化」に記載の手順に従って Upstream Connection を選択し、API に Upstream Connection ポリシーを追加します。
- Upstream Connection のリンクをクリックします。
- Enabled のチェックボックスを選択し、ポリシーを有効にします。
アップストリームへの接続に関するオプションを設定します。
-
send_timeout -
connect_timeout -
read_timeout
-
- API への Upstream Connection ポリシーの設定が完了したら、Update Policy をクリックします。
変更を保存するには、Update Policy Chain をクリックします。
4.1.26. Upstream Mutual TLS
Upstream Mutual TLS ポリシーを使用すると、設定で指定した証明書に基づいて、APIcast とアップストリーム API との間で相互 TLS 接続を確立することができます。このポリシーは、アップストリーム API に応じて複数の証明書をサポートします。
4.1.26.1. ポリシーチェーンへの Upstream Mutual TLS ポリシーの設定
本セクションでは、ポリシーチェーンで Upstream Mutual TLS ポリシーを設定する手順を説明します。
前提条件
- 3scale システムにアクセスできること。
手順
- 「管理ポータルでのポリシーの有効化」に記載の手順に従って Upstream Mutual TLS を選択し、API に Upstream Mutual TLS ポリシーを追加します。
- Upstream Mutual TLS のリンクをクリックします。
- Enabled のチェックボックスを選択し、ポリシーを有効にします。
Certificate type を選択します。
- path: OpenShift によって生成された証明書などのパスを指定する場合。
- embedded: サードパーティーが生成した証明書をファイルシステムからアップロードして使用する場合。
- Certificate でクライアント証明書を指定します。
- Certificate key でキーを指定します。
- API への Upstream Mutual TLS ポリシーの設定が完了したら、Update Policy Chain をクリックします。
変更をプロモートするには、以下の手順を実施します。
- [Your_product] page > Integration > Configuration の順に移動します。
APIcast Configuration セクションで、Promote v# to Staging APIcast をクリックします。
-
v#は、プロモートされる設定のバージョン番号を表します。
-
4.1.27. URL Rewriting
URL Rewriting ポリシーを使用すると、リクエストのパスおよびクエリー文字列を変更することができます。
3scale APIcast ポリシーと組み合わせる場合には、ポリシーチェーンで URL Rewriting ポリシーを APIcast ポリシーの前に設定すると、APIcast のマッピングルールは変更したパスに適用されます。ポリシーチェーンで URL Rewriting ポリシーを APIcast ポリシーの後に設定すると、マッピングルールは元のパスに適用されます。
このポリシーでは、以下の 2 つの操作セットがサポートされます。
-
commands: リクエストのパスを書き換えるために適用されるコマンドのリスト。 -
query_args_commands: リクエストのクエリー文字列を書き換えるために適用されるコマンドのリスト。
4.1.27.1. パスを書き換えるためのコマンド
commands リストの各コマンドは、以下の設定パラメーターで構成されます。
-
op: 適用される操作。設定可能なオプションはsubおよびgsubです。sub操作では、指定した正規表現との最初のマッチだけが置き換えられます。gsub操作では、指定した正規表現とのマッチがすべて置き換えられます。sub および gsub 操作に関するドキュメントを参照してください。 -
regex: 照合される Perl 互換の正規表現 -
replace: マッチした際に置き換えられる文字列 -
options(オプション): 正規表現との照合がどのように行われるかを定義するオプション。設定可能なオプションに関する情報は、OpenResty Lua モジュールプロジェクトのドキュメントの「ngx.re.match」セクションを参照してください。 -
break(オプション): true に設定すると (チェックボックスを選択する)、コマンドが URL を書き換えた場合、それが適用される最後のコマンドになります (リスト内の後続コマンドはすべて破棄されます)。
4.1.27.2. クエリー文字列を書き換えるためのコマンド
query_args_commands リストの各コマンドは、以下の設定パラメーターで構成されます。
op: クエリー引数に適用される操作。以下のオプションを設定することができます。-
add: 既存の引数に値を追加します。 -
set: 引数が設定されていなければ作成し、設定されていればその値を置き換えます。 -
push: 引数が設定されていなければ作成し、設定されていれば値を追加します。 -
delete: 引数を削除します。
-
-
arg: 操作が適用されるクエリー引数の名前 -
value: クエリー引数に使用される値を指定します。値のタイプが「liquid」の場合には、値は{{ variable_from_context }}の形式にする必要があります。delete操作の場合には、値を考慮する必要はありません。 -
value_type(オプション): クエリー引数の値がどのように評価されるかを定義します。プレーンテキストの場合のplainまたは Liquid テンプレートとして評価する場合のliquidいずれかに設定します。詳細な情報は、「ポリシーでの変数およびフィルターの使用」を参照してください。指定しなければ、デフォルトではタイプ「plain」が使用されます。
例
URL Rewriting ポリシーは、以下のように設定します。
APIcast に送信される元のリクエスト URI:
https://api.example.com/api/v1/products/123/details?user_key=abc123secret&pusharg=first&setarg=original
https://api.example.com/api/v1/products/123/details?user_key=abc123secret&pusharg=first&setarg=originalURL の書き換えを適用した後に APIcast が API バックエンドに送信する URI:
https://api-backend.example.com/internal/products/123/details?pusharg=first&pusharg=pushvalue&setarg=setvalue
https://api-backend.example.com/internal/products/123/details?pusharg=first&pusharg=pushvalue&setarg=setvalue以下の変換が適用されます。
-
サブストリング
/api/v1/はパス書き換えコマンドだけにマッチし、/internal/に置き換えられます。 -
user_keyクエリー引数は削除されます。 -
値
pushvalueは追加の値としてpushargクエリー引数に追加されます。 -
クエリー引数
setargの値originalは、設定した値setvalueに置き換えられます。 -
クエリー引数
addargは元の URL に存在しないため、コマンドaddは適用されませんでした。
ポリシーの設定方法に関する情報は、本書の「3scale でのポリシーチェーンの作成」セクションを参照してください。
4.1.28. 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 ポリシーは、以下のように設定します。
APIcast に送信される元のリクエスト URI:
https://api.example.com/api/v1/products/123/details?user_key=abc123secret
https://api.example.com/api/v1/products/123/details?user_key=abc123secretURL の書き換えを適用した後に APIcast が API バックエンドに送信する URI:
https://api-backend.example.com/internal/products/details?user_key=abc123secret&extraparam=anyvalue&id=123
https://api-backend.example.com/internal/products/details?user_key=abc123secret&extraparam=anyvalue&id=123
'%20d='M201.5%20305.5c-13.8%200-24.9-11.1-24.9-24.6%200-13.8%2011.1-24.9%2024.9-24.9%2013.6%200%2024.6%2011.1%2024.6%2024.9%200%2013.6-11.1%2024.6-24.6%2024.6zM504%20256c0%20137-111%20248-248%20248S8%20393%208%20256%20119%208%20256%208s248%20111%20248%20248zm-132.3-41.2c-9.4%200-17.7%203.9-23.8%2010-22.4-15.5-52.6-25.5-86.1-26.6l17.4-78.3%2055.4%2012.5c0%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.3%2024.9-24.9s-11.1-24.9-24.9-24.9c-9.7%200-18%205.8-22.1%2013.8l-61.2-13.6c-3-.8-6.1%201.4-6.9%204.4l-19.1%2086.4c-33.2%201.4-63.1%2011.3-85.5%2026.8-6.1-6.4-14.7-10.2-24.1-10.2-34.9%200-46.3%2046.9-14.4%2062.8-1.1%205-1.7%2010.2-1.7%2015.5%200%2052.6%2059.2%2095.2%20132%2095.2%2073.1%200%20132.3-42.6%20132.3-95.2%200-5.3-.6-10.8-1.9-15.8%2031.3-16%2019.8-62.5-14.9-62.5zM302.8%20331c-18.2%2018.2-76.1%2017.9-93.6%200-2.2-2.2-6.1-2.2-8.3%200-2.5%202.5-2.5%206.4%200%208.6%2022.8%2022.8%2087.3%2022.8%20110.2%200%202.5-2.2%202.5-6.1%200-8.6-2.2-2.2-6.1-2.2-8.3%200zm7.7-75c-13.6%200-24.6%2011.1-24.6%2024.9%200%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.1%2024.9-24.6%200-13.8-11-24.9-24.9-24.9z'/%3e%3c/svg%3e){kind=small}