You are browsing documentation for an outdated plugin version.
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 or plugin
string requiredThe name of the plugin, in this case
mtls-auth
.- If using the Kong Admin API, Konnect API, declarative configuration, or decK files, the field is
name
. - If using the KongPlugin object in Kubernetes, the field is
plugin
.
- If using the Kong Admin API, Konnect API, declarative configuration, or decK files, the field is
-
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/{serviceName|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/{routeName|Id}/plugins
. -
enabled
boolean default:true
Whether this plugin will be applied.
-
config
record required-
anonymous
stringAn optional string (consumer UUID) value to use as an “anonymous” consumer if authentication fails. If the request is left empty (which it is by default), it fails with an authentication failure of either
HTTP 495
if the client presented a certificate that is not acceptable, orHTTP 496
if the client failed to present certificate as requested. Please note that this value must refer to the consumerid
attribute, which is internal to Kong, 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.
-
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
Known Issue: The default value
IGNORE_CA_ERROR
has a known issue in versions 1.5.0.0 and later.m As a workaround, manually set the value toSKIP
.Controls client certificate revocation check behavior. Valid values are
SKIP
,IGNORE_CA_ERROR
, orSTRICT
. If set toSKIP
, 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, and a missing OCSP or CRL URL in the certificate or a failure to connect to the server results in a revoked status. If both OCSP and CRL URL are set, the plugin always checks OCSP first, and only checks the CRL URL if it can’t communicate with the OCSP server.
-
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.
-