Tag 10: TLS
Ziel: Kong mit einem Zertifikat einer eigenen CA ausstatten, HTTPS für Schreiben und Admin API erzwingen, alte TLS-Versionen erkennen und das Backend über TLS mit geprüftem Zertifikat ansprechen. · Dauer: ca. 75 min · Voraussetzung: Tag 9
Briefing
- Kong beendet TLS am Proxy-Port 8443. Welches Zertifikat es zeigt, entscheidet der Hostname, den der Client im Handshake nennt (SNI).
- Ohne passendes Zertifikat zeigt Kong ein selbst erzeugtes
Standard-Zertifikat für
localhost. protocols: [https]an einer Route verbietet Klartext: HTTP bekommt 426.- Zum Backend spricht Kong HTTP oder HTTPS. Bei HTTPS prüft es das
Zertifikat nur mit
tls_verify: trueund einer CA, der es vertraut.
curl ──TLS (SNI api.kong.lab)──► Kong :8443 ──TLS, geprüft──► echo-tls:8080
Zertifikat api.kong.lab CA: Kong Lab CA
signiert von Kong Lab CA
Drill 1: Eine eigene CA
source ~/kong-lab/setup/env.sh
mkdir -p ~/kong-lab/tag10/tls && cd ~/kong-lab/tag10/tls
openssl req -x509 -newkey rsa:2048 -nodes -keyout ca.key -out ca.crt -days 365 \
-subj "/CN=Kong Lab CA" 2>/dev/null
openssl req -newkey rsa:2048 -nodes -keyout api.key -out api.csr \
-subj "/CN=api.kong.lab" 2>/dev/null
printf 'subjectAltName=DNS:api.kong.lab,DNS:localhost\nextendedKeyUsage=serverAuth\n' \
> api.ext
openssl x509 -req -in api.csr -CA ca.crt -CAkey ca.key -CAcreateserial \
-out api.crt -days 90 -extfile api.ext
openssl x509 -in api.crt -noout -subject -issuer -ext subjectAltNameErwartet:
Certificate request self-signature ok
subject=CN = api.kong.lab
subject=CN = api.kong.lab
issuer=CN = Kong Lab CA
X509v3 Subject Alternative Name:
DNS:api.kong.lab, DNS:localhost
Eine CA, ein Server-Zertifikat für zwei Namen, 90 Tage gültig.
Browser und curl achten auf subjectAltName,
nicht auf CN.
Fortschritt speichern? Kostenlos registrieren
Drill 2: Das Standard-Zertifikat
curl -s -o /dev/null -w '%{http_code}\n' https://localhost:8443/api/v1/version
echo "rc=$?"
curl -sk -o /dev/null -w '%{http_code}\n' https://localhost:8443/api/v1/version
echo | openssl s_client -connect localhost:8443 -servername api.kong.lab 2>/dev/null \
| openssl x509 -noout -issuerErwartet:
000
rc=60
200
issuer=C = US, ST = California, L = San Francisco, O = Kong, OU = IT Department, CN = …
Fehler 60: curl traut dem Zertifikat nicht. Mit
-k (prüfen abschalten) klappt es, aber das Zertifikat hat
Kong beim ersten Start selbst erzeugt. Für Clients ist es wertlos.
Fortschritt speichern? Kostenlos registrieren
Drill 3: Zertifikat und SNI
Zertifikat und Schlüssel kommen in deine kong.yaml. decK
verlangt für Zertifikate eine feste id, damit die SNIs
darauf verweisen können:
cat > tls.yaml <<EOF
certificates:
- id: $(cat /proc/sys/kernel/random/uuid)
cert: |
$(sed 's/^/ /' api.crt)
key: |
$(sed 's/^/ /' api.key)
snis:
- name: api.kong.lab
- name: localhost
EOF
head -3 tls.yaml
deck file merge ~/kong-lab/kong/kong.yaml tls.yaml -o ~/kong-lab/kong/kong.yaml
ksync 2>/dev/null | tail -3
curl -s --cacert ca.crt --resolve api.kong.lab:8443:127.0.0.1 \
https://api.kong.lab:8443/api/v1/version
curl -s --cacert ca.crt https://localhost:8443/api/v1/version
curl -s $ADMIN/snis | jq -r '.data[].name'Erwartet (gekürzt, die ID weicht bei dir ab):
certificates:
- id: 06e00ffb-721a-4a0e-b96b-17b4c19b32bf
cert: |
Created: 3
Updated: 0
Deleted: 0
0.2.0
0.3.0
api.kong.lab
localhost
--resolve lässt curl den Namen
api.kong.lab auf 127.0.0.1 auflösen, ohne
/etc/hosts zu ändern, und schickt ihn als SNI.
--cacert ca.crt statt -k: Jetzt prüft
curl wirklich.
Sicherheit: Deine
kong.yamlenthält jetzt einen privaten Schlüssel. Im Labor bleibt das lokale Git-Repository auf der VM. In Produktion gehört der Schlüssel in einen Vault, und Kong liest ihn per Referenz ({vault://…}).
Fortschritt speichern? Kostenlos registrieren
Drill 4: HTTPS erzwingen
Passwörter (admin-api) und Schlüssel
(notes-schreiben) sollen nie im Klartext reisen:
SEL='$..routes[?(@.name=="notes-schreiben" || @.name=="admin-api")]'
deck file patch -s ~/kong-lab/kong/kong.yaml --selector "$SEL" \
--value 'protocols:["https"]' -o ~/kong-lab/kong/kong.yaml
ksync 2>/dev/null | tail -1
H='Content-Type: application/json'
curl -s -w ' %{http_code}\n' -X POST -H 'apikey: lab-key-anna-456' -H "$H" \
-d '{"text":"http"}' $PROXY/api/v1/notes | tr -d '\n'; echo
curl -s -w ' %{http_code}\n' --cacert ca.crt -X POST -H 'apikey: lab-key-anna-456' \
-H "$H" -d '{"text":"per TLS"}' https://localhost:8443/api/v1/notes
curl -s -o /dev/null -w '%{http_code}\n' --cacert ca.crt -u anna:lab-user-pw-123 \
https://localhost:8443/admin-api/statusErwartet (gekürzt):
Deleted: 0
{ "message":"Please use HTTPS protocol", "request_id":"4ec2065a…"} 426
{"id":"c78656b2-…","text":"per TLS"}
201
200
426 heißt „Upgrade Required”. Wer stattdessen umleiten will, setzt an
der Route https_redirect_status_code: 301. Dann schickt
Kong einen Location-Header auf https://… ohne
Port, denn es kennt nur den Port, auf dem es im Container lauscht; in
Produktion steht Kong auf 443.
Fortschritt speichern? Kostenlos registrieren
Drill 5: Welche TLS-Versionen
curl -s $ADMIN | jq -c '.configuration | {ssl_protocols, ssl_cipher_suite}'
for v in tls1_2 tls1_3; do
echo | openssl s_client -$v -connect localhost:8443 -servername localhost 2>&1 \
| grep '^New, '
done
echo | openssl s_client -tls1_1 -cipher 'DEFAULT@SECLEVEL=0' -connect localhost:8443 \
2>&1 | grep -o 'tlsv1 alert protocol version'Erwartet:
{"ssl_protocols":"TLSv1.2 TLSv1.3","ssl_cipher_suite":"intermediate"}
New, TLSv1.2, Cipher is ECDHE-RSA-AES256-GCM-SHA384
New, TLSv1.3, Cipher is TLS_AES_256_GCM_SHA384
tlsv1 alert protocol version
intermediate folgt der Empfehlung von Mozilla: TLS 1.2
und 1.3 mit modernen Ciphers. Für TLS 1.1 musst du schon den eigenen
Client überreden (SECLEVEL=0), und dann lehnt Kong ab.
Stand festhalten:
cd ~/kong-lab/kong
git add kong.yaml
git commit -qm "Tag 10: Zertifikat, HTTPS für Schreiben und Admin API"Fortschritt speichern? Kostenlos registrieren
Drill 6: TLS zum Backend
Auch hinter dem Gateway kann ein Netz unsicher sein. Ein Echo-Dienst mit eigenem Zertifikat, signiert von deiner CA:
cd ~/kong-lab/tag10/tls
openssl req -newkey rsa:2048 -nodes -keyout echo-tls.key -out echo-tls.csr \
-subj "/CN=echo-tls" 2>/dev/null
printf 'subjectAltName=DNS:echo-tls\n' > echo.ext
openssl x509 -req -in echo-tls.csr -CA ca.crt -CAkey ca.key -CAcreateserial \
-out echo-tls.crt -days 90 -extfile echo.ext 2>/dev/null
chmod 644 echo-tls.key
docker run -d --name echo-tls --network lab -v $PWD:/tls:ro \
ghcr.io/mccutchen/go-httpbin:2.26.0 \
-https-cert-file /tls/echo-tls.crt -https-key-file /tls/echo-tls.key > /dev/null
sleep 2
docker logs echo-tls 2>&1 | tail -1 | grep -o 'listening on .*'Erwartet:
listening on https://0.0.0.0:8080"
Kong soll das Zertifikat prüfen. Dafür bekommt es die CA als
ca_certificate, und der Service verweist darauf:
CAID=$(cat /proc/sys/kernel/random/uuid)
cat > upstream-tls.yaml <<EOF
ca_certificates:
- id: $CAID
cert: |
$(sed 's/^/ /' ca.crt)
services:
- name: echo-tls
url: https://echo-tls:8080/anything
tls_verify: true
ca_certificates:
- $CAID
routes:
- name: echo-tls
paths: [/echo-tls]
EOF
deck file merge ~/kong-lab/kong/kong.yaml upstream-tls.yaml -o ~/kong-lab/kong/kong.yaml
ksync 2>/dev/null | tail -3
curl -s -o /dev/null -w '%{http_code}\n' $PROXY/echo-tls/getErwartet:
Created: 3
Updated: 0
Deleted: 0
200
Und ohne die CA? Spiel dieselbe Datei mit leerer Liste
ca_certificates ein:
deck file patch -s ~/kong-lab/kong/kong.yaml \
--selector '$.services[?(@.name=="echo-tls")]' \
--value 'ca_certificates:[]' -o ohne-ca.yaml
deck gateway sync ohne-ca.yaml 2>/dev/null | tail -1; sleep 5
curl -s -w ' %{http_code}\n' $PROXY/echo-tls/get | tr -d '\n'; echo
docker compose -f ~/kong-lab/kong/compose.yaml logs kong 2>&1 \
| grep -o 'upstream SSL certificate verify error: ([^)]*)' | tail -1Erwartet (gekürzt):
Deleted: 0
{ "message":"An invalid response was received from the upstream server", …} 502
upstream SSL certificate verify error: (20:unable to get local issuer certificate)
Kong traut dem Zertifikat nicht und bricht ab, der Client bekommt
502. Ohne tls_verify: true hätte Kong jedes Zertifikat
genommen, auch das eines Angreifers.
Der Echo-Dienst mit TLS war ein Versuch. Zurück zum Stand von Drill 5:
docker rm -f echo-tls
cd ~/kong-lab/kong && git checkout kong.yaml && ksync 2>/dev/null | tail -3Erwartet:
echo-tls
Updated 1 path from the index
Created: 0
Updated: 0
Deleted: 3
Fortschritt speichern? Kostenlos registrieren
Kontrollpunkt
curl -s --cacert ~/kong-lab/tag10/tls/ca.crt https://localhost:8443/api/v1/versionErwartet: Kong zeigt dein Zertifikat, curl prüft es
erfolgreich (je nach Target 0.2.0 oder
0.3.0).
0.2.0
curl -s -o /dev/null -w '%{http_code}\n' -u anna:lab-user-pw-123 $PROXY/admin-api/statusErwartet: Die Admin API ist über HTTP gesperrt.
426
curl -s $ADMIN/routes/notes-schreiben | jq -c .protocolsErwartet: Schreiben nur noch über HTTPS.
["https"]
Challenge
Dein Zertifikat läuft in 90 Tagen ab. Finde mit einem einzigen Befehl heraus, wann genau, und zwar so, wie es ein Client sieht, nicht aus der Datei.
Hinweis: openssl s_client holt das
Zertifikat, openssl x509 -enddate zeigt das Ende.
Lösung
echo | openssl s_client -connect localhost:8443 -servername api.kong.lab 2>/dev/null \
| openssl x509 -noout -enddate -issuerErwartet (gekürzt, das Datum weicht bei dir ab):
notAfter=Jan 30 12:55:18 2027 GMT
issuer=CN = Kong Lab CA
Genau so prüft ein Monitoring die Laufzeit von außen. Ein Alarm 30
Tage vor notAfter verhindert die häufigste TLS-Störung
überhaupt: das vergessene Zertifikat.
Fortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
- ACME: Das Plugin
acme(auch in OSS) holt Zertifikate automatisch bei Let’s Encrypt und erneuert sie. Voraussetzung: Kong ist unter dem Namen öffentlich erreichbar. - Schlüssel im Vault: Zertifikatsfelder in Kong sind
referenzierbar (
{vault://env/…}); Enterprise bindet HashiCorp Vault, OpenBao und Cloud-Speicher an. - mTLS zu Clients: Client-Zertifikate prüft in OSS
kein Plugin; Enterprise hat
mtls-auth. Zum Backend kann Kong selbst ein Client-Zertifikat vorzeigen (client_certificateam Service). - TLS vor Kong: Oft beendet ein Load Balancer TLS. Dann gehört TLS zwischen Load Balancer und Kong trotzdem dazu, sonst reisen Schlüssel im internen Netz im Klartext.