Document updated on Apr 10, 2020
Securing B2B communication with mTLS
Mutual TLS authentication (mTLS) is an authentication mechanism used traditionally in business-to-business (B2B) applications where clients provide a certificate that allows to connect to the KrakenD server.
The certificates must be recognized by your system’s Certification Authority (CA) or be added under the ca_certs list.
Configuring mutual authentication
From the configuration file perspective, Mutual TLS Authentication is no more than flag at the root level of the configuration.
When mTLS is enabled, all KrakenD endpoints require clients to provide a known client-side X.509 authentication certificate. KrakenD relies on the system’s CA to validate certificates.
To enable it you need to add enable_mtls to your tls configuration:
{
"version": 3,
"tls": {
"public_key": "/path/to/cert.pem",
"private_key": "/path/to/key.pem",
"enable_mtls": true,
"ca_certs": [
"./rootCA.pem"
]
}
}
Fields of TLS/SSL
ca_certsarray- An array with all the CA certificates you would like to load to KrakenD when using mTLS, in addition to the certificates present in the system’s CA.Example:
["ca.pem"]Defaults to[] cipher_suitesarray- The list of cipher suites
curve_preferencesarray- The list of all the identifiers for the curve preferences. Use
23for CurveP256,24for CurveP384,25for CurveP521,29for X25519.Defaults to[23,24,25] disable_system_ca_poolboolean- Make that any certificate in the system’s CA is not recognized by KrakenD. The only certificates loaded will be the ones in the
ca_certslist when true.Defaults tofalse disabledboolean- A flag to disable TLS (useful while in development).Defaults to
false enable_mtlsboolean- Whether to enable or not Mutual Authentication. When mTLS is enabled, all KrakenD endpoints require clients to provide a known client-side X.509 authentication certificate. KrakenD relies on the system’s CA to validate certificates.Defaults to
false max_version- Maximum TLS version supported.Possible values are:
"SSL3.0","TLS10","TLS11","TLS12","TLS13"Defaults to"TLS13" min_version- Minimum TLS version supported. When specifiying very old and insecure versions under TLS12 you must provide the
ciphers_list.Possible values are:"SSL3.0","TLS10","TLS11","TLS12","TLS13"Defaults to"TLS13" prefer_server_cipher_suitesboolean- Enforces the use of TLS versions and cipher suites configured, and blocks all traffic not in the range.Defaults to
false private_key* string- Absolute path to the private key, or relative to the current working directory.Examples:
"/path/to/key.pem","./certs/key.pem"Defaults to"./certs/key.pem" public_key* string- Absolute path to the public key, or relative to the current working directory.Examples:
"/path/to/cert.pem","./certs/cert.pem"Defaults to"./certs/cert.pem"
Connections not having a recognized certificate in KrakenD’s system CA, will be rejected. For further documentation on TLS, see the TLS documentation
mTLS example
To use mTLS you need to generate the client and server certificates. The following script example creates the needed files to enable mTLS. Notice that in the CN of the certificates we are adding localhost as we want to connect to KrakenD from and to localhost.
# Private key for the certificate authority
openssl genrsa -des3 -out rootCA.protected.key 2048
openssl rsa -in rootCA.protected.key -out rootCA.key
# Generate the CA
openssl req -x509 -new -nodes -key rootCA.key -sha256 -days 1024 -out rootCA.pem -subj "/C=US/ST=California/L=Mountain View/O=Your Organization/OU=Your Unit/CN=example.com"
# Generate a key for the client certificate
openssl genrsa -out client.key 2048
# Generate the certificate request for the client
openssl req -new -key client.key -out client.csr -subj "/C=US/ST=California/L=Mountain View/O=Your Organization/OU=Your Unit/CN=localhost"
# Sign the certificate request for the client
openssl x509 -req -in client.csr -extensions client -CA rootCA.pem -CAkey rootCA.key -CAcreateserial -out client.crt -days 500 -sha256
# Generate a key for the server certificate
openssl genrsa -out server.key 2048
# Generate the certificate request for the server
openssl req -new -key server.key -out server.csr -subj "/C=US/ST=California/L=Mountain View/O=Your Organization/OU=Your Unit/CN=localhost"
# Sign the certificate request for the server
openssl x509 -req -in server.csr -extensions server -CA rootCA.pem -CAkey rootCA.key -CAcreateserial -out server.crt -days 500 -sha256
The KrakenD configuration needed is as follows (no endpoints used for this demo):
{
"version": 3,
"$schema": "https://www.krakend.io/schema/v2.1/krakend.json",
"port": 443,
"tls": {
"public_key": "./server.crt",
"private_key": "./server.key",
"enable_mtls": true,
"ca_certs": [
"./rootCA.pem"
],
"disable_system_ca_pool": true
}
}
At this moment KrakenD accepts only clients passing a valid certificate. Let’s connect to the /__health endpoint:
Connect using mTLS
$curl \
--cacert rootCA.pem \
--key client.key \
--cert client.crt \
https://localhost/__health
{"agents":{},"now":"2022-11-07 11:43:53.444657401 +0000 UTC m=+25.777003978","status":"ok"}If we don’t provide the valid certs we get an error instead:
Connect without valid certs
$curl -k https://localhost/__health
curl: (56) OpenSSL SSL_read: error:14094412:SSL routines:ssl3_read_bytes:sslv3 alert bad certificate, errno 0
