Skip to content
Kong Logo | Kong Docs Logo
search
  • We're Hiring!
  • Docs
    • Kong Gateway
    • Kong Konnect
    • Kong Mesh
    • Plugin Hub
    • decK
    • Kubernetes Ingress Controller
    • Insomnia
    • Kuma

    • Docs contribution guidelines
  • Plugin Hub
  • Support
  • Community
  • Kong Academy
Get a Demo Start Free Trial
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Plugin Hub
  • decK
  • Kubernetes Ingress Controller
  • Insomnia
  • Kuma

  • Docs contribution guidelines
  • 3.3.x (latest)
  • 3.2.x
  • 3.1.x
  • 3.0.x
  • 2.8.x
  • 2.7.x
  • 2.6.x
  • Older Enterprise versions (2.1-2.5)
  • Older OSS versions (2.1-2.5)
  • Archive (pre-2.1)

github-edit-pageEdit this page

report-issueReport an issue

enterprise-switcher-iconSwitch to OSS

On this pageOn this page
  • kong.client.get_ip()
  • kong.client.get_forwarded_ip()
  • kong.client.get_port()
  • kong.client.get_forwarded_port()
  • kong.client.get_credential()
  • kong.client.load_consumer(consumer_id[, search_by_username])
  • kong.client.get_consumer()
  • kong.client.authenticate(consumer, credential)
  • kong.client.get_protocol([allow_terminated])
Kong Gateway
3.2.x
  • Home
  • Kong Gateway
  • Plugin Development
  • PDK
  • kong.client
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"
Thank you for your feedback.
Was this page useful?
  • Kong
    THE CLOUD CONNECTIVITY COMPANY

    Kong powers reliable digital connections across APIs, hybrid and multi-cloud environments.

    • Company
    • Customers
    • Events
    • Investors
    • Careers Hiring!
    • Partners
    • Press
    • Contact
  • Products
    • Kong Konnect
    • Kong Gateway
    • Kong Mesh
    • Get Started
    • Pricing
  • Resources
    • eBooks
    • Webinars
    • Briefs
    • Blog
    • API Gateway
    • Microservices
  • Open Source
    • Install Kong Gateway
    • Kong Community
    • Kubernetes Ingress
    • Kuma
    • Insomnia
  • Solutions
    • Decentralize
    • Secure & Govern
    • Create a Dev Platform
    • API Gateway
    • Kubernetes
    • Service Mesh
Star
  • Terms•Privacy
© Kong Inc. 2023