コンテンツにスキップ
|
Kong Gateway
3.8.x
report-issue問題を報告する
旧バージョンのドキュメントを参照しています。 最新のドキュメントはこちらをご参照ください。

kong.client

クライアント情報モジュール。

特定のリクエストのコンテキストでKongに接続しているクライアントに関する情報を取得するための関数のセット。

ほかの参照リソース：nginx.org/en/docs/http/ngx_http_realip_module.html

kong.client.get_ip()

リクエストを行っているクライアントのリモートアドレスを返します。このモジュールは 常に Kongに直接接続しているクライアントのアドレスを返します。つまり、 ロードバランサーがKongの前にある場合、この関数はダウンストリームの クライアントのアドレス ではなく 、ロードバランサーのアドレスを返します。

フェーズ

  • certificate, rewrite, access, header_filter, response, body_filter, log

戻り値

  • string: リクエストを行っているクライアントのリモートIPアドレス。

使用方法

-- Given a client with IP 127.0.0.1 making connection through
-- a load balancer with IP 10.0.0.1 to Kong answering the request for
-- https://example.com:1234/v1/movies
kong.client.get_ip() -- "10.0.0.1"

kong.client.get_forwarded_ip()

リクエストを行っているクライアントのリモートアドレスを返します。kong.client.get_ip とは異なり、この関数は、ロードバランサーがKongの前にある場合に転送されたアドレスを考慮します。 この関数が転送されたアドレスを返すかどうかは、以下のKong構成パラメータに応じて決まります。

フェーズ

  • certificate, rewrite, access, header_filter, response, body_filter, log

戻り値

  • string：転送されたアドレスを考慮して、リクエストを行っているクライアントの リモートIPアドレス。

使用方法

-- Given a client with IP 127.0.0.1 making connection through
-- a load balancer with IP 10.0.0.1 to Kong answering the request for
-- https://username:password@example.com:1234/v1/movies

kong.client.get_forwarded_ip() -- "127.0.0.1"

-- Note: This example assumes that 10.0.0.1 is one of the trusted IPs, and that
-- the load balancer adds the right headers matching with the configuration
-- of `real_ip_header`, e.g. `proxy_protocol`.

kong.client.get_port()

リクエストを行っているクライアントのリモートポートを返します。これは 常に Kongに直接接続しているクライアントのポートを返します。つまり、 ロードバランサーがKongの前にある場合、この関数はダウンストリームの クライアントのポート ではなく 、ロードバランサーのポートを返します。

フェーズ

  • certificate, rewrite, access, header_filter, response, body_filter, log

戻り値

  • number：リモートクライアントのポート。

使用方法

-- [client]:40000 <-> 80:[balancer]:30000 <-> 80:[kong]:20000 <-> 80:[service]
kong.client.get_port() -- 30000

kong.client.get_forwarded_port()

リクエストを行っているクライアントのリモートポートを返します。kong.client.get_portとは異なり、この関数は、ロードバランサーがKongの前にある場合に転送されたポートを考慮します。この関数が転送されたポートを返すかどうかは、以下のKong構成パラメータに応じて決まります。

フェーズ

  • certificate, rewrite, access, header_filter, response, body_filter, log

戻り値

  • number: 転送されたポートを考慮したリモートクライアントポート。

使用方法

-- [client]:40000 <-> 80:[balancer]:30000 <-> 80:[kong]:20000 <-> 80:[service]
kong.client.get_forwarded_port() -- 40000

-- Note: This example assumes that [balancer] is one of the trusted IPs, and that
-- the load balancer adds the right headers matching with the configuration
-- of `real_ip_header`, e.g. `proxy_protocol`.

kong.client.get_credential()

現在認証されているコンシューマの認証情報を返します。設定されていない場合は、nilを返します。

フェーズ

  • access、header_filter、response、body_filter、log

戻り値

  • string: 認証された認証情報。

使用方法

local credential = kong.client.get_credential()
if credential then
  consumer_id = credential.consumer_id
else
  -- request not authenticated yet
end

kong.client.load_consumer(consumer_id[, search_by_username])

データストアからコンシューマを返します。IDでコンシューマを検索し、オプションで名前による2番目の検索を実行することもできます。

フェーズ

  • access、header_filter、response、body_filter、log

パラメータ

  • consumer_id (string): 検索するコンシューマ ID
  • search_by_username (boolean、 オプション ): 真実かつ、 IDでコンシューマが見つからない場合、 ユーザー名による2回目の検索が実行されます。

戻り値

  1. table|nil：コンシューマエンティティまたは nil。

  2. nil|err：成功した場合はnil、失敗した場合はエラーメッセージ。

使用方法

local consumer_id = "john_doe"
local consumer = kong.client.load_consumer(consumer_id, true)

kong.client.get_consumer()

現在認証されているコンシューマの consumer エンティティを返します。 設定されていない場合は、nil を返します。

フェーズ

  • access、header_filter、response、body_filter、log

戻り値

  • table: 認証されたコンシューマエンティティ。

使用方法

local consumer = kong.client.get_consumer()
if consumer then
  consumer_id = consumer.id
else
  -- request not authenticated yet, or a credential
  -- without a consumer (external auth)
end

kong.client.authenticate(consumer, credential)

認証されたコンシューマおよび/または認証情報、および現在のリクエストの認証済みコンシューマグループを設定します。consumerとcredentialはどちらもnilになる可能性がありますが、少なくともどちらかは存在する必要があります。それ以外の場合、この関数はエラーをスローします。

フェーズ

  • access

パラメータ

  • consumer （table|nil）: 設定するコンシューマー。値が指定されない場合、既存の値はすべて削除されます。
  • credential （table|nil）: 設定する認証情報。値が指定されない場合、既存の値はすべて削除されます。

使用方法

-- assuming `credential` and `consumer` have been set by some authentication code
kong.client.authenticate(consumer, credentials)

_CLIENT.set_authenticated_consumer_groups(group)

現在のリクエストに対して認証されたコンシューマグループを明示的に設定します。 group が、テーブルでも nil でもない場合にはエラーを通知します。

フェーズ

  • auth_and_later

パラメータ

  • グループ （table|nil）：設定するコンシューマグループ。「いいえ」の値が指定された場合、既存の値はすべてクリアされます。この値は、各グループが idやnameのようなグループのメタデータを含むテーブル。

使用方法

-- assuming `group` is provided by some code
_CLIENT.set_authenticated_consumer_groups(group)

_CLIENT.set_authenticated_consumer_group(group)

この関数は非推奨となり、set_authenticated_consumer_groupsが優先されるようになります。 現在のリクエストに対して認証されたコンシューマグループを明示的に設定します。 groupがテーブルでもnilでもない場合は、エラーをスローします。

フェーズ

  • auth_and_later

パラメータ

  • グループ （table|nil）：設定するコンシューマグループ。「いいえ」の値が指定された場合、既存の値はすべてクリアされます。この値は、 idやnameのようなグループのメタデータを含むテーブルである必要があります。

使用方法

-- assuming `group` is provided by some code
_CLIENT.set_authenticated_consumer_group(group)

_CLIENT.get_consumer_groups()

現在のリクエストの認証済みコンシューマ グループを取得します。

フェーズ

  • auth_and_later

戻り値

  • table|nil: 認証されたコンシューマグループ。現在のリクエストに対してコンシューマグループが認証されていない場合は、nilを返します。

使用方法

local groups = _CLIENT.get_consumer_groups()

_CLIENT.get_consumer_group()

この関数は非推奨となり、get_consumer_groups が優先されるようになります。現在のリクエストに対する認証済みコンシューマグループを取得します。

フェーズ

  • auth_and_later

戻り値

  • table|nil：認証されたコンシューマグループ。ない場合はnilを返します 現在のリクエストに対してコンシューマ グループが認証されました。

使用方法

local group = _CLIENT.get_consumer_group()

_CLIENT.authenticate_consumer_group_by_consumer_id(consumer_id)

指定されたコンシューマ IDに基づいて、現在のリクエストのコンシューマグループを設定します。consumer_idが文字列でもnilでもない場合は、エラーが返されます。コンシューマグループがすでに認証されている場合、グループは上書きされません。この関数は、cache_keyのサブセットを使用して、redis-SCAN のような検索を実行します。consumer_group_mappingは決定論的な動作のためにグループ名でソートされますが、これは将来のリリースで変更される可能性があります。

フェーズ

  • access

パラメータ

  • consumer_id （string|nil）：コンシューマグループ向けのコンシューマID。 値が未指定の場合、現在のコンシューマグループは変更されません。

使用方法

-- assuming `consumer_id` is provided by some code
_CLIENT.authenticate_consumer_group_by_consumer_id(consumer_id)

kong.client.get_protocol([allow_terminated])

現在のルートに一致するプロトコルを返します（"http"、"https"、"tcp" または "tls"）。一致するルートがない場合は nil を返します。これは、リクエストが間違っている場合に起こり得ます。

フェーズ

  • access、header_filter、response、body_filter、log

パラメータ

  • allow_terminated （boolean、 任意 ）: 設定すると、HTTPSのチェック時にX-Forwarded-Protoヘッダーがチェックされます。

戻り値

  1. string|nil: "http"、 "https"、 "tcp"、 "tls"、 nilのいずれかになります。

  2. nil|err：成功した場合はnil、失敗した場合はエラーメッセージ。

使用方法

kong.client.get_protocol() -- "http"