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.

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 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"

Back to top

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:

• trusted_ips
• real_ip_header
• real_ip_recursive

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

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

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:

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

Back to top

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

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)

Back to top

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

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

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

Usage

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

Back to top