kong.client

kong.client

Client information module.

A set of functions to retrieve information about the client connecting to Kong in the context of a given request.

kong.client.get_ip()

Returns the remote address of the client making the request. This module always returns the address of the client directly connecting to Kong. That is, in cases when a load balancer is in front of Kong, this function returns the load balancer’s address, and not that of the downstream client.

Phases

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

Returns

string: The remote IP address of the client making the request.

Usage

-- 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()

Returns the remote address of the client making the request. Unlike kong.client.get_ip, this function will consider forwarded addresses in cases when a load balancer is in front of Kong. Whether this function returns a forwarded address or not depends on several Kong configuration parameters:

Phases

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

Returns

string: The remote IP address of the client making the request, considering forwarded addresses.

Usage

-- 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()

Returns the remote port of the client making the request. This always returns the port of the client directly connecting to Kong. That is, in cases when a load balancer is in front of Kong, this function returns the load balancer’s port, and not that of the downstream client.

Phases

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

Returns

number: The remote client port.

Usage

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

kong.client.get_forwarded_port()

Returns the remote port of the client making the request. Unlike kong.client.get_port, this function will consider forwarded ports in cases when a load balancer is in front of Kong. Whether this function returns a forwarded port or not depends on several Kong configuration parameters:

Phases

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

Returns

number: The remote client port, considering forwarded ports.

Usage

-- [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()

Returns the credentials of the currently authenticated consumer. If not set yet, it returns nil.

Phases

access, header_filter, response, body_filter, log

Returns

string: The authenticated credential.

Usage

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])

Returns the consumer from the datastore. Looks up the consumer by ID, and can optionally do a second search by name.

Phases

access, header_filter, response, body_filter, log

Parameters

consumer_id (string): The consumer ID to look up.
search_by_username (boolean, optional): If truthy, and if the consumer is not found by ID, then a second search by username will be performed.

Returns

table|nil: Consumer entity or nil.
nil|err: nil if successful, or an error message if it fails.

Usage

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

kong.client.get_consumer()

Returns the consumer entity of the currently authenticated consumer. If not set yet, it returns nil.

Phases

access, header_filter, response, body_filter, log

Returns

table: The authenticated consumer entity.

Usage

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)

Sets the authenticated consumer and/or credential as well as the authenticated consumer-group for the current request. While both consumer and credential can be nil, at least one of them must exist. Otherwise, this function will throw an error.

Phases

access

Parameters

consumer (table|nil): The consumer to set. If no value is provided, then any existing value will be cleared.
credential (table|nil): The credential to set. If no value is provided, then any existing value will be cleared.

Usage

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

kong.client.set_authenticated_consumer_groups(groups)

Explicitly sets the authenticated consumer groups for the current request. Throws an error if the groups parameter is neither a table nor nil.

Phases

auth_and_later

Parameters

groups (table|nil): The consumer groups to set. If no value is provided, then any existing value will be cleared. This value should be a sequence-like table of tables, with each item having at least an id and a name.

Usage

kong.client.set_authenticated_consumer_groups({
  {
    id = "fed2bf38-10c4-404e-8d45-a2b0f521464d",
    name = "my-group",
  },
  {
    id = "736bb9d9-98f2-46d5-97fc-d7361d9488ee",
    name = "my-other-group",
  }
})

kong.client.get_consumer_group()

This function is deprecated in favor of get_consumer_groups. Retrieves the authenticated consumer group for the current request.

Phases

auth_and_later

Returns

table|nil: The authenticated consumer group. Returns nil if no consumer group has been authenticated for the current request.

Usage

local group = kong.client.get_consumer_group()

kong.client.authenticate_consumer_group_by_consumer_id(consumer_id)

Sets the consumer group for the current request based on the provided consumer id. If the consumer_id is neither a string nor nil, it throws an error. If the consumer group has already been authenticated, it doesn’t override the group. The function performs a redis-SCAN-like lookup using a subset of the cache_key. The consumer_group_mapping is sorted by group name for deterministic behavior, but this might be changed in future releases.

Phases

access

Parameters

consumer_id (string|nil): The consumer id to use for setting the consumer group. If no value is provided, the current consumer group is not changed.

Usage

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

kong.client.get_protocol([allow_terminated])

Returns the protocol matched by the current route ("http", "https", "tcp" or "tls"), or nil, if no route has been matched, which can happen when dealing with erroneous requests.

Phases

access, header_filter, response, body_filter, log

Parameters

allow_terminated (boolean, optional): If set, the X-Forwarded-Proto header is checked when checking for HTTPS.

Returns

string|nil: Can be one of "http", "https", "tcp", "tls" or nil.
nil|err: nil if successful, or an error message if it fails.

Usage

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