feat: add kid-based signature validation with enhanced error handling (#8)

* feat: add kid-based signature validation with enhanced error handling

* feat: add automatic key selection when kid header is absent

Implements fallback key selection based on JWT algorithm and key metadata when kid header is missing. Plugin now attempts to find a single unambiguous matching key by comparing JWT algorithm (RS256/384/512, PS256/384/512, ES256/384/512) with key metadata (alg, kty, use). Rejects tokens when multiple keys match or no matching key is found. Adds key_metadata tracking throughout the key retrieval chain and comprehensive test coverage for various

* chore: add explicit docker network configuration for service isolation

Defines kong-net bridge network and assigns all services to it for improved network isolation and DNS resolution. Adds diagnostic network connectivity test script that validates DNS resolution for kong, kc, and httpbin services during test initialization.

* chore: add diagnostic logging to GitHub Actions test workflow

Adds Docker version information output and failure diagnostics that display container status and logs for kong, keycloak, and test services when tests fail. Improves troubleshooting capabilities for CI test failures.

* fix: add signature validator module to rockspec build configuration

Registers the new validators.signature module in the rockspec build modules list and aligns formatting of validator module entries for consistency.

* fix: set all fetching public keys security events to ua221

* Update src/handler.lua

Co-authored-by: Luis Pflamminger <luis.pflamminger@gmail.com>

* test: remove kty-based key matching and simplify algorithm validation

Removes key type (kty) field from key metadata tracking and eliminates kty-based key matching logic. Simplifies algorithm validation to only check explicit alg field matches when present. Updates test descriptions to reflect that keys match when no alg is specified rather than matching by kty. Removes PS256 algorithm test and kid-optional integration test notes that are now covered by unit tests.

* chore: bump plugin version to 1.7.0-1

---------

Co-authored-by: Luis Pflamminger <luis.pflamminger@gmail.com>

Author: chrisingenhaag

.github/workflows/test.yml

@@ -27,5 +27,27 @@ jobs:
       - uses: actions/checkout@v4
         with:
           submodules: "true"
+      
+      - name: Show Docker info
+        run: |
+          docker --version
+          docker compose version
+          
       - name: Run Tests
         run: docker compose build --no-cache && docker compose up --exit-code-from tests tests
+      
+      - name: Show container status
+        if: failure()
+        run: docker compose ps
+      
+      - name: Show Kong logs
+        if: failure()
+        run: docker compose logs kong
+      
+      - name: Show Keycloak logs
+        if: failure()
+        run: docker compose logs kc
+      
+      - name: Show test logs
+        if: failure()
+        run: docker compose logs tests

Dockerfile

@@ -44,7 +44,7 @@ RUN if [ -x "$(command -v apk)" ]; then apk add --no-cache $FIX_DEPENDENCIES; \
     elif [ -x "$(command -v apt-get)" ]; then apt-get remove --purge -y $FIX_DEPENDENCIES; \
     fi
 
-ARG PLUGIN_VERSION=1.6.0-1
+ARG PLUGIN_VERSION=1.7.0-1
 RUN luarocks install /tmp/kong-plugin-jwt-keycloak-${PLUGIN_VERSION}.all.rock
 
 USER kong

README.md

@@ -88,15 +88,15 @@ luarocks install kong-plugin-jwt-keycloak
 #### Packing the rock
 
 ```bash
-export PLUGIN_VERSION=1.6.0-1
+export PLUGIN_VERSION=1.7.0-1
 luarocks make
 luarocks pack kong-plugin-jwt-keycloak ${PLUGIN_VERSION}
 ```
 
 #### Installing the rock
 
 ```bash
-export PLUGIN_VERSION=1.6.0-1
+export PLUGIN_VERSION=1.7.0-1
 luarocks install jwt-keycloak-${PLUGIN_VERSION}.all.rock
 ```
 

docker-compose.yml

@@ -8,7 +8,7 @@ x-kong-image: &kong-image
     dockerfile: Dockerfile
     args:
       KONG_VERSION: ${KONG_VERSION:-3.9.1}
-      PLUGIN_VERSION: 1.6.0-1
+      PLUGIN_VERSION: 1.7.0-1
   environment:
     KONG_DATABASE: postgres
     KONG_PG_HOST: postgres
@@ -30,6 +30,8 @@ services:
     depends_on:
       - postgres
     entrypoint: [ "/bin/sh", "-c", "until kong migrations bootstrap; do echo waiting for database; sleep 2; done;" ]
+    networks:
+      - kong-net
   kong:
     <<: *kong-image
     depends_on:
@@ -39,6 +41,8 @@ services:
     ports:
       - "8000:8000"
       - "8001:8001"
+    networks:
+      - kong-net
   postgres:
     image: postgres:16
     environment:
@@ -47,6 +51,8 @@ services:
       POSTGRES_PASSWORD: kong
     volumes:
       - pg_data:/var/lib/postgresql/data
+    networks:
+      - kong-net
   kc-pg:
     image: postgres:16
     environment:
@@ -55,6 +61,8 @@ services:
       POSTGRES_PASSWORD: postgres
     volumes:
       - pg_kc_data:/var/lib/postgresql/data
+    networks:
+      - kong-net
   kc:
     image: quay.io/keycloak/keycloak:${KEYCLOAK_VERSION:-26.2}
     depends_on:
@@ -75,6 +83,8 @@ services:
       - KC_HOSTNAME_STRICT=false
       - KC_HTTP_RELATIVE_PATH=/auth
       - KC_HTTP_ENABLED=true
+    networks:
+      - kong-net
 
   tests:
     build:
@@ -91,12 +101,27 @@ services:
     environment:
       - LUA_PATH=/opt/kong-plugin-jwt-keycloak/src/?.lua;/opt/kong-plugin-jwt-keycloak/?.lua;;
       - LUA_CPATH=/usr/local/lib/lua/5.1/?.so;;
+      - HTTP_PROXY=
+      - HTTPS_PROXY=
+      - NO_PROXY="localhost,127.0.0.1"
+      - http_proxy=
+      - https_proxy=
+      - no_proxy="localhost,127.0.0.1"
+    networks:
+      - kong-net
     entrypoint: [ "/bin/sh", "-c", "cd /opt/tests && /bin/sh ./run_tests.sh" ]
 
   httpbin:
     image: mccutchen/go-httpbin:2.18.3
     ports:
       - "8080"
+    networks:
+      - kong-net
+
+networks:
+  kong-net:
+    driver: bridge
+
 volumes:
   pg_data:
   pg_kc_data:

kong-plugin-jwt-keycloak-1.6.0-1.rockspec kong-plugin-jwt-keycloak-1.7.0-1.rockspeckong-plugin-jwt-keycloak-1.6.0-1.rockspec renamed to kong-plugin-jwt-keycloak-1.7.0-1.rockspec

@@ -1,6 +1,6 @@
 local plugin_name = "jwt-keycloak"
 local package_name = "kong-plugin-" .. plugin_name
-local package_version = "1.6.0"
+local package_version = "1.7.0"
 local rockspec_revision = "1"
 
 local github_account_name = "telekom"
@@ -38,8 +38,9 @@ build = {
     ["kong.plugins."..plugin_name..".keycloak_keys"]      = "src/keycloak_keys.lua",
     ["kong.plugins."..plugin_name..".key_conversion"]     = "src/key_conversion.lua",
     ["kong.plugins."..plugin_name..".gateway.securitylog"] = "src/gateway/securitylog.lua",
-    ["kong.plugins."..plugin_name..".validators.issuers"] = "src/validators/issuers.lua",
-    ["kong.plugins."..plugin_name..".validators.roles"]   = "src/validators/roles.lua",
-    ["kong.plugins."..plugin_name..".validators.scope"]   = "src/validators/scope.lua",
+    ["kong.plugins."..plugin_name..".validators.issuers"]   = "src/validators/issuers.lua",
+    ["kong.plugins."..plugin_name..".validators.roles"]     = "src/validators/roles.lua",
+    ["kong.plugins."..plugin_name..".validators.scope"]     = "src/validators/scope.lua",
+    ["kong.plugins."..plugin_name..".validators.signature"] = "src/validators/signature.lua",
   }
 }

…in-jwt-keycloak-1.6.0-1.rockspec.license …in-jwt-keycloak-1.7.0-1.rockspec.licensekong-plugin-jwt-keycloak-1.6.0-1.rockspec.license renamed to kong-plugin-jwt-keycloak-1.7.0-1.rockspec.license kong-plugin-jwt-keycloak-1.6.0-1.rockspec.license renamed to kong-plugin-jwt-keycloak-1.7.0-1.rockspec.license

@@ -54,4 +54,24 @@ describe("Plugin: jwt-keycloak (keycloak_keys)", function()
       assert.is_function(keycloak_keys.get_request)
     end)
   end)
+
+  describe("get_issuer_keys", function()
+    it("should return keys and aligned kids from JWKS", function()
+      local well_known_endpoint = "https://keycloak.example.com/auth/realms/test/.well-known/openid-configuration"
+
+      local keys, kids, err, key_metadata = keycloak_keys.get_issuer_keys(well_known_endpoint)
+
+      assert.is_nil(err)
+      assert.is_table(keys)
+      assert.is_table(kids)
+      assert.is_table(key_metadata)
+      assert.equals(2, #keys)
+      assert.equals(2, #kids)
+      assert.equals(2, #key_metadata)
+      assert.same({ "kid1", "kid2" }, kids)
+      -- Verify metadata structure
+      assert.is_table(key_metadata[1])
+      assert.is_table(key_metadata[2])
+    end)
+  end)
 end)