Tag 11: Ein eigenes Plugin in Lua
Ziel: Ein eigenes Plugin schreiben, das den Namen aus einem geprüften JWT als Header ans Backend gibt, es in Kong einbinden, konfigurieren und gegen gefälschte Header absichern. · Dauer: ca. 75 min · Voraussetzung: Tag 10
Briefing
- Ein Plugin besteht aus mindestens zwei Lua-Dateien:
schema.luabeschreibt die Konfiguration,handler.luaenthält die Logik für die Phasen einer Anfrage. - Die PRIORITY im Handler bestimmt, wann es läuft.
jwt-identityläuft mit 1400 nachjwt(1450): Es sieht nur Tokens, die schon geprüft sind. - Das PDK (
kong.request,kong.service.request,kong.client,kong.log) ist die stabile Schnittstelle zu Kong. - Kong lädt eigene Plugins über
KONG_PLUGINSund den Lua-Suchpfad.
Bearer JWT ─► jwt (1450): Signatur ok, Consumer keycloak
─► jwt-identity (1400): X-User = preferred_username aus dem Token
─► acl (950) ─► Backend sieht X-User: anna
Drill 1: Die Anatomie
source ~/kong-lab/setup/env.sh
mkdir -p ~/kong-lab/tag11
cp -R ~/kong-lab/code/plugins ~/kong-lab/plugins
cd ~/kong-lab/plugins/kong/plugins/jwt-identity
ls
grep -v '^--' schema.luaErwartet:
handler.lua schema.lua
local typedefs = require "kong.db.schema.typedefs"
return {
name = "jwt-identity",
fields = {
{ consumer = typedefs.no_consumer },
{ protocols = typedefs.protocols_http },
{ config = {
type = "record",
fields = {
{ claim = { type = "string", required = true,
default = "preferred_username" } },
{ header = { type = "string", required = true, default = "X-User",
match = "^X%-[%w%-]+$" } },
},
} },
},
}
Zwei Einstellungen: welcher Claim (claim) in welchen
Header (header). match ist ein Lua-Muster: Der
Header muss mit X- beginnen. no_consumer
verbietet, das Plugin an einen Consumer zu hängen.
sed -n '/^function/,/^end/p' handler.luaErwartet:
function JwtIdentity:access(conf)
-- Ein vom Client mitgeschickter Header wird immer entfernt.
kong.service.request.clear_header(conf.header)
-- Nur wenn die Anmeldung über ein JWT lief, ist das Token geprüft.
local credential = kong.client.get_credential()
if not credential or not credential.algorithm then
return
end
local auth = kong.request.get_header("authorization") or ""
local token = auth:match("^[Bb]earer%s+(.+)$")
if not token then
return
end
local jwt, err = jwt_parser:new(token)
if not jwt then
kong.log.warn("Token nicht lesbar: ", err)
return
end
local value = jwt.claims[conf.claim]
if type(value) == "string" then
kong.service.request.set_header(conf.header, value)
kong.log.info(conf.header, ": ", value)
end
end
Die Phase access läuft vor der Weiterleitung. Drei
Regeln stecken im Code: einen mitgeschickten Header immer löschen, nur
bei einer JWT-Anmeldung handeln (nur JWT-Credentials haben
algorithm), und das Token mit Kongs eigenem Parser lesen
statt selbst Base64 zu zerlegen.
Fortschritt speichern? Kostenlos registrieren
Drill 2: Einbinden
cd ~/kong-lab/kong
cp ~/kong-lab/code/tag11/compose.yaml compose.yaml
grep -E 'KONG_PLUGINS|LUA_PACKAGE|kong-plugins' compose.yaml
docker compose up -d --wait
curl -s $ADMIN | jq -c '.plugins.available_on_server["jwt-identity"]'Erwartet (gekürzt):
KONG_PLUGINS: bundled,jwt-identity
KONG_LUA_PACKAGE_PATH: /kong-plugins/?.lua;;
- ../plugins:/kong-plugins:ro # eigene Plugins (Tag 11)
Container kong-kong-1 Healthy
{"priority":1400,"version":"0.1.0"}
bundled steht für die 45 mitgelieferten Plugins. Der
Suchpfad /kong-plugins/?.lua macht aus
kong.plugins.jwt-identity.handler die Datei
/kong-plugins/kong/plugins/jwt-identity/handler.lua;
;; hängt den Standardpfad an.
Fortschritt speichern? Kostenlos registrieren
Drill 3: Das Schema prüft mit
Kong prüft jede Konfiguration gegen dein Schema, bevor es sie speichert:
curl -s -X POST $ADMIN/schemas/plugins/validate -H 'Content-Type: application/json' \
-d '{"name":"jwt-identity","config":{"header":"User"}}' | jq -r .message
curl -s -X POST $ADMIN/schemas/plugins/validate -H 'Content-Type: application/json' \
-d '{"name":"jwt-identity","config":{}}' | jq -r .messageErwartet:
schema violation (config.header: invalid value: User)
schema validation successful
Ohne Angaben gelten die Standardwerte aus dem Schema.
Fortschritt speichern? Kostenlos registrieren
Drill 4: Am Service whoami
cd ~/kong-lab/tag11
deck file add-plugins -s ~/kong-lab/kong/kong.yaml \
--selector '$.services[?(@.name=="whoami")]' \
--config '{"name":"jwt-identity"}' -o ~/kong-lab/kong/kong.yaml
ksync 2>/dev/null | tail -3
anna_token() {
curl -s -d grant_type=password -d client_id=notes-cli \
-d client_secret=lab-client-secret-123 \
-d username=anna -d password=lab-user-pw-123 \
$KC/protocol/openid-connect/token | jq -r .access_token
}
T=$(token); U=$(anna_token)
for t in "$T" "$U"; do
curl -s -H "Authorization: Bearer $t" $PROXY/whoami \
| jq -c '.headers | {"X-User", "X-Consumer-Username"}'
doneErwartet:
Created: 1
Updated: 0
Deleted: 0
{"X-User":["service-account-notes-cli"],"X-Consumer-Username":["keycloak"]}
{"X-User":["anna"],"X-Consumer-Username":["keycloak"]}
Das Ergebnis der Challenge aus Tag 6, jetzt gelöst: Der Consumer bleibt der Aussteller, aber das Backend erfährt, wer im Token steht.
Fortschritt speichern? Kostenlos registrieren
Drill 5: Fälschen zwecklos
Kann ein Client sich selbst einen Namen geben?
curl -s -H 'apikey: lab-key-anna-456' -H 'X-User: chef' $PROXY/whoami \
| jq -c '.headers | {"X-User", "X-Consumer-Username"}'
curl -s -H "Authorization: Bearer $U" -H 'X-User: chef' $PROXY/whoami \
| jq -c '.headers."X-User"'Erwartet:
{"X-User":null,"X-Consumer-Username":["anna"]}
["anna"]
Mit Schlüssel bleibt X-User leer: Das Plugin löscht den
Header und setzt keinen neuen, denn die Anmeldung lief nicht über ein
JWT. Mit Token gewinnt der Name aus dem Token. Ohne die erste Zeile in
access könnte jeder Client X-User: chef
schicken, und ein Backend, das dem Header traut, wäre offen.
Fortschritt speichern? Kostenlos registrieren
Drill 6: Anders konfigurieren
Dasselbe Plugin, anderer Claim:
P='$.services[?(@.name=="whoami")].plugins[?(@.name=="jwt-identity")]'
deck file patch -s ~/kong-lab/kong/kong.yaml --selector "$P" \
--value 'config:{"claim":"email","header":"X-User-Email"}' -o mail.yaml
deck gateway sync mail.yaml 2>/dev/null | tail -2; sleep 5
curl -s -H "Authorization: Bearer $(anna_token)" $PROXY/whoami \
| jq -c '.headers | {"X-User", "X-User-Email"}'
ksync 2>/dev/null | tail -1Erwartet:
Updated: 1
Deleted: 0
{"X-User":null,"X-User-Email":["[email protected]"]}
Deleted: 0
Das Plugin wurde in Drill 4 ohne config angelegt, darum
ersetzt der Patch das ganze Feld config. ksync
stellt danach den Stand aus kong.yaml wieder her.
Fortschritt speichern? Kostenlos registrieren
Drill 7: Code ändern und Logs lesen
Der Handler schreibt mit kong.log.info. Im Log steht
davon nichts:
curl -s -o /dev/null -H "Authorization: Bearer $(anna_token)" $PROXY/whoami
docker compose -f ~/kong-lab/kong/compose.yaml logs kong 2>&1 \
| grep -c 'jwt-identity.*X-User'
curl -s $ADMIN | jq -r .configuration.log_levelErwartet:
0
notice
Kong protokolliert ab notice. Ändere die Zeile im Code.
Neuer Code braucht kein ksync, sondern einen Neustart der
Worker:
H=~/kong-lab/plugins/kong/plugins/jwt-identity/handler.lua
ALT='kong.log.info(conf.header, ": ",'
NEU='kong.log.notice("gesetzt: ", conf.header, "=",'
sed -i "s/$ALT/$NEU/" $H
docker compose -f ~/kong-lab/kong/compose.yaml exec kong kong reload; sleep 5
curl -s -o /dev/null -H "Authorization: Bearer $(anna_token)" $PROXY/whoami
docker compose -f ~/kong-lab/kong/compose.yaml logs kong 2>&1 \
| grep -o '\[jwt-identity\] gesetzt: [^,]*' | tail -1Erwartet:
Kong reloaded
[jwt-identity] gesetzt: X-User=anna
Kong stellt jeder Zeile den Namen des Plugins voran. In Produktion
setzt du KONG_LOG_LEVEL nur zur Fehlersuche auf
info oder debug, denn es protokolliert dann
auch Inhalte von Anfragen.
Stand festhalten:
cd ~/kong-lab/kong
git add compose.yaml kong.yaml && git commit -qm "Tag 11: Plugin jwt-identity"Fortschritt speichern? Kostenlos registrieren
Kontrollpunkt
curl -s $ADMIN/plugins | jq -r '.data[] | select(.name == "jwt-identity")
| [.name, .config.claim, .config.header] | @tsv'Erwartet: eine Instanz mit den Standardwerten.
jwt-identity preferred_username X-User
curl -s -H "Authorization: Bearer $(token)" $PROXY/whoami | jq -r '.headers."X-User"[0]'Erwartet: der Name aus dem Token.
service-account-notes-cli
curl -s -H 'apikey: lab-key-anna-456' -H 'X-User: chef' $PROXY/whoami \
| jq -c '.headers."X-User"'Erwartet: kein Header, die Fälschung ist weg.
null
Challenge
Ein Angreifer baut sich ein Token ohne Signatur mit
preferred_username: chef und schickt es an eine Route, an
der jwt-identity hängt, aber kein
jwt. Was kommt beim Backend an? Probier es an der Route
echo.
Hinweis: Häng das Plugin per --config
an den Service echo; ein Token ohne Signatur sind Header
und Payload in Base64url mit einem Punkt am Ende.
Lösung
cd ~/kong-lab/tag11
deck file add-plugins -s ~/kong-lab/kong/kong.yaml \
--selector '$.services[?(@.name=="echo")]' \
--config '{"name":"jwt-identity"}' -o echo.yaml
deck gateway sync echo.yaml 2>/dev/null | tail -2; sleep 5
b64() { base64 -w0 | tr '/+' '_-' | tr -d '='; }
KOPF=$(echo -n '{"alg":"none"}' | b64)
INHALT=$(echo -n '{"preferred_username":"chef"}' | b64)
FAKE="$KOPF.$INHALT."
curl -s -H "Authorization: Bearer $FAKE" -H 'X-User: chef' $PROXY/echo/headers \
| jq -c '.headers."X-User"'
ksync 2>/dev/null | tail -1Erwartet:
Updated: 0
Deleted: 0
null
Deleted: 1
Nichts. Ohne jwt gibt es kein JWT-Credential, also setzt
das Plugin keinen Namen und löscht den mitgeschickten. Genau dafür prüft
es credential.algorithm, statt einem Token zu trauen, das
nur lesbar ist.
Fortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
- Testen mit Pongo: Kongs Werkzeug
pongostartet Kong und Postgres in Containern und führt Unit- und Integrationstests (busted) für eigene Plugins aus. - Ausliefern: Als LuaRocks-Paket oder in ein eigenes Image kopiert; im Container ein eingebundenes Verzeichnis wie hier nur im Labor.
- Andere Sprachen: Kong hat PDKs für Go, Python und JavaScript; diese Plugins laufen als eigene Prozesse und sind langsamer als Lua.
- Konnect und Enterprise laden eigene Plugins über Schemas in die Control Plane; der Code muss trotzdem auf jedem Data-Plane-Knoten liegen (Tag 13).