verikloak-pundit 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9062ddd03a6b118971608756c82d1299dc4b509d7219d289aefbeaf381c8e49e
-  data.tar.gz: f2c2a0e9a236c454aabd9316b04ee6e1e98860f6d2db3d8e3863fb826d92a29f
+  metadata.gz: 6936cd5efb5ccaecf789b427db2f7cd09f358604ba334f592f3e5079ac6501c4
+  data.tar.gz: 37db6dc08acd9918bebb15bd8dbb32320e00661ffc81b1b40c85850ec1c0822c
 SHA512:
-  metadata.gz: b2a830375513deb2e8d4b350ffb7960fb95a6c58d5b45af7c519b45cd6086ffd21230af26a89921fca57528e48275e4bf4be59d96a2c45794a11d262c7fe80c3
-  data.tar.gz: deebae419df84ced4bb9ff0a9181847155db0adeb08f6b8cfb8319c6b2f50cd99cbd8e2dc2fa89417d15f2ab198c8e262503be630ab9ec3daf1ca58c5de7aeef
+  metadata.gz: 120391c41f3f769ce49d7bddd83bed04b010ea367d8b63ddedb5de4610f9f8a6600f29f56f84c929b2209e4c26d6825a3d774ae1f32c20f16dd6d53378d5f9bf
+  data.tar.gz: a6d8babf7f27a842105fcc9ba44a42f9c73a21c45eeb486339c9afddca8aa1a6df97720c944407945ebd02a7918455bbb235b3e74de39025594d50d8babf0014

data/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [0.2.0] - 2025-09-21
+
+### Added
+- Allow `permission_role_scope = :all_resources` to respect the new
+  `permission_resource_clients` whitelist so only approved clients contribute
+  to permission checks.
+- Document verikloak-bff and verikloak-audience integration patterns,
+  including `env_claims_key` examples and role naming guidance.
+
+### Changed
+- `UserContext` now snapshots the configuration at initialization to keep
+  behavior consistent even if `Verikloak::Pundit.configure` runs mid-request.
+- Bump the minimum `verikloak` runtime dependency to `>= 0.1.5` to pick up
+  client whitelist support.
+
 ## [0.1.1] - 2025-09-20
 
 ### Added

data/README.md

@@ -89,12 +89,35 @@ Verikloak::Pundit.configure do |c|
   #                         (enabling this broadens permissions to every resource client;
   #                          review the upstream role assignments before turning it on)
   c.permission_role_scope = :default_resource
+  # Optional whitelist of resource clients when `permission_role_scope = :all_resources`.
+  # Leaving this as nil keeps the legacy "all clients" behavior, while providing
+  # an explicit list (e.g., %w[rails-api verikloak-bff]) limits which clients can
+  # contribute roles to permission checks.
+  c.permission_resource_clients = nil
 
   # Expose `verikloak_claims` to views via helper_method (Rails only)
   c.expose_helper_method = true
 end
 ```
 
+### Working with other Verikloak gems
+
+- **verikloak-bff**: When your Rails application sits behind the BFF, the access
+  token presented to verikloak-pundit typically originates from the BFF
+  (e.g. via the `x-verikloak-user` header). Make sure your Rack stack stores the
+  decoded claims under the same `env_claims_key` configured above (the default
+  `"verikloak.user"` works out of the box with `verikloak-bff >= 0.3`). If the
+  BFF issues tokens for multiple downstream services, set
+  `permission_resource_clients` to the limited list of clients whose roles should
+  affect Rails-side authorization to avoid accidentally inheriting permissions
+  meant for other services.
+- **verikloak-audience**: Audience services often mint resource roles with a
+  service-specific prefix (for example, `audience-service:editor`). Align your
+  `role_map` keys with that naming convention so `user.has_permission?` resolves
+  correctly. If Audience adds its own client entry inside `resource_access`, add
+  that client id to `permission_resource_clients` when you need to consume those
+  roles from Rails.
+
 ## Non-Rails / custom usage
 
 ```ruby
@@ -142,6 +165,10 @@ If you find a security vulnerability, please follow the instructions in [SECURIT
 
 ### Operational guidance
 - Enabling `permission_role_scope = :all_resources` pulls roles from every Keycloak client in `resource_access`. Review the granted roles carefully to ensure you are not expanding permissions beyond what the application expects.
+- Combine `permission_role_scope = :all_resources` with `permission_resource_clients`
+  to explicitly opt-in the clients that may contribute permissions. Leaving the
+  whitelist blank (the default) reverts to the legacy behavior of trusting
+  every client in the token.
 - Leaving `expose_helper_method = true` exposes `verikloak_claims` to the Rails view layer. If the claims include personal or sensitive data, consider switching it to `false` and pass only the minimum required information through controller-provided helpers.
 
 ## License

data/lib/generators/verikloak/pundit/install/install_generator.rb

@@ -11,7 +11,6 @@ module Verikloak
         desc 'Creates Verikloak Pundit initializer and a base ApplicationPolicy (optional).'
 
         # Skip creating application_policy.rb
-        # @return [Boolean]
         class_option :skip_policy, type: :boolean, default: false, desc: 'Do not create application_policy.rb'
 
         # Create the initializer file under config/initializers.

data/lib/verikloak/pundit/configuration.rb

@@ -16,12 +16,16 @@ module Verikloak
     #   @return [Array<String,Proc>] path inside JWT claims to reach resource roles
     # @!attribute permission_role_scope
     #   @return [Symbol] :default_resource or :all_resources for permission mapping scope
+    # @!attribute permission_resource_clients
+    #   @return [Array<String>, nil] list of resource clients allowed when
+    #     {#permission_role_scope} is `:all_resources`. `nil` permits every client.
     # @!attribute expose_helper_method
     #   @return [Boolean] whether to register `verikloak_claims` as a Rails helper method
     class Configuration
       attr_accessor :resource_client, :role_map, :env_claims_key,
                     :realm_roles_path, :resource_roles_path,
-                    :permission_role_scope, :expose_helper_method
+                    :permission_role_scope, :permission_resource_clients,
+                    :expose_helper_method
 
       # Build a new configuration, optionally copying values from another
       # configuration so callers can mutate a safe duplicate.
@@ -64,6 +68,7 @@ module Verikloak
         @role_map = dup_hash(@role_map).freeze
         @realm_roles_path = dup_array(@realm_roles_path).freeze
         @resource_roles_path = dup_array(@resource_roles_path).freeze
+        @permission_resource_clients = freeze_permission_clients(@permission_resource_clients)
         @expose_helper_method = !@expose_helper_method.nil? && @expose_helper_method
         freeze
       end
@@ -81,6 +86,7 @@ module Verikloak
         # rubocop:enable Style/SymbolProc
         # :default_resource (realm + default client), :all_resources (realm + all clients)
         @permission_role_scope = :default_resource
+        @permission_resource_clients = nil
         @expose_helper_method = true
       end
 
@@ -95,6 +101,7 @@ module Verikloak
         @realm_roles_path = dup_array(other.realm_roles_path)
         @resource_roles_path = dup_array(other.resource_roles_path)
         @permission_role_scope = other.permission_role_scope
+        @permission_resource_clients = dup_array(other.permission_resource_clients)
         @expose_helper_method = other.expose_helper_method
       end
 
@@ -178,6 +185,17 @@ module Verikloak
 
         value.respond_to?(:dup)
       end
+
+      # Normalize and freeze the configured permission clients list.
+      #
+      # @param value [Array<String, Symbol>, nil]
+      # @return [Array<String>, nil]
+      def freeze_permission_clients(value)
+        array = dup_array(value)
+        return nil if array.nil?
+
+        array.compact.map(&:to_s).uniq.freeze
+      end
     end
   end
 end

data/lib/verikloak/pundit/user_context.rb

@@ -4,15 +4,17 @@ module Verikloak
   module Pundit
     # Lightweight wrapper around Keycloak claims for Pundit policies.
     class UserContext
-      attr_reader :claims, :resource_client
+      attr_reader :claims, :resource_client, :config
 
       # Create a new user context from JWT claims.
       #
       # @param claims [Hash] JWT claims issued by Keycloak
       # @param resource_client [String] default resource client name for resource roles
-      def initialize(claims, resource_client: Verikloak::Pundit.config.resource_client)
+      # @param config [Verikloak::Pundit::Configuration] configuration snapshot to use
+      def initialize(claims, resource_client: nil, config: nil)
+        @config = config || Verikloak::Pundit.config
         @claims = claims || {}
-        @resource_client = resource_client.to_s
+        @resource_client = (resource_client || @config.resource_client).to_s
       end
 
       # Subject identifier from claims.
@@ -30,7 +32,7 @@ module Verikloak
       # Realm-level roles from claims based on configuration path.
       # @return [Array<String>]
       def realm_roles
-        path = resolve_path(Verikloak::Pundit.config.realm_roles_path)
+        path = resolve_path(config.realm_roles_path)
         Array(claims.dig(*path))
       end
 
@@ -40,7 +42,7 @@ module Verikloak
       # @return [Array<String>]
       def resource_roles(client = resource_client)
         client = client.to_s
-        path = resolve_path(Verikloak::Pundit.config.resource_roles_path, client: client)
+        path = resolve_path(config.resource_roles_path, client: client)
         Array(claims.dig(*path))
       end
 
@@ -82,7 +84,7 @@ module Verikloak
       def has_permission?(perm) # rubocop:disable Naming/PredicatePrefix
         pr = perm.to_sym
         roles = realm_roles + resource_roles_scope
-        mapped = roles.map { |r| RoleMapper.map(r, Verikloak::Pundit.config) }
+        mapped = roles.map { |r| RoleMapper.map(r, config) }
         mapped.map(&:to_sym).include?(pr)
       end
 
@@ -91,8 +93,9 @@ module Verikloak
       # @param env [Hash] Rack environment
       # @return [UserContext]
       def self.from_env(env)
-        claims = env[Verikloak::Pundit.config.env_claims_key]
-        new(claims)
+        config = Verikloak::Pundit.config
+        claims = env[config.env_claims_key]
+        new(claims, config: config)
       end
 
       private
@@ -108,9 +111,9 @@ module Verikloak
           when Proc
             # Support lambdas that accept (config) or (config, client)
             if seg.arity >= 2
-              seg.call(Verikloak::Pundit.config, client).to_s
+              seg.call(config, client).to_s
             else
-              seg.call(Verikloak::Pundit.config).to_s
+              seg.call(config).to_s
             end
           else
             seg.to_s
@@ -121,7 +124,7 @@ module Verikloak
       # Resolve resource roles based on configured permission scope.
       # @return [Array<String>]
       def resource_roles_scope
-        case Verikloak::Pundit.config.permission_role_scope&.to_sym
+        case config.permission_role_scope&.to_sym
         when :all_resources
           resource_roles_all_clients
         else
@@ -137,7 +140,22 @@ module Verikloak
 
         # Bypass configured path lambda (which targets the default client)
         # and gather roles from all clients explicitly.
-        access.values.flat_map { |entry| Array(entry['roles']) }
+        access.each_with_object([]) do |(client_id, entry), roles|
+          next unless permission_client_allowed?(client_id)
+
+          roles.concat(Array(entry['roles']))
+        end
+      end
+
+      # Check whether the given client is allowed for permission scope.
+      #
+      # @param client_id [String]
+      # @return [Boolean]
+      def permission_client_allowed?(client_id)
+        whitelist = config.permission_resource_clients
+        return true if whitelist.nil?
+
+        whitelist.include?(client_id.to_s)
       end
     end
   end

data/lib/verikloak/pundit/version.rb

@@ -5,6 +5,6 @@ module Verikloak
     # Gem version for verikloak-pundit.
     #
     # @return [String]
-    VERSION = '0.1.1'
+    VERSION = '0.2.0'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: verikloak-pundit
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - taiyaky
@@ -49,20 +49,20 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.2
+        version: 0.1.5
     - - "<"
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: 1.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.2
+        version: 0.1.5
     - - "<"
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: 1.0.0
 description: Maps Keycloak JWT roles to a Pundit-friendly UserContext with helpers
   and a Rails generator.
 executables: []
@@ -92,7 +92,7 @@ metadata:
   source_code_uri: https://github.com/taiyaky/verikloak-pundit
   changelog_uri: https://github.com/taiyaky/verikloak-pundit/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/taiyaky/verikloak-pundit/issues
-  documentation_uri: https://rubydoc.info/gems/verikloak-pundit/0.1.1
+  documentation_uri: https://rubydoc.info/gems/verikloak-pundit/0.2.0
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: