Skip to content
Kong Gateway 2.8 Increases Security and Simplifies API Management.  —Learn More →
|
search
Plugin Hub
header icon

Mutual TLS Authentication

You are browsing documentation for an outdated plugin version. See the latest documentation here.

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

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:

  1. In Konnect Cloud, select the service on the ServiceHub page.
  2. Scroll down to Versions and select the version.
  3. Scroll down to Plugins and click New Plugin.
  4. Find and select the Mutual TLS Authentication plugin.

  5. 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"} ]
  6. Click Create.

Configure this plugin on a service:

  1. In Kong Manager, select the workspace.
  2. From the Dashboard, scroll down to Services and click View for the service row.
  3. Scroll down to plugins and click Add Plugin.

  4. 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.
  5. If the option is available, select Scoped.
  6. Add the service name and ID to the Service field if it is not already prefilled.

  7. 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"} ]
  8. Click Create.

Enable the plugin on a route

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:

  1. In Konnect Cloud, select the service from the ServiceHub page.
  2. Scroll down to Versions and select the version.
  3. Select the route.
  4. Scroll down to Plugins and click Add Plugin.
  5. Find and select the Mutual TLS Authentication plugin.

  6. 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"} ]
  7. Click Create.

Configure this plugin on a route:

  1. In Kong Manager, select the workspace.
  2. From the Dashboard, select Routes in the left navigation.
  3. Click View for the route row.
  4. Scroll down to plugins and click Add Plugin.

  5. 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.
  6. If the option is available, select Scoped.
  7. Add the Route ID if it is not already prefilled.

  8. 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"} ]
  9. 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.

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:

  1. In Kong Manager, select the workspace.
  2. From the Dashboard, select Plugins in the left navigation.
  3. Click New Plugin.

  4. 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.
  5. If the option is available, set the plugin scope to Global.

  6. 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"} ]
  7. 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:

  1. Manual mappings with subject_name matching the certificate’s SAN or CN (in that order) and ca_certificate = <issuing authority of the client certificate>
  2. Manual mappings with subject_name matching the certificate’s SAN or CN (in that order) and ca_certificate = NULL
  3. If config.consumer_by is not null, Consumer with username and/or id matching the certificate’s SAN or CN (in that order)
  4. 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.