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.

See also: nginx.org/en/docs/http/ngx_http_realip_module.html

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"

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:

• trusted_ips
• real_ip_header
• real_ip_recursive

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`.

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

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:

• trusted_ips
• real_ip_header
• real_ip_recursive

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`.

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

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

1. table|nil: Consumer entity or nil.

2. 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)

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

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)

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.
• opts (table|nil, optional): Options table, with the following fields: opts.mode - either “write” or “append”, write will replace any existing groups that are set, append will add to the existing groups.

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",
  }
})
-- assuming `group` is provided by some code
_CLIENT.set_authenticated_consumer_groups(group)

This function is deprecated in favor of set_authenticated_consumer_groups. Explicitly sets the authenticated consumer group for the current request. Throws an error if the group is neither a table nor nil.

Phases

• auth_and_later

Parameters

• group (table|nil): The consumer group to set. If no value is provided, then any existing value will be cleared. this value should be a table with metadata of the group like its id and name.

Usage

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

Retrieves the authenticated consumer groups for the current request.

Phases

• auth_and_later

Returns

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

Usage

local groups = kong.client.get_consumer_groups()

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

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)

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

1. string|nil: Can be one of "http", "https", "tcp", "tls" or nil.

2. nil|err: nil if successful, or an error message if it fails.

Usage

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

Returns the VPC ID of the endpoint in the PROXY protocol v2 header PP2_SUBTYPE_AWS_VPCE_ID. This function requires the user to enable proxy_protocol flag in the proxy_listen directive.

Note: once the flag proxy_protocol is enabled the listen port will only accept proxy protocol data from downstream.

Refer to the nginx doc (https://docs.nginx.com/nginx/admin-guide/load-balancer/using-proxy-protocol/) for more detailed information.

Phases

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

Returns

1. string|nil:

2. nil|err: nil if successful, or an error message if it fails.

Usage

kong.client.get_aws_vpce_id() -- a vpc id string