The plugin requests, but does not require the client certificate. No validation
of the client certificate is performed. If a client certificate exists,
the plugin makes the certificate available to other plugins acting on this request.
This plugin must be used in conjunction with the TLS Metadata Headers plugin.
This plugin is compatible with DB-less mode.
In DB-less mode, you configure Kong Gateway
Therefore, the Admin API is mostly read-only. The only tasks it can perform are all
related to handling the declarative config, including:
- Setting a target's health status in the load balancer
- Validating configurations against schemas
- Uploading the declarative configuration using the
Example plugin configuration
Here's a list of all the parameters which can be used in this plugin's configuration:
|The name of the plugin, in this case
|The name or ID of the service the plugin targets.
Set one of these parameters if adding the plugin to a service through the top-level
Not required if using
|The name or ID of the route the plugin targets.
Set one of these parameters if adding the plugin to a route through the top-level
Not required if using
|Whether this plugin will be applied.
Indicates the TLS handshake preference. The only option is
requests the client certificate.
Client certificate request
Client certificates are requested in the
ssl_certificate_by_lua phase where Kong Gateway does not
have access to
workspace information. Due to this information gap, Kong Gateway asks for
the client certificate on every handshake if the
tls-handshake-modifier plugin is configured on any route or service.
In most cases, the failure of the client to present a client certificate doesn’t affect subsequent
proxying if that route or service does not have the
tls-handshake-modifier plugin applied. The exception is where
the client is a desktop browser, which prompts the end user to choose the client cert to send and
leads to user experience issues rather than proxy behavior problems.
To improve this situation, Kong builds an in-memory map of SNIs from the configured Kong Gateway routes that should present a client
certificate. To limit client certificate requests during a handshake while ensuring the client
certificate is requested when needed, the in-memory map is dependent on all the routes in
Kong Gateway having the SNIs attribute set. When no routes have SNIs set, Kong Gateway must request
the client certificate during every TLS handshake:
- On every request irrespective of workspace when the plugin is enabled in global workspace scope.
- On every request irrespective of workspace when the plugin is applied at the service level
and one or more of the routes do not have SNIs set.
- On every request irrespective of workspace when the plugin is applied at the route level
and one or more routes do not have SNIs set.
- On specific requests only when the plugin is applied at the route level and all routes have SNIs set.
The result is all routes must have SNIs if you want to restrict the handshake request
for client certificates to specific requests.