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.

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:

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

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:

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

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

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)

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