Zum Inhalt springen
Trainingslager IT-Trainingslager

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.lua beschreibt die Konfiguration, handler.lua enthält die Logik für die Phasen einer Anfrage.
  • Die PRIORITY im Handler bestimmt, wann es läuft. jwt-identity läuft mit 1400 nach jwt (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_PLUGINS und 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.lua

Erwartet:

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.lua

Erwartet:

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 .message

Erwartet:

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"}'
done

Erwartet:

  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 -1

Erwartet:

  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_level

Erwartet:

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 -1

Erwartet:

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 -1

Erwartet:

  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 pongo startet 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).