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

Author: chrisingenhaag

docker-compose.yml

@@ -91,6 +91,12 @@ 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"
     entrypoint: [ "/bin/sh", "-c", "cd /opt/tests && /bin/sh ./run_tests.sh" ]
 
   httpbin:

spec/01-unit/keycloak_keys_spec.lua

@@ -54,4 +54,19 @@ 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 = keycloak_keys.get_issuer_keys(well_known_endpoint)
+
+      assert.is_nil(err)
+      assert.is_table(keys)
+      assert.is_table(kids)
+      assert.equals(2, #keys)
+      assert.equals(2, #kids)
+      assert.same({ "kid1", "kid2" }, kids)
+    end)
+  end)
 end)

spec/01-unit/validators/signature_spec.lua

@@ -0,0 +1,115 @@
+-- SPDX-FileCopyrightText: 2025 Deutsche Telekom AG
+--
+-- SPDX-License-Identifier: Apache-2.0
+
+local helpers = require "spec.helpers"
+
+describe("Plugin: jwt-keycloak (signature validator)", function()
+  local signature_validator
+
+  before_each(function()
+    helpers.setup_kong_mock()
+    signature_validator = require "kong.plugins.jwt-keycloak.validators.signature"
+  end)
+
+  after_each(function()
+    helpers.teardown_kong_mock()
+    package.loaded["kong.plugins.jwt-keycloak.validators.signature"] = nil
+  end)
+
+  it("should reject when kid is missing", function()
+    local jwt = {
+      header = { alg = "RS256" },
+    }
+
+    local public_keys = {
+      keys = { "key1" },
+      kids = { "kid1" },
+    }
+
+    local err = signature_validator.validate_signature_with_kid({}, jwt, public_keys)
+
+    assert.is_table(err)
+    assert.equals(401, err.status)
+    assert.equals("Invalid token: kid header missing", err.message)
+  end)
+
+  it("should reject when kids table is missing", function()
+    local jwt = {
+      header = { alg = "RS256", kid = "kid1" },
+    }
+
+    local public_keys = {
+      keys = { "key1" },
+      -- kids missing
+    }
+
+    local err = signature_validator.validate_signature_with_kid({}, jwt, public_keys)
+
+    assert.is_table(err)
+    assert.equals(401, err.status)
+    assert.equals("Unable to find public key for token kid", err.message)
+  end)
+
+  it("should reject when kid is not found in public keys", function()
+    local jwt = {
+      header = { alg = "RS256", kid = "kidX" },
+    }
+
+    local public_keys = {
+      keys = { "key1", "key2" },
+      kids = { "kid1", "kid2" },
+    }
+
+    local err = signature_validator.validate_signature_with_kid({}, jwt, public_keys)
+
+    assert.is_table(err)
+    assert.equals(401, err.status)
+    assert.equals("Unable to find public key for token kid", err.message)
+  end)
+
+  it("should accept when signature verifies with kid-matched key", function()
+    local call_count = 0
+    local used_keys = {}
+
+    local jwt = {
+      header = { alg = "RS256", kid = "kid2" },
+      verify_signature = function(self, key)
+        call_count = call_count + 1
+        table.insert(used_keys, key)
+        return key == "KEY_FOR_KID2"
+      end
+    }
+
+    local public_keys = {
+      keys = { "KEY_FOR_KID1", "KEY_FOR_KID2" },
+      kids = { "kid1", "kid2" },
+    }
+
+    local err = signature_validator.validate_signature_with_kid({}, jwt, public_keys)
+
+    assert.is_nil(err)
+    assert.equals(1, call_count)
+    assert.same({ "KEY_FOR_KID2" }, used_keys)
+  end)
+
+  it("should reject when signature does not verify with kid-matched key", function()
+    local jwt = {
+      header = { alg = "RS256", kid = "kid2" },
+      verify_signature = function(self, key)
+        return false
+      end
+    }
+
+    local public_keys = {
+      keys = { "KEY_FOR_KID1", "KEY_FOR_KID2" },
+      kids = { "kid1", "kid2" },
+    }
+
+    local err = signature_validator.validate_signature_with_kid({}, jwt, public_keys)
+
+    assert.is_table(err)
+    assert.equals(401, err.status)
+    assert.equals("Invalid token signature", err.message)
+  end)
+end)

spec/helpers.lua

@@ -85,25 +85,71 @@ end
 -- Mock cjson.safe
 local mock_cjson_safe = {
   decode = function(data)
-    -- Simple JSON decoder for tests
+    -- Minimal JSON decoder for tests, tailored to the structures we use
+    -- Well-known configuration with jwks_uri
+    if data:find('"jwks_uri"') then
+      local jwks_uri = data:match('"jwks_uri"%s*:%s*"([^"]+)"')
+      return { jwks_uri = jwks_uri }, nil
+    end
+
+    -- JWKS document with keys and kids
+    if data:find('"keys"') then
+      -- For tests, return 2 RSA keys with kids kid1 and kid2
+      return {
+        keys = {
+          {
+            kid = "kid1",
+            kty = "RSA",
+            n = "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx4cbbfAAtmY7sFdl7oahqT_Rc59oKHM78bF8HGmKuHqUL6v3Ohl80UR8QFN5Y8o3h8DGf9LUz0p8H2I",
+            e = "AQAB"
+          },
+          {
+            kid = "kid2",
+            kty = "RSA",
+            n = "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx4cbbfAAtmY7sFdl7oahqT_Rc59oKHM78bF8HGmKuHqUL6v3Ohl80UR8QFN5Y8o3h8DGf9LUz0p8H2I",
+            e = "AQAB"
+          }
+        }
+      }, nil
+    end
+
+    -- Generic test payload
     if data == '{"test": "data"}' then
-      return { test = "data" }
+      return { test = "data" }, nil
     end
+
     return nil, "parse error"
   end
 }
 
 -- Mock socket modules
-local mock_http = {
-  request = function(options)
-    return "result", 200
+local function http_request_mock(options)
+  local url = options.url
+  local sink = options.sink
+
+  local body
+  if url and url:find("openid%-configuration") then
+    body = '{"jwks_uri": "https://keycloak.example.com/auth/realms/test/jwks"}'
+  elseif url and url:find("jwks") then
+    body = '{"keys": []}' -- actual keys are provided by mock_cjson_safe.decode
+  else
+    body = '{"test": "data"}'
   end
+
+  if sink then
+    local writer = sink
+    writer(body)
+  end
+
+  return true, 200
+end
+
+local mock_http = {
+  request = http_request_mock
 }
 
 local mock_https = {
-  request = function(options)
-    return "result", 200
-  end
+  request = http_request_mock
 }
 
 local mock_ltn12 = {

src/handler.lua

@@ -14,6 +14,7 @@ local validate_scope = require("kong.plugins.jwt-keycloak.validators.scope").val
 local validate_roles = require("kong.plugins.jwt-keycloak.validators.roles").validate_roles
 local validate_realm_roles = require("kong.plugins.jwt-keycloak.validators.roles").validate_realm_roles
 local validate_client_roles = require("kong.plugins.jwt-keycloak.validators.roles").validate_client_roles
+local signature_validator = require("kong.plugins.jwt-keycloak.validators.signature")
 
 local re_gmatch = ngx.re.gmatch
 local decode_base64 = ngx.decode_base64
@@ -106,19 +107,24 @@ end
 -------------------------------------------------------------------------------
 local function custom_helper_issuer_get_keys(well_known_endpoint, cafile)
     kong.log.debug('Getting public keys from token issuer')
-    local keys, err = keycloak_keys.get_issuer_keys(well_known_endpoint, cafile)
+    local keys, kids, err = keycloak_keys.get_issuer_keys(well_known_endpoint, cafile)
     if err then
         return nil, err
     end
 
     local decoded_keys = {}
+    local key_ids = {}
     for i, key in ipairs(keys) do
         decoded_keys[i] = custom_base64_decode(key)
+        if kids then
+            key_ids[i] = kids[i]
+        end
     end
 
     kong.log.debug('Number of keys retrieved: ' .. table.getn(decoded_keys))
     return {
         keys = decoded_keys,
+        kids = key_ids,
         updated_at = socket.gettime()
     }
 end
@@ -149,28 +155,35 @@ local function custom_validate_token_signature(conf, jwt, second_call)
         })
     end
 
-    -- Verify signatures
-    for _, k in ipairs(public_keys.keys) do
-        if jwt:verify_signature(k) then
-            kong.log.debug('JWT signature verified')
-            return nil
-        end
+    -- Delegate kid-based selection and signature validation to dedicated validator
+    local err_tbl = signature_validator.validate_signature_with_kid(conf, jwt, public_keys)
+    if not err_tbl then
+        kong.log.debug('JWT signature verified using kid-matched key')
+        return nil
     end
 
     -- We could not validate signature, try to get a new keyset?
     local since_last_update = socket.gettime() - public_keys.updated_at
     if not second_call and since_last_update > conf.iss_key_grace_period then
-        kong.log.debug('Could not validate signature. Keys updated last ' .. since_last_update .. ' seconds ago')
+        kong.log.debug('Could not validate signature with kid-matched key. Keys updated last ' .. since_last_update .. ' seconds ago')
         -- can it be that the signature key of the issuer has changed ... ?
         -- invalidate the old keys in kong cache and do a current lookup to the signature keys
         -- of the token issuer
         kong.cache:invalidate_local(issuer_cache_key)
         return custom_validate_token_signature(conf, jwt, true)
     end
 
-    security_event('ua222', 'ua, invalid token signature')
-    return kong.response.exit(401, {
-        message = "Invalid token signature"
+    -- After optional refresh we still failed; map error message to appropriate security event
+    if err_tbl.message == "Invalid token: kid header missing" then
+        security_event('ua201', 'ua, token integrity wrong, kid missing')
+    elseif err_tbl.message == "Unable to find public key for token kid" then
+        security_event('ua221', 'ua, public key for kid not available')
+    else
+        security_event('ua222', 'ua, invalid token signature')
+    end
+
+    return kong.response.exit(err_tbl.status, {
+        message = err_tbl.message
     })
 end
 

src/keycloak_keys.lua

@@ -49,22 +49,28 @@ local function get_issuer_keys(well_known_endpoint)
 
     local res, err = get_request(well_known_endpoint, req.scheme, req.port)
     if err then
-        return nil, err
+        return nil, nil, err
     end
 
-    local res, err = get_request(res['jwks_uri'], req.scheme,  req.port)
-    if err then
-        return nil, err
+    local jwks, jwks_err = get_request(res["jwks_uri"], req.scheme, req.port)
+    if jwks_err then
+        return nil, nil, jwks_err
     end
 
     local keys = {}
-    for i, key in ipairs(res['keys']) do
+    local kids = {}
+    for i, key in ipairs(jwks["keys"]) do
         keys[i] = string.gsub(
-            convert.convert_kc_key(key), 
+            convert.convert_kc_key(key),
             "[\r\n]+", ""
         )
+        kids[i] = key.kid
     end
-    return keys, nil
+
+    -- Preserve original behavior for existing callers by returning keys as first
+    -- value and error as third value. The second return value contains the list
+    -- of kids aligned by index with the keys array.
+    return keys, kids, nil
 end
 
 return {