kong-plugin-mtls-auth is an Open Source plugin for Kong which authenticates clients using mTLS. It is similar (but simpler) than the mTLS plugin provided in Kong Enterprise edition.
Information extracted from the mTLS client certificate can be made available using headers for the upstream service, or used by other plugins (such as the kong-plugin-mtls-acl plugins) to further limit access.
The implementation of this plugin was inspired by the mtls-validate plugin.
If you're using luarocks execute the following:
luarocks install kong-plugin-mtls-auth
You also need to set the KONG_PLUGINS environment variable
export KONG_PLUGINS=mtls-auth
Configure nginx to use verify client certificate in kong.conf:
nginx_proxy_ssl_client_certificate = /path/to/rootCA.crt
nginx_proxy_ssl_verify_client = on
To enable the plugin only for one service:
curl -X POST http://localhost:8001/services/{ID}/plugins \
--data "name=mtls-auth" \
--data "config.upstream_cert_cn_header=X-Client-Cert-San"
To enable the plugin using declarative config in kong.yml:
plugins:
- name: mtls-auth
config:
upstream_cert_cn_header: "X-Client-Cert-San"
| Parameter | Default | Required | Description |
|---|---|---|---|
error_response_code |
401 | false | Response code to return if client certificate validation fails |
upstream_cert_header |
false | HTTP header name in which the client certificate in PEM format (urlencoded) will be made available to the upstream service | |
upstream_cert_fingerprint_header |
false | HTTP header name in which the client certificate fingerprint will be made available to the upstream service | |
upstream_cert_serial_header |
false | HTTP header name in which the client certificate serial number will be made available to the upstream service | |
upstream_cert_i_dn_header |
false | HTTP header name in which the client certificate issuer DN will be made available to the upstream service | |
upstream_cert_s_dn_header |
false | HTTP header name in which the client certificate subject DN will be made available to the upstream service | |
upstream_cert_cn_header |
false | HTTP header name in which the client certificate Common Name will be made available to the upstream service | |
upstream_cert_org_header |
false | HTTP header name in which the client certificate Organization will be made available to the upstream service |
Copyright 2023 Björn Beskow, Callista Enterprise AB
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.