1. Homepage
  2. Flex Gateway (1.7)
  3. 内部ポリシーディレクトリ

  4. 外部認証

外部認証ポリシー

ポリシー名

外部認証

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 のローカルモード

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

- policyRef:
    name: native-ext-authz-flex
  config:
    uri: <string> // REQUIRED
    serverType: <string> // REQUIRED, default "grpc"
    serverVersion: <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
    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​ です。

serverVersion

省略可能

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​ 種別のサーバーで使用できます。

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 の接続モード

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

パラメーター 説明

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

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

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

外部サーバーの種別。

Transport protocol API version (トランスポートプロトコル API バージョン)

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

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

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

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

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

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

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

ポリシーのしくみ

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

80%

  1. クライアントが Flex Gateway によって公開される API インスタンスに対する HTTP 要求を行います。

  2. Flex Gateway がクライアントの要求とヘッダーで構成される要求を認証サービスに転送します。

  3. 認証サービスが認証応答を Flex Gateway に送信し返します。

    • 要求が認証されない場合、Flex Gateway では必要なヘッダーを追加し、​403​ 禁止アクセスコードをクライアントに返します。

    • 要求が承認されると、Flex Gateway では必要に応じてヘッダーデータをクライアント要求に追加して、要求がアップストリームサービスに渡されることを許可します。

  4. Flex Gateway は必要なヘッダーを追加し、通常どおりに応答を返します。