You are browsing unreleased documentation. See the latest documentation here.
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
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 ornil
. -
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 anid
and aname
.
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. Returnsnil
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, theX-Forwarded-Proto
header is checked when checking for HTTPS.
Returns
-
string|nil
: Can be one of"http"
,"https"
,"tcp"
,"tls"
ornil
. -
nil|err
:nil
if successful, or an error message if it fails.
Usage
kong.client.get_protocol() -- "http"