kong.client

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

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

• ip The remote address of the client making the request

Usage

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:

• real_ip_header

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

Back to top

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

Back to top

• real_ip_header

Phases

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

Returns

• number The remote client port, considering forwarded ports

Usage

Back to top

kong.client.get_credential()

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

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
end

Back to top

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

1. table|nil consumer entity or nil

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

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

Back to top

kong.client.authenticate(consumer, credential)

Sets the authenticated consumer and/or credential for the current request. While both consumer and credential can be , 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)

Back to top

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

1. string|nil "http", "https", "tcp", "tls" or nil

2. nil|err nil if success, or error message if failure

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

Back to top