外部認証ポリシー

ポリシー名

外部認証

Summary (概要)

外部 gRPC または HTTP 認証サービスを使用して要求を認証します

カテゴリ

セキュリティ

使用可能な最小 Flex Gateway バージョン

v1.6.0

返される状況コード

403 - アクセス拒否、無効なクライアントアプリケーションログイン情報

概要

外部認証ポリシーでは、受信クライアント HTTP 要求を外部 gRPC または HTTP 認証サービスに転送してクライアント HTTP 要求がアップストリームサービスへのアクセスを承認されるかどうかを判断します。要求が承認されると、Flex Gateway では要求がアップストリームサービスに渡されることを許可します。不正なアクセスでは、Flex Gateway では 403 禁止要求エラーを返します。

認証トークンヘッダーなどのリクエストヘッダーをクライアント HTTP 要求から認証サービスに転送するには、[Allowed Headers (許可されるヘッダー)] パラメーターを設定します。さらに、HTTP 認証サーバーの場合は、[Headers to add (追加するヘッダー)] パラメーターを使用して新しいヘッダーを認証要求に挿入します。

Flex Gateway によってヘッダーがバイト単位でエンコードされ、認証サービスに送信されます。utf8 でエンコードされたヘッダーを送信するには、環境変数 FLEX_HEADER_RAW_VALUE_ENABLE=false を設定します。

外部認証ポリシーでは、認証サービスから返された追加情報を使用してクライアント HTTP リクエストおよびレスポンスヘッダーを変更することもできます。たとえば、承認済みのユーザーがユーザー名に対応するアクセストークンヘッダーを使用して要求を行うと、認証サービスでは Flex Gateway がクライアント HTTP 要求を追加できるように username ヘッダーを返す場合があります。

gRPC 認証サーバーの場合は、認証サービスが認証応答を含めてヘッダーを返す場合、Flex Gateway ではこれらのヘッダーをクライアント HTTP 要求に追加するか、クライアント要求に存在する場合はヘッダーを上書きします。

HTTP 認証サーバーの場合は、追加、上書き、または無視するヘッダーを設定できます。HTTP サーバーが設定されているポリシーでも、アップストリームサービスから返されるクライアント応答を変更できます。

外部認証ポリシーは、Envoy に対してネイティブな外部認証検索条件の拡張機能です。外部認証検索条件に付いての詳細は、「External Authorization Filter (外部認証検索条件)」を参照してください。すべての外部認証検索条件パラメーターが外部認証ポリシーで使用できるとは限りません。設定可能なパラメーターを確認するには、「ポリシーのパラメーターの設定」を参照してください。

他のポリシーで受信 HTTP 要求が変更される場合は、要求を認証サービスに送信する前にこれらの変更が存在している必要があるかどうかに応じて確実にポリシーを並び替えてください。ポリシーの並び替えについての詳細は、ポリシーの順序付けを参照してください。

ポリシーのパラメーターの設定

ポリシーパラメーターを設定するには、Flex Gateway が実行されているモードに関する次のパラメーターリファレンスを参照してください。

Flex Gateway のローカルモード
管理 Flex Gateway および Flex Gateway の接続モード

Flex Gateway のローカルモード

ローカルモードでは、宣言型の設定ファイルを使用してポリシーを API に適用します。以下のポリシー定義とパラメーターの表を参照してください。

- policyRef:
    name: native-ext-authz-flex
  config:
    uri: <string> // REQUIRED
    serverType: <string> // REQUIRED, default "grpc"
    serverApiVersion: <string> // REQUIRED, default `v3`
    serviceRequestHeadersToAdd: <object-array> // OPTIONAL
      - key: <string>
        value: <string>
    serviceResponseUpstreamHeaders: <string-array> // OPTIONAL
    serviceResponseUpstreamHeadersToAppend: <string-array> // OPTIONAL
    serviceResponseClientHeaders: <string-array> // OPTIONAL
    serviceResponseClientHeadersOnSuccess: <string-array> // OPTIONAL
    pathPrefix: <string> // OPTIONAL
    requestTimeout: <number> // REQUIRED, default `5000`
    includePeerCertificate: <boolean> // REQUIRED, default `false`
    allowedHeaders: <string-array> // OPTIONAL

パラメーター必須または省略可能デフォルト値説明

パラメーター	必須または省略可能	デフォルト値	説明
`uri`	必須	なし	外部認証サービス URI。gRPC 種別のサーバーでは、次の形式を使用して URI を定義します: `h2://<ext.authz.com>:<port>`。
`serverType`	必須	`grpc`	外部サーバーの種別。サポートされている値は `grpc` と `http` です。
`serverApiVersion`	省略可能	`v3`	トランスポートプロトコル API バージョン。サポートされている値は `v3` と `v2` です。
`includePeerCertificate`	省略可能	`false`	`true` の場合、認証サーバー要求にピア証明書が含まれます。サポートされている値は `true` と `false` です。
`serviceRequestHeadersToAdd`	省略可能	なし	認証サービス要求に挿入するカスタムヘッダーとその値が定義されます。このパラメーターは `HTTP` 種別のサーバーで使用できます。
`serviceRequestHeadersToAdd.key`	省略可能	なし	追加する新しいヘッダーの名前。
`serviceRequestHeadersToAdd.value`	省略可能	なし	追加する新しいヘッダーの値。
`serviceResponseUpstreamHeaders`	省略可能	なし	アップストリームサービスへのクライアント要求に追加する認証応答からのヘッダーが指定されます。Flex Gateway によって共存するヘッダーが上書きされます。このパラメーターは `HTTP` 種別のサーバーで使用できます。
`serviceResponseUpstreamHeadersToAppend`	省略可能	なし	アップストリームサービスへのクライアント要求に追加する認証応答からのヘッダーが指定されます。Flex Gateway によって共存するヘッダーが追加されます。このパラメーターは `HTTP` 種別のサーバーで使用できます。
`serviceResponseClientHeaders`	省略可能	なし	アップストリームサービスから返されるクライアント応答に追加する認証応答からのヘッダーが指定されます。Flex Gateway によって既存のヘッダーが上書きされます。このパラメーターは `HTTP` 種別のサーバーで使用できます。
`serviceResponseClientHeadersOnSuccess`	省略可能	なし	要求が正常に認証された場合にアップストリームサービスから返されるクライアント応答に追加する認証応答からのヘッダーが指定されます。Flex Gateway によって既存のヘッダーが上書きされます。このパラメーターは `HTTP` 種別のサーバーで使用できます。
`pathPrefix`	省略可能	なし	`Path` 認証リクエストヘッダーが存在する場合はその値に対するプレフィックスを設定します。
`requestTimeout`	省略可能	`5000`	ポリシーが認証サービスからの応答を待機する最大時間 (ミリ秒)。
`allowedHeaders`	省略可能	なし	認証要求に伝播するクライアント HTTP 要求からのヘッダーが指定されます。デフォルトでは、gRPC サーバーに送信される要求にはすべてのクライアントヘッダーが含まれます。HTTP サーバーに送信される要求にはクライアントヘッダーが含まれません。各サーバー種別の許可されるヘッダーをリストする場合は、要求にリストされたヘッダーのみが含まれます。

uri

必須

なし

外部認証サービス URI。gRPC 種別のサーバーでは、次の形式を使用して URI を定義します: h2://<ext.authz.com>:<port>。

serverType

必須

grpc

外部サーバーの種別。サポートされている値は grpc と http です。

serverApiVersion

省略可能

v3

トランスポートプロトコル API バージョン。サポートされている値は v3 と v2 です。

includePeerCertificate

省略可能

false

true の場合、認証サーバー要求にピア証明書が含まれます。サポートされている値は true と false です。

serviceRequestHeadersToAdd

省略可能

なし

認証サービス要求に挿入するカスタムヘッダーとその値が定義されます。このパラメーターは HTTP 種別のサーバーで使用できます。

serviceRequestHeadersToAdd.key

省略可能

なし

追加する新しいヘッダーの名前。

serviceRequestHeadersToAdd.value

省略可能

なし

追加する新しいヘッダーの値。

serviceResponseUpstreamHeaders

省略可能

なし

アップストリームサービスへのクライアント要求に追加する認証応答からのヘッダーが指定されます。Flex Gateway によって共存するヘッダーが上書きされます。このパラメーターは HTTP 種別のサーバーで使用できます。

serviceResponseUpstreamHeadersToAppend

省略可能

なし

アップストリームサービスへのクライアント要求に追加する認証応答からのヘッダーが指定されます。Flex Gateway によって共存するヘッダーが追加されます。このパラメーターは HTTP 種別のサーバーで使用できます。

serviceResponseClientHeaders

省略可能

なし

アップストリームサービスから返されるクライアント応答に追加する認証応答からのヘッダーが指定されます。Flex Gateway によって既存のヘッダーが上書きされます。このパラメーターは HTTP 種別のサーバーで使用できます。

serviceResponseClientHeadersOnSuccess

省略可能

なし

要求が正常に認証された場合にアップストリームサービスから返されるクライアント応答に追加する認証応答からのヘッダーが指定されます。Flex Gateway によって既存のヘッダーが上書きされます。このパラメーターは HTTP 種別のサーバーで使用できます。

pathPrefix

省略可能

なし

Path 認証リクエストヘッダーが存在する場合はその値に対するプレフィックスを設定します。

requestTimeout

省略可能

5000

ポリシーが認証サービスからの応答を待機する最大時間 (ミリ秒)。

allowedHeaders

省略可能

なし

認証要求に伝播するクライアント HTTP 要求からのヘッダーが指定されます。デフォルトでは、gRPC サーバーに送信される要求にはすべてのクライアントヘッダーが含まれます。HTTP サーバーに送信される要求にはクライアントヘッダーが含まれません。各サーバー種別の許可されるヘッダーをリストする場合は、要求にリストされたヘッダーのみが含まれます。

必須の値を空白のままにすると、パラメーターがデフォルト値として設定されます。省略可能な値を空白のままにした場合は、値が設定されません。

リソースの設定例

次の設定では、gRPC 認証サービスがピア証明書と認証トークンヘッダーが含まれる要求を受信します。

- policyRef:
    name: native-ext-authz-flex
  config:
    uri: h2://ext-authz-grpc-service:9001
    serverType: "grpc"
    includePeerCertificate: "true"
    allowedHeaders:
      - access-token

管理 Flex Gateway および Flex Gateway の接続モード

UI からポリシーを API インスタンスに適用するときに、以下のパラメーターが表示されます。

パラメーター 説明

パラメーター	説明
External authorization service URI (外部認証サービス URI)	外部認証サービス URI。gRPC 種別のサーバーでは、`\h2://<ext.authz.com>:<port>` として URI を定義します。
External authorization server type (外部認証サーバー種別)	外部サーバーの種別。
Server API version (サーバー API バージョン)	トランスポートプロトコル API バージョン。
Include peer certificates in the authorization server request (認証サーバー要求にピア証明書が含まれる)	認証サーバー要求にピア証明書が含まれます。
Path prefix (パスプレフィックス)	`Path` 認証リクエストヘッダーが存在する場合はその値に対するプレフィックスを設定します。
Request Timeout (要求タイムアウト)	ポリシーが認証サービスからの応答を待機する最大時間 (ミリ秒)。デフォルトでは、要求タイムアウトは 5000 ミリ秒です。
Allowed headers (許可されるヘッダー)	デフォルトでは、gRPC サーバーに送信される要求にはすべてのクライアントヘッダーが含まれ、HTTP サーバーに送信される要求にはクライアントヘッダーが含まれません。各サーバー種別の許可されるヘッダーをリストする場合は、要求にリストされたヘッダーのみが含まれます。

External authorization service URI (外部認証サービス URI)

外部認証サービス URI。gRPC 種別のサーバーでは、\h2://<ext.authz.com>:<port> として URI を定義します。

External authorization server type (外部認証サーバー種別)

外部サーバーの種別。

Server API version (サーバー API バージョン)

トランスポートプロトコル API バージョン。

Include peer certificates in the authorization server request (認証サーバー要求にピア証明書が含まれる)

認証サーバー要求にピア証明書が含まれます。

Path prefix (パスプレフィックス)

Path 認証リクエストヘッダーが存在する場合はその値に対するプレフィックスを設定します。

Request Timeout (要求タイムアウト)

ポリシーが認証サービスからの応答を待機する最大時間 (ミリ秒)。デフォルトでは、要求タイムアウトは 5000 ミリ秒です。

Allowed headers (許可されるヘッダー)

デフォルトでは、gRPC サーバーに送信される要求にはすべてのクライアントヘッダーが含まれ、HTTP サーバーに送信される要求にはクライアントヘッダーが含まれません。各サーバー種別の許可されるヘッダーをリストする場合は、要求にリストされたヘッダーのみが含まれます。

ポリシーのしくみ

次の図は、外部認証ポリシー実行時の要求と応答のフローの順序を示しています。

ユーザー、API ゲートウェイ、データベース、API 間のインタラクションを示すシーケンス図

クライアントが Flex Gateway によって公開される API インスタンスに対する HTTP 要求を行います。
Flex Gateway がクライアントの要求とヘッダーで構成される要求を認証サービスに転送します。
認証サービスが認証応答を Flex Gateway に送信し返します。
- 要求が認証されない場合、Flex Gateway では必要なヘッダーを追加し、403 禁止アクセスコードをクライアントに返します。
- 要求が承認されると、Flex Gateway では必要に応じてヘッダーデータをクライアント要求に追加して、要求がアップストリームサービスに渡されることを許可します。
Flex Gateway は必要なヘッダーを追加し、通常どおりに応答を返します。