You are browsing documentation for an outdated version. 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.

kong.client.get_ip()

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

Phases

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

Returns

string ip The remote 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 ip The remote 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: assuming 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 will always return the port of the client directly connecting to Kong. That is, in cases when a load balancer is in front of Kong, this function will return 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: assuming 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. Will look up the consumer by id, and optionally will 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, then if the consumer was not found by id, then a second search by username will be performed

Returns

table|nil consumer entity or nil
nil|err nil if success, or error message if failure

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 for the current request. While both consumer and credential can be nil, it is required that at least one of them exists. Otherwise this function will throw an error.

Phases

access

Parameters

consumer (table|nil): The consumer to set. Note: if no value is provided, then any existing value will be cleared!
credential (table|nil): The credential to set. Note: 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.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 will be checked when checking for https

Returns

string|nil "http", "https", "tcp", "tls" or nil
nil|err nil if success, or error message if failure

Usage

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