Add mutual TLS authentication based on client-supplied certificate and configured trusted CA list. Automatically maps certificates to Consumers based on the common name field.
Configuration Reference
Enable the plugin on a service
Admin API
Kubernetes
Declarative (YAML)
Konnect Cloud
Kong Manager
For example, configure this plugin on a service by
making the following request:
curl -X POST http://{HOST}:8001/services/{SERVICE}/plugins \
--data "name=mtls-auth" \
--data "config.ca_certificates=`[ { "id": "fdac360e-7b19-4ade-a553-6dd22937c82f" }, { "id": "aabc360e-7b19-5aab-1231-6da229a7b82f"} ]`"
SERVICE
is the id
or name
of the service that this plugin
configuration will target.
First, create a KongPlugin
resource:
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
name: <mtls-auth-example>
config:
ca_certificates: `[ { "id": "fdac360e-7b19-4ade-a553-6dd22937c82f" }, { "id": "aabc360e-7b19-5aab-1231-6da229a7b82f"} ]`
plugin: mtls-auth
Next, apply the KongPlugin resource to a
Service by annotating the
Service as follows:
apiVersion: v1
kind: Service
metadata:
name: {SERVICE}
labels:
app: {SERVICE}
annotations:
konghq.com/plugins: <mtls-auth-example>
spec:
ports:
- port: 80
targetPort: 80
protocol: TCP
name: {SERVICE}
selector:
app: {SERVICE}
{SERVICE}
is the id
or name
of the service that this plugin
configuration will target.
Note: The KongPlugin resource only needs to be defined once
and can be applied to any service, consumer, or route in the namespace. If you
want the plugin to be available cluster-wide, create the resource as a
KongClusterPlugin
instead of KongPlugin
.
For example, configure this plugin on a service by
adding this section to your declarative configuration file:
plugins:
- name: mtls-auth
service: {SERVICE}
config:
ca_certificates: `[ { "id": "fdac360e-7b19-4ade-a553-6dd22937c82f" }, { "id": "aabc360e-7b19-5aab-1231-6da229a7b82f"} ]`
SERVICE
is the id
or name
of the service that this plugin
configuration will target.
Configure this plugin on a service:
- In Konnect Cloud, select the service on the ServiceHub page.
- Scroll down to Versions and select the version.
- Scroll down to Plugins and click New Plugin.
- Find and select the Mutual TLS Authentication plugin.
-
Enter the following parameters, updating the default
or sample values as needed:
- Config.Ca Certificates:
[ { "id": "fdac360e-7b19-4ade-a553-6dd22937c82f" }, { "id": "aabc360e-7b19-5aab-1231-6da229a7b82f"} ]
- Click Create.
Configure this plugin on a service:
- In Kong Manager, select the workspace.
- From the Dashboard, scroll down to Services and click View for the
service row.
- Scroll down to plugins and click Add Plugin.
-
Find and select the Mutual TLS Authentication plugin.
Note: If the plugin is greyed out, then it is not available
for your product tier. See
Kong Gateway tiers.
- If the option is available, select Scoped.
- Add the service name and ID to the Service field if it
is not already prefilled.
-
Enter the following parameters, updating the default or sample values as needed:
- Config.Ca Certificates:
[ { "id": "fdac360e-7b19-4ade-a553-6dd22937c82f" }, { "id": "aabc360e-7b19-5aab-1231-6da229a7b82f"} ]
- Click Create.
Enable the plugin on a route
Admin API
Kubernetes
Declarative (YAML)
Konnect Cloud
Kong Manager
For example, configure this plugin on a route with:
$ curl -X POST http://{HOST}:8001/routes/{ROUTE}/plugins \
--data "name=mtls-auth" \
--data "config.ca_certificates=`[ { "id": "fdac360e-7b19-4ade-a553-6dd22937c82f" }, { "id": "aabc360e-7b19-5aab-1231-6da229a7b82f"} ]`"
ROUTE
is the id
or name
of the route that this plugin configuration
will target.
First, create a KongPlugin
resource:
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
name: <mtls-auth-example>
config:
ca_certificates: `[ { "id": "fdac360e-7b19-4ade-a553-6dd22937c82f" }, { "id": "aabc360e-7b19-5aab-1231-6da229a7b82f"} ]`
plugin: mtls-auth
Then, apply it to an ingress (Route or Routes)
by annotating the ingress as follows:
apiVersion: networking/v1beta1
kind: Ingress
metadata:
name: {ROUTE}
annotations:
kubernetes.io/ingress.class: kong
konghq.com/plugins: <mtls-auth-example>
spec:
rules:
- host: examplehostname.com
http:
paths:
- path: /bar
backend:
serviceName: echo
servicePort: 80
ROUTE
is the id
or name
of the route that this plugin configuration
will target.
Note: The KongPlugin resource only needs to be defined once
and can be applied to any service, consumer, or route in the namespace. If you
want the plugin to be available cluster-wide, create the resource as a
KongClusterPlugin
instead of KongPlugin
.
For example, configure this plugin on a route by
adding this section to your declarative configuration file:
plugins:
- name: mtls-auth
route: <route>
config:
ca_certificates: `[ { "id": "fdac360e-7b19-4ade-a553-6dd22937c82f" }, { "id": "aabc360e-7b19-5aab-1231-6da229a7b82f"} ]`
ROUTE
is the id
or name
of the route that this plugin configuration
will target.
Configure this plugin on a route:
- In Konnect Cloud, select the service from the ServiceHub page.
- Scroll down to Versions and select the version.
- Select the route.
- Scroll down to Plugins and click Add Plugin.
- Find and select the Mutual TLS Authentication plugin.
-
Enter the following parameters, updating the default
or sample values as needed:
- Config.Ca Certificates:
[ { "id": "fdac360e-7b19-4ade-a553-6dd22937c82f" }, { "id": "aabc360e-7b19-5aab-1231-6da229a7b82f"} ]
- Click Create.
Configure this plugin on a route:
- In Kong Manager, select the workspace.
- From the Dashboard, select Routes in the left navigation.
- Click View for the route row.
- Scroll down to plugins and click Add Plugin.
-
Find and select the Mutual TLS Authentication plugin.
Note: If the plugin is greyed out, then it is not available
for your product tier. See
Kong Gateway tiers.
- If the option is available, select Scoped.
- Add the Route ID if it is not already prefilled.
-
Enter the following parameters, updating the default
or sample values as needed:
- Config.Ca Certificates:
[ { "id": "fdac360e-7b19-4ade-a553-6dd22937c82f" }, { "id": "aabc360e-7b19-5aab-1231-6da229a7b82f"} ]
- Click Create.
Enable the plugin globally
A plugin which is not associated to any service, route, or consumer is
considered global, and will be run on every request. Read the
Plugin Reference and the Plugin Precedence
sections for more information.
Admin API
Kubernetes
Declarative (YAML)
Kong Manager
For example, configure this plugin globally with:
$ curl -X POST http://{HOST}:8001/plugins/ \
--data "name=mtls-auth" \
--data "config.ca_certificates=`[ { "id": "fdac360e-7b19-4ade-a553-6dd22937c82f" }, { "id": "aabc360e-7b19-5aab-1231-6da229a7b82f"} ]`"
Create a KongClusterPlugin
resource and label it as global:
apiVersion: configuration.konghq.com/v1
kind: KongClusterPlugin
metadata:
name: <global-mtls-auth>
annotations:
kubernetes.io/ingress.class: kong
labels:
global: \"true\"
config:
ca_certificates: `[ { "id": "fdac360e-7b19-4ade-a553-6dd22937c82f" }, { "id": "aabc360e-7b19-5aab-1231-6da229a7b82f"} ]`
plugin: mtls-auth
For example, configure this plugin using the plugins:
entry in the declarative
configuration file:
plugins:
- name: mtls-auth
config:
ca_certificates: `[ { "id": "fdac360e-7b19-4ade-a553-6dd22937c82f" }, { "id": "aabc360e-7b19-5aab-1231-6da229a7b82f"} ]`
Configure this plugin globally:
- In Kong Manager, select the workspace.
- From the Dashboard, select Plugins in the left navigation.
- Click New Plugin.
-
Find and select the Mutual TLS Authentication plugin.
Note: If the plugin is greyed out, then it is not available
for your product tier. See
Kong Gateway tiers.
- If the option is available, set the plugin scope to Global.
-
Enter the following parameters, updating the
default/sample values as needed:
- Config.Ca Certificates:
[ { "id": "fdac360e-7b19-4ade-a553-6dd22937c82f" }, { "id": "aabc360e-7b19-5aab-1231-6da229a7b82f"} ]
- Click Create.
Parameters
Here's a list of all the parameters which can be used in this plugin's configuration:
Form Parameter |
Description |
name
required
Type: string |
The name of the plugin, in this case mtls-auth . |
service.id
Type: string |
The ID of the Service the plugin targets. |
route.id
Type: string |
The ID of the Route the plugin targets. |
enabled
required
Type: boolean
Default value: true |
Whether this plugin will be applied. |
config.anonymous
optional
|
An 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 will fail with an authentication failure of either HTTP 495 if the client presented a certificate that is not acceptable, or HTTP 496 if the client failed to present certificate as requested. Please note that this value must refer to the Consumer id attribute, which is internal to Kong, and not its custom_id .
|
config.consumer_by
optional
Default value: [ "username", "custom_id" ]
|
Whether to match the subject name of the client-supplied certificate against consumer’s username and/or custom_id attribute. If set to [] (the empty array) then auto-matching is disabled.
|
config.ca_certificates
required
|
List of “CA Certificates” object to use as Certificate Authorities (CA) when validating client certificate. At least one is required but can specify as many as needed. The value of this array comprises of primary keys for the “Certificate Authority” object.
|
config.cache_ttl
Default value: 60
|
Cache expiry time in seconds.
|
Usage
In order to authenticate the Consumer, it must provide a valid certificate and
complete mutual TLS handshake with Kong.
The plugin will validate the certificate provided against the configured CA list based on the requested Route or Service.
If the certificate is not trusted or has expired, the response will be HTTP 401
“TLS certificate failed verification.”
If Consumer did not present a valid certificate (this includes requests not sent to the HTTPS port),
then the response will be HTTP 401
“No required TLS certificate was sent”. That exception is if the config.anonymous
option was configured on the plugin, in which case the anonymous Consumer will be used
and the request will be allowed to proceed.
Adding certificate authorities
In order to use this plugin, you must add certificate authority certificates. These are stored in a separate ca-certificates store rather than the main certificates store, as they do not require private keys. To add one, obtain a PEM-encoded copy of your CA certificate and POST it to /ca_certificates
:
$ curl -sX POST https://kong:8001/ca_certificates -F cert=@cert.pem
{
"tags": null,
"created_at": 1566597621,
"cert": "-----BEGIN CERTIFICATE-----\FullPEMOmittedForBrevity==\n-----END CERTIFICATE-----\n",
"id": "322dce96-d434-4e0d-9038-311b3520f0a3"
}
The id
value returned can now be used for mTLS plugin configurations or consumer mappings.
Create manual mappings between certificate and Consumer object
Sometimes you may not wish to use automatic Consumer lookup or you have certificates
that contain a field value not associated with Consumer objects directly. In those
situations, you may manually assign one or more subject names to the Consumer object for
identifying the correct Consumer.
Note: “Subject names” refers to the certificate’s Subject Alternative Names (SAN) or
“Common Name” (CN). CN will only be used if the SAN extension does not exist.
$ curl -X POST http://kong:8001/consumers/{consumer}/mtls-auth \
-d 'subject_name=test@example.com'
HTTP/1.1 201 Created
{
"consumer": { "id": "876bf719-8f18-4ce5-cc9f-5b5af6c36007" },
"created_at": 1443371053000,
"subject_name": "test@example.com"
}
consumer
: The id
or username
property of the Consumer entity to associate the credentials to.
form parameter |
default |
description |
subject_name required |
|
The Subject Alternative Name (SAN) or Common Name (CN) that should be mapped to consumer (in that order of lookup). |
ca_certificate optional |
|
UUID of the Certificate Authority (CA) that the certificate has to be verifiable by for the mapping to success. This is to help distinguish multiple certificates with the same subject name but are issued under different CAs. If empty, the subject name will match certificates issued by any CA under the corresponding config.ca_certificates . |
Matching behaviors
Once a client certificate has been verified as valid, the Consumer object will be determined in the following order:
- Manual mappings with
subject_name
matching the certificate’s SAN or CN (in that order) and ca_certificate = <issuing authority of the client certificate>
- Manual mappings with
subject_name
matching the certificate’s SAN or CN (in that order) and ca_certificate = NULL
- If
config.consumer_by
is not null, Consumer with username
and/or id
matching the certificate’s SAN or CN (in that order)
- The
config.anonymous
consumer (if set)
Note: matching will stop as soon as the first successful match is found.
When a client has been authenticated, the plugin will append headers to the request before proxying it to the upstream service so that you can identify the Consumer in your code:
X-Consumer-ID
, the ID of the Consumer on Kong
X-Consumer-Custom-ID
, the custom_id
of the Consumer (if set)
X-Consumer-Username
, the username
of the Consumer (if set)
X-Credential-Username
, the username
of the Credential (only if the consumer is not the ‘anonymous’ consumer)
X-Anonymous-Consumer
will be set to true
if authentication failed and the ‘anonymous’ Consumer was set instead.
Troubleshooting
When authentication fails, the client does not have access to any details explaining the
failure. The security reason for this omission is to prevent malicious reconnaissance.
Instead, the details are recorded inside Kong’s error logs under the [mtls-auth]
filter.