THREESCALE-11887 Add configurable whitelist_deny_unmatched policy option

CHANGELOG.md

@@ -27,6 +27,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - Set request timeout for OIDC query. [PR #1601](https://github.com/3scale/APIcast/pull/1601) [THREESCALE-8006](https://redhat.atlassian.net/browse/THREESCALE-8006)
 - Set upstream metrics when sending request via proxy. [PR #1598](https://github.com/3scale/APIcast/pull/1598) [THREESCALE-10571](https://redhat.atlassian.net/browse/THREESCALE-15071)
 - Certificate is never verified in API request for https backend via proxy [PR #1573](https://github.com/3scale/APIcast/pull/1568) [THREESCALE-11944](https://redhat.atlassian.net/browse/THREESCALE-11944)
+- Add whitelist_deny_unmatched option for keycloak_role_check policy [PR #1605](https://github.com/3scale/APIcast/pull/1605) [THREESCALE-11887](https://redhat.atlassian.net/browse/THREESCALE-11887)
 
 ### Added
 - Update APIcast schema manifest [PR #1550](https://github.com/3scale/APIcast/pull/1550)

gateway/src/apicast/policy/keycloak_role_check/README.md

@@ -118,3 +118,25 @@
     ]
   }
   ```
+
+## `whitelist_deny_unmatched` option
+
+By default, when using `whitelist` mode, requests to paths not matching any configured scope are denied. Set `whitelist_deny_unmatched` to `false` to allow unmatched paths through instead.
+
+This option has no effect when `type` is `"blacklist"`.
+
+- When you want to protect only specific paths with a role check and leave all other paths open. Set `whitelist_deny_unmatched` to `false`.
+
+  ```json
+  {
+    "scopes": [
+      {
+        "realm_roles": [ { "name": "admin" } ],
+        "resource": "/admin"
+      }
+    ],
+    "whitelist_deny_unmatched": false
+  }
+  ```
+
+  Requests to `/admin` require the `admin` realm role. Requests to any other path are allowed regardless of roles.

gateway/src/apicast/policy/keycloak_role_check/apicast-policy.json

@@ -105,6 +105,11 @@
         "description": "Type of the role check",
         "enum": ["whitelist", "blacklist"],
         "default": "whitelist"
+      },
+      "whitelist_deny_unmatched": {
+        "type": "boolean",
+        "description": "Only applies when type is 'whitelist'. When true (default), requests to paths not matching any configured scope are denied. When false, unmatched paths are allowed through.",
+        "default": true
       }
     }
   }

gateway/src/apicast/policy/keycloak_role_check/keycloak_role_check.lua

@@ -99,6 +99,10 @@ end
 function _M.new(config)
   local self = new()
   self.type = config.type or "whitelist"
+  -- When true (default), a whitelist denies requests to paths not matching any
+  -- configured scope. When false, unmatched paths are allowed through.
+  -- Has no effect when type is "blacklist".
+  self.whitelist_deny_unmatched = config.whitelist_deny_unmatched ~= false and true or false
   self.scopes = config.scopes or {}
 
   build_scopes(self.scopes)
@@ -159,7 +163,7 @@ local function match_client_roles(scope, context)
 end
 
 local function validate_scope_access(scope, context, uri, request_method)
-  for _, method  in ipairs(scope.methods) do
+  for _, method in ipairs(scope.methods) do
 
     local resource = scope.resource_template_string:render(context)
 
@@ -173,40 +177,53 @@ local function validate_scope_access(scope, context, uri, request_method)
 
     if mapping_rule:matches(request_method, uri) then
       if match_realm_roles(scope, context) and match_client_roles(scope, context) then
-        return true
+        return true, true
       end
+      return true, false
     end
   end
-  return false
+  return false, false
 end
 
 local function scopes_check(scopes, context)
   local uri = ngx.var.uri
-  local request_method =  ngx.req.get_method()
+  local request_method = ngx.req.get_method()
 
   if not context.jwt then
-    return false
+    return false, false
   end
 
+  local any_resource_matched = false
+
   for _, scope in ipairs(scopes) do
-    if validate_scope_access(scope, context, uri, request_method) then
-      return true
+    local resource_matched, roles_passed = validate_scope_access(scope, context, uri, request_method)
+    if resource_matched then
+      if roles_passed then
+        return true, true
+      end
+      any_resource_matched = true
     end
   end
 
-  return false
+  return any_resource_matched, false
 end
 
 function _M:access(context)
-  if scopes_check(self.scopes, context) then
-    if self.type == "blacklist" then
+  local resource_matched, roles_passed = scopes_check(self.scopes, context)
+
+  if self.type == "whitelist" then
+    if resource_matched and not roles_passed then
+      return errors.authorization_failed(context.service)
+    end
+    if not resource_matched and self.whitelist_deny_unmatched then
       return errors.authorization_failed(context.service)
     end
-  else
-    if self.type == "whitelist" then
+  elseif self.type == "blacklist" then
+    if resource_matched and roles_passed then
       return errors.authorization_failed(context.service)
     end
   end
+
   return true
 end
 

spec/policy/keycloak_role_check/keycloak_role_check_spec.lua

@@ -663,5 +663,72 @@ describe('Keycloak Role check policy', function()
       end)
 
     end)
+
+    describe('whitelist_deny_unmatched option', function()
+      local context_with_jwt = {
+        jwt = {
+          realm_access = { roles = { "known_role" } }
+        },
+        service = {
+          auth_failed_status = 403,
+          error_auth_failed = "auth failed"
+        }
+      }
+
+      local scopes = {
+        {
+          realm_roles = { { name = "known_role" } },
+          resource = "/protected"
+        }
+      }
+
+      describe('unmatched path behaviour', function()
+        before_each(function()
+          ngx.var = { uri = '/unmatched' }
+        end)
+
+        it('denies unmatched path by default', function()
+          local policy = KeycloakRoleCheckPolicy.new({ scopes = scopes, type = "whitelist" })
+          policy:access(context_with_jwt)
+          assert.same(ngx.status, 403)
+        end)
+
+        it('denies unmatched path when whitelist_deny_unmatched is true', function()
+          local policy = KeycloakRoleCheckPolicy.new({ scopes = scopes, type = "whitelist", whitelist_deny_unmatched = true })
+          policy:access(context_with_jwt)
+          assert.same(ngx.status, 403)
+        end)
+
+        it('allows unmatched path when whitelist_deny_unmatched is false', function()
+          local policy = KeycloakRoleCheckPolicy.new({ scopes = scopes, type = "whitelist", whitelist_deny_unmatched = false })
+          policy:access(context_with_jwt)
+          assert.not_same(ngx.status, 403)
+        end)
+
+        it('blacklist always allows unmatched path regardless of whitelist_deny_unmatched', function()
+          local policy = KeycloakRoleCheckPolicy.new({ scopes = scopes, type = "blacklist", whitelist_deny_unmatched = true })
+          policy:access(context_with_jwt)
+          assert.not_same(ngx.status, 403)
+        end)
+      end)
+
+      describe('matched path behaviour is unaffected', function()
+        before_each(function()
+          ngx.var = { uri = '/protected' }
+        end)
+
+        it('whitelist + whitelist_deny_unmatched false: matched path with correct role is still allowed', function()
+          local policy = KeycloakRoleCheckPolicy.new({ scopes = scopes, type = "whitelist", whitelist_deny_unmatched = false })
+          policy:access(context_with_jwt)
+          assert.not_same(ngx.status, 403)
+        end)
+
+        it('blacklist + whitelist_deny_unmatched true: matched path with correct role is still denied', function()
+          local policy = KeycloakRoleCheckPolicy.new({ scopes = scopes, type = "blacklist", whitelist_deny_unmatched = true })
+          policy:access(context_with_jwt)
+          assert.same(ngx.status, 403)
+        end)
+      end)
+    end)
   end)
 end)

t/apicast-policy-keycloak-role-check.t

@@ -550,3 +550,146 @@ Check an allowed role with the blacklisted mode with methods
 --- no_error_log
 [error]
 oauth failed with
+
+
+=== TEST 8: whitelist_deny_unmatched false - unmatched path is allowed
+Scoped whitelist: paths not listed in scopes are allowed regardless of roles.
+--- backend
+  location /transactions/oauth_authrep.xml {
+    content_by_lua_block {
+      ngx.exit(200)
+    }
+  }
+
+--- configuration
+{
+  "oidc": [
+    {
+      "issuer": "https://example.com/auth/realms/apicast",
+      "config": { "id_token_signing_alg_values_supported": [ "RS256" ] },
+      "keys": { "somekid": { "pem": "-----BEGIN PUBLIC KEY-----\nMFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBALClz96cDQ965ENYMfZzG+Acu25lpx2K\nNpAALBQ+catCA59us7+uLY5rjQR6SOgZpCz5PJiKNAdRPDJMXSmXqM0CAwEAAQ==\n-----END PUBLIC KEY-----", "alg": "RS256" } }
+    }
+  ],
+  "services": [
+    {
+      "id": 42,
+      "backend_version": "oauth",
+      "backend_authentication_type": "service_token",
+      "backend_authentication_value": "token-value",
+      "proxy": {
+        "authentication_method": "oidc",
+        "oidc_issuer_endpoint": "https://example.com/auth/realms/apicast",
+        "api_backend": "http://test:$TEST_NGINX_SERVER_PORT/",
+        "proxy_rules": [
+          { "pattern": "/", "http_method": "GET", "metric_system_name": "hits", "delta": 1 }
+        ],
+        "policy_chain": [
+          {
+            "name": "apicast.policy.keycloak_role_check",
+            "configuration": {
+              "scopes": [
+                {
+                  "realm_roles": [ { "name": "admin" } ],
+                  "resource": "/protected"
+                }
+              ],
+              "whitelist_deny_unmatched": false
+            }
+          },
+          { "name": "apicast.policy.apicast" }
+        ]
+      }
+    }
+  ]
+}
+--- upstream
+  location /public {
+     content_by_lua_block {
+       ngx.say('yay, api backend');
+     }
+  }
+--- request
+GET /public
+--- more_headers eval
+::authorization_bearer_jwt('audience', {
+  realm_access => {
+    roles => [ 'regular_user' ]
+  }
+}, 'somekid')
+--- error_code: 200
+--- response_body
+yay, api backend
+--- no_error_log
+[error]
+oauth failed with
+
+
+
+=== TEST 9: whitelist_deny_unmatched true (default) - unmatched path is denied
+Whitelist default behaviour: paths not listed in scopes are denied.
+--- backend
+  location /transactions/oauth_authrep.xml {
+    content_by_lua_block {
+      ngx.exit(200)
+    }
+  }
+
+--- configuration
+{
+  "oidc": [
+    {
+      "issuer": "https://example.com/auth/realms/apicast",
+      "config": { "id_token_signing_alg_values_supported": [ "RS256" ] },
+      "keys": { "somekid": { "pem": "-----BEGIN PUBLIC KEY-----\nMFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBALClz96cDQ965ENYMfZzG+Acu25lpx2K\nNpAALBQ+catCA59us7+uLY5rjQR6SOgZpCz5PJiKNAdRPDJMXSmXqM0CAwEAAQ==\n-----END PUBLIC KEY-----", "alg": "RS256" } }
+    }
+  ],
+  "services": [
+    {
+      "id": 42,
+      "backend_version": "oauth",
+      "backend_authentication_type": "service_token",
+      "backend_authentication_value": "token-value",
+      "proxy": {
+        "authentication_method": "oidc",
+        "error_status_auth_failed": 403,
+        "error_auth_failed": "auth failed",
+        "oidc_issuer_endpoint": "https://example.com/auth/realms/apicast",
+        "api_backend": "http://test:$TEST_NGINX_SERVER_PORT/",
+        "proxy_rules": [
+          { "pattern": "/", "http_method": "GET", "metric_system_name": "hits", "delta": 1 }
+        ],
+        "policy_chain": [
+          {
+            "name": "apicast.policy.keycloak_role_check",
+            "configuration": {
+              "scopes": [
+                {
+                  "realm_roles": [ { "name": "restricted" } ],
+                  "resource": "/sensitive"
+                }
+              ]
+            }
+          },
+          { "name": "apicast.policy.apicast" }
+        ]
+      }
+    }
+  ]
+}
+--- upstream
+  location /other {
+     content_by_lua_block {
+       ngx.say('yay, api backend');
+     }
+  }
+--- request
+GET /other
+--- more_headers eval
+::authorization_bearer_jwt('audience', {
+  realm_access => {
+    roles => [ 'regular_user' ]
+  }
+}, 'somekid')
+--- error_code: 403
+--- response_body chomp
+auth failed