Configuration
This plugin is compatible with DB-less mode.
Compatible protocols
The Mutual TLS Authentication plugin is compatible with the following protocols:
grpc
, grpcs
, http
, https
Parameters
Here's a list of all the parameters which can be used in this plugin's configuration:
-
name
string requiredThe name of the plugin, in this case
mtls-auth
. -
instance_name
stringAn optional custom name to identify an instance of the plugin, for example
mtls-auth_my-service
. Useful when running the same plugin in multiple contexts, for example, on multiple services. -
service.name or service.id
stringThe 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
/plugins
endpoint. Not required if using/services/SERVICE_NAME|ID/plugins
. -
route.name or route.id
stringThe 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
/plugins
endpoint. Not required if using/routes/ROUTE_NAME|ID/plugins
. -
enabled
boolean default:true
Whether this plugin will be applied.
-
config
record required-
anonymous
stringAn optional string (consumer UUID or username) value to use as an “anonymous” consumer if authentication fails. If empty (default null), the request fails with an authentication failure
4xx
. Note that this value must refer to the consumerid
orusername
attribute, and not itscustom_id
.
-
consumer_by
array of typestring
default:username, custom_id
Must be one of:username
,custom_id
Whether to match the subject name of the client-supplied certificate against consumer’s
username
and/orcustom_id
attribute. If set to[]
(the empty array), then auto-matching is disabled.
-
ca_certificates
array of typestring
requiredList of CA Certificates strings to use as Certificate Authorities (CA) when validating a client certificate. At least one is required but you can specify as many as needed. The value of this array is comprised of primary keys (
id
).
-
cache_ttl
number required default:60
Cache expiry time in seconds.
-
skip_consumer_lookup
boolean required default:false
Skip consumer lookup once certificate is trusted against the configured CA list.
-
allow_partial_chain
boolean required default:false
Allow certificate verification with only an intermediate certificate. When this is enabled, you don’t need to upload the full chain to Kong Certificates.
-
authenticated_group_by
string default:CN
Must be one of:CN
,DN
Certificate property to use as the authenticated group. Valid values are
CN
(Common Name) orDN
(Distinguished Name). Onceskip_consumer_lookup
is applied, any client with a valid certificate can access the Service/API. To restrict usage to only some of the authenticated users, also add the ACL plugin (not covered here) and create allowed or denied groups of users.
-
revocation_check_mode
string default:IGNORE_CA_ERROR
Must be one of:SKIP
,IGNORE_CA_ERROR
,STRICT
Controls client certificate revocation check behavior. If set to
SKIP
, no revocation check is performed. If set toIGNORE_CA_ERROR
, the plugin respects the revocation status when either OCSP or CRL URL is set, and doesn’t fail on network issues. If set toSTRICT
, the plugin only treats the certificate as valid when it’s able to verify the revocation status.
-
http_timeout
number default:30000
HTTP timeout threshold in milliseconds when communicating with the OCSP server or downloading CRL.
-
cert_cache_ttl
number default:60000
The length of time in milliseconds between refreshes of the revocation check status cache.
-
send_ca_dn
boolean default:false
Sends the distinguished names (DN) of the configured CA list in the TLS handshake message.
-
http_proxy_host
stringA string representing a host name, such as example.com.
-
http_proxy_port
integer between:0
65535
An integer representing a port number between 0 and 65535, inclusive.
-
https_proxy_host
stringA string representing a host name, such as example.com.
-
https_proxy_port
integer between:0
65535
An integer representing a port number between 0 and 65535, inclusive.
-