kong.client package

Submodules

kong.client.tls module

class kong.client.tls.tls

Bases: object

static disable_session_reuse() → Tuple[bool, str]

Prevents the TLS session for the current connection from being reused by disabling the session ticket and session ID for the current TLS connection.

Phases:

certificate

Example:

res, err = kong.client.tls.disable_session_reuse()

if not res:

# do something with err

Returns:

Returns true if successful, nil if it fails.

Return type:

bool

Returns:

Returns nil if successful, or an error message if it fails.

Return type:

err

static get_full_client_certificate_chain() → Tuple[str, str]

Returns the PEM encoded downstream client certificate chain with the client certificate at the top and intermediate certificates (if any) at the bottom.

Phases:

rewrite, access, balancer, header_filter, body_filter, log

Example:

cert, err = kong.client.tls.get_full_client_certificate_chain()

if err:

# do something with errif not cert:

# client did not complete mTLS# do something with cert

Returns:

Returns a PEM-encoded client certificate if the mTLS handshake was completed, or nil if an error occurred or the client did not present its certificate.

Return type:

str

Returns:

Returns nil if successful, or an error message if it fails.

Return type:

err

static request_client_certificate(ca_certs: Any | None) → Tuple[bool, str]

Requests the client to present its client-side certificate to initiate mutual TLS authentication between server and client. This function requests, but does not require the client to start the mTLS process. The TLS handshake can still complete even if the client doesn’t present a client certificate. However, in that case, it becomes a TLS connection instead of an mTLS connection, as there is no mutual authentication. To find out whether the client honored the request, use get_full_client_certificate_chain in later phases. The ca_certs argument is the optional CA certificate chain opaque pointer, which can be created by the [parse_pem_cert](https://github.com/openresty/lua-resty-core/blob/master/lib/ngx/ssl.md#parse_pem_cert) or [resty.opensslx509.chain](https://github.com/fffonion/lua-resty-openssl#restyopensslx509chain) The Distinguished Name (DN) list hints of the CA certificates will be sent to clients. If omitted, will not send any DN list to clients.

Phases:

certificate

Example:

x509_lib = require “resty.openssl.x509”

chain_lib = require “resty.openssl.x509.chain”

res, err

chain = chain_lib.new()

# err check

x509, err = x509_lib.new(pem_cert, “PEM”)

# err check

res, err = chain:add(x509)

# err check

# chain.ctx is the raw data of the chain, i.e. STACK_OF(X509) *

res, err = kong.client.tls.request_client_certificate(chain.ctx)

if not res:

# do something with err

Parameters:

ca_certs (cdata) – The CA certificate chain opaque pointer

Returns:

Returns true if successful, or nil if it fails.

Return type:

bool

Returns:

Returns nil if successful, or an error message if it fails.

Return type:

err

static set_client_verify() → None

Overrides the client’s verification result generated by the log serializer. By default, the request.tls.client_verify field inside the log generated by Kong’s log serializer is the same as the [$ssl_client_verify](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#var_ssl_client_verify) Nginx variable. Only “SUCCESS”, “NONE”, or “FAILED:<reason>” are accepted values. This function does not return anything on success, and throws a Lua error in case of a failure.

Phases:

rewrite, access, balancer

Example:

kong.client.tls.set_client_verify(“FAILED:unknown CA”)

Module contents

class kong.client.client

Bases: object

static authenticate(consumer: table, credential: table) → None

Sets the authenticated consumer and/or credential as well as the authenticated consumer-group 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

Example:

# assuming credential and consumer have been set by some authentication code

kong.client.authenticate(consumer, credentials)

Parameters:

• consumer (table) – The consumer to set. If no value is provided, then any existing value will be cleared.

• credential (table) – The credential to set. If no value is provided, then any existing value will be cleared.

static authenticate_consumer_group_by_consumer_id(consumer_id: str) → None

If the consumer_id is neither a string nor nil, it throws an error. If the consumer group has already been authenticated, it doesn’t override the group. The function performs a redis-SCAN-like lookup using a subset of the cache_key. The consumer_group_mapping is sorted by group name for deterministic behavior, but this might be changed in future releases.

Phases:

access

Example:

# assuming consumer_id is provided by some code

kong.client.authenticate_consumer_group_by_consumer_id(consumer_id)

Parameters:

consumer_id (str) – The consumer id to use for setting the consumer group. If no value is provided, the current consumer group is not changed.

static get_consumer() → table

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

Phases:

access, header_filter, response, body_filter, log

Example:

consumer = kong.client.get_consumer()

if consumer:

consumer_id = consumer.id

else:

# request not authenticated yet, or a credential

# without a consumer (external auth)

Returns:

The authenticated consumer entity.

Return type:

table

static get_consumer_group() → table

This function is deprecated in favor of get_consumer_groups. Retrieves the authenticated consumer group for the current request.

Phases:

auth_and_later

Example:

group = kong.client.get_consumer_group()

Returns:

The authenticated consumer group. Returns nil if no consumer group has been authenticated for the current request.

Return type:

table

static get_consumer_groups() → table

Retrieves the authenticated consumer groups for the current request.

Phases:

auth_and_later

Example:

groups = kong.client.get_consumer_groups()

Returns:

The authenticated consumer groups. Returns nil if no consumer groups has been authenticated for the current request.

Return type:

table

static get_credential() → str

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

Phases:

access, header_filter, response, body_filter, log

Example:

credential = kong.client.get_credential()

if credential:

consumer_id = credential.consumer_id

else:

# request not authenticated yet

Returns:

The authenticated credential.

Return type:

str

static get_forwarded_ip() → str

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](https://docs.konghq.com/gateway/latest/reference/configuration/#trusted_ips) * [real_ip_header](https://docs.konghq.com/gateway/latest/reference/configuration/#real_ip_header) * [real_ip_recursive](https://docs.konghq.com/gateway/latest/reference/configuration/#real_ip_recursive)

Phases:

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

Example:

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

Returns:

The remote IP address of the client making the request, considering forwarded addresses.

Return type:

str

static get_forwarded_port() → number

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](https://docs.konghq.com/gateway/latest/reference/configuration/#trusted_ips) * [real_ip_header](https://docs.konghq.com/gateway/latest/reference/configuration/#real_ip_header) * [real_ip_recursive](https://docs.konghq.com/gateway/latest/reference/configuration/#real_ip_recursive)

Phases:

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

Example:

# [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.

Returns:

The remote client port, considering forwarded ports.

Return type:

number

static get_ip() → str

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

Example:

# 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”

Returns:

The remote IP address of the client making the request.

Return type:

str

static get_port() → number

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

Example:

# [client]:40000 <-> 80:[balancer]:30000 <-> 80:[kong]:20000 <-> 80:[service]

kong.client.get_port() # 30000

Returns:

The remote client port.

Return type:

number

static get_protocol(allow_terminated: bool | None) → Tuple[str, str]

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

Example:

kong.client.get_protocol() # “http”

Parameters:

allow_terminated (bool) – If set, the X-Forwarded-Proto header is checked when checking for HTTPS.

Returns:

Can be one of “http”, “https”, “tcp”, “tls” or nil.

Return type:

str

Returns:

nil if successful, or an error message if it fails.

Return type:

err

static load_consumer(consumer_id: str, search_by_username: bool | None) → Tuple[table, str]

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

Example:

consumer_id = “john_doe”

consumer = kong.client.load_consumer(consumer_id, true)

Parameters:

• consumer_id (str) – The consumer ID to look up.

• search_by_username (bool) – If truthy, and if the consumer is not found by ID, then a second search by username will be performed.

Returns:

Consumer entity or nil.

Return type:

table

Returns:

nil if successful, or an error message if it fails.

Return type:

err

static set_authenticated_consumer_group(group: table) → None

This function is deprecated in favor of set_authenticated_consumer_groups. Explicitly sets the authenticated consumer group for the current request. Throws an error if the group is neither a table nor nil.

Phases:

auth_and_later

Example:

# assuming group is provided by some code

kong.client.set_authenticated_consumer_group(group)

Parameters:

group (table) – The consumer group to set. If no value is provided, then any existing value will be cleared. this value should be a table with metadata of the group like its id and name.

static set_authenticated_consumer_groups(groups: table) → None

Explicitly sets the authenticated consumer groups for the current request. Throws an error if the groups parameter is neither a table nor nil.

Phases:

auth_and_later

Example:

kong.client.set_authenticated_consumer_groups({

{

id = “fed2bf38-10c4-404e-8d45-a2b0f521464d”,

name = “my-group”,

},

{

id = “736bb9d9-98f2-46d5-97fc-d7361d9488ee”,

name = “my-other-group”,

}

})

Parameters:

groups (table) – The consumer groups to set. If no value is provided, then any existing value will be cleared. This value should be a sequence-like table of tables, with each item having at least an id and a name.

class tls

Bases: object

static disable_session_reuse() → Tuple[bool, str]

Prevents the TLS session for the current connection from being reused by disabling the session ticket and session ID for the current TLS connection.

Phases:

certificate

Example:

res, err = kong.client.tls.disable_session_reuse()

if not res:

# do something with err

Returns:

Returns true if successful, nil if it fails.

Return type:

bool

Returns:

Returns nil if successful, or an error message if it fails.

Return type:

err

static get_full_client_certificate_chain() → Tuple[str, str]

Returns the PEM encoded downstream client certificate chain with the client certificate at the top and intermediate certificates (if any) at the bottom.

Phases:

rewrite, access, balancer, header_filter, body_filter, log

Example:

cert, err = kong.client.tls.get_full_client_certificate_chain()

if err:

# do something with errif not cert:

# client did not complete mTLS# do something with cert

Returns:

Returns a PEM-encoded client certificate if the mTLS handshake was completed, or nil if an error occurred or the client did not present its certificate.

Return type:

str

Returns:

Returns nil if successful, or an error message if it fails.

Return type:

err

static request_client_certificate(ca_certs: Any | None) → Tuple[bool, str]

Requests the client to present its client-side certificate to initiate mutual TLS authentication between server and client. This function requests, but does not require the client to start the mTLS process. The TLS handshake can still complete even if the client doesn’t present a client certificate. However, in that case, it becomes a TLS connection instead of an mTLS connection, as there is no mutual authentication. To find out whether the client honored the request, use get_full_client_certificate_chain in later phases. The ca_certs argument is the optional CA certificate chain opaque pointer, which can be created by the [parse_pem_cert](https://github.com/openresty/lua-resty-core/blob/master/lib/ngx/ssl.md#parse_pem_cert) or [resty.opensslx509.chain](https://github.com/fffonion/lua-resty-openssl#restyopensslx509chain) The Distinguished Name (DN) list hints of the CA certificates will be sent to clients. If omitted, will not send any DN list to clients.

Phases:

certificate

Example:

x509_lib = require “resty.openssl.x509”

chain_lib = require “resty.openssl.x509.chain”

res, err

chain = chain_lib.new()

# err check

x509, err = x509_lib.new(pem_cert, “PEM”)

# err check

res, err = chain:add(x509)

# err check

# chain.ctx is the raw data of the chain, i.e. STACK_OF(X509) *

res, err = kong.client.tls.request_client_certificate(chain.ctx)

if not res:

# do something with err

Parameters:

ca_certs (cdata) – The CA certificate chain opaque pointer

Returns:

Returns true if successful, or nil if it fails.

Return type:

bool

Returns:

Returns nil if successful, or an error message if it fails.

Return type:

err

static set_client_verify() → None

Overrides the client’s verification result generated by the log serializer. By default, the request.tls.client_verify field inside the log generated by Kong’s log serializer is the same as the [$ssl_client_verify](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#var_ssl_client_verify) Nginx variable. Only “SUCCESS”, “NONE”, or “FAILED:<reason>” are accepted values. This function does not return anything on success, and throws a Lua error in case of a failure.

Phases:

rewrite, access, balancer

Example:

kong.client.tls.set_client_verify(“FAILED:unknown CA”)