verikloak-pundit 0.2.3 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a4618def320e58859e62b0562ac2d942a3e307a61b3c287bc3a748511c76a3d0
-  data.tar.gz: ce80df2707bf38a548ef51dc6ed68acd149e2c06b2ef02d2b0a20dc709040cbf
+  metadata.gz: 7a29b74665fc8bf023f1b6aeea48575b55227a5a4c0d8deae339b02651885814
+  data.tar.gz: fda84a30fa38d00819b5b00c4d72a2a8858355c4faaba2dcef8ec1a956df7753
 SHA512:
-  metadata.gz: 246e5840dc895ee184ef33d88ea92c5e73f58c6120217e2661e6757dd2539ee74f7ba2b2eb47502ca70115884a971ef11530458af6a8aa6f3900f96f70d1119e
-  data.tar.gz: 6d4762d24e1b90c71ea68a1642456a9b4f3132d6424ef9587bfc1f41d70c3f124ebb1c8e60ea49d273b3e73a1077ebaeac4106311e1244890a29d41af8169300
+  metadata.gz: 928b8e33c892000b074a6c8fe12aece68a14140d5994b9f13640d074b39130f560a49e3fabc1a07917e0678d89e6f8a1b797a73dcb3f579b5ffeef622398050d
+  data.tar.gz: 7c418267c589a0a13a0aafdbb2cc48c4fa4cefb87a61d8051a3257e3250790b7be48ac79b7e3fc96421c4ad1a966d0ba511277d67e872d7e7c6f5e6fced09412

data/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [0.2.4] - 2026-01-01
+
+### Added
+- **Environment variable fallback**: `resource_client` now falls back to `ENV['KEYCLOAK_RESOURCE_CLIENT']` when not explicitly configured, enabling environment-based configuration.
+- **Auto-sync with verikloak-rails**: When used alongside `verikloak-rails`, `env_claims_key` is automatically synchronized from `Verikloak::Rails.config.user_env_key` if not explicitly set.
+
+### Changed
+- **Simplified initializer template**: Generator now produces a minimal initializer with commented examples instead of explicit defaults. Most settings work out of the box.
+- **README improvements**: Updated Configuration section with environment variables table, auto-configuration documentation, and removed redundant examples.
+- **Consistent Pundit include**: Quick Start examples now use `Pundit::Authorization` consistently.
+
 ## [0.2.3] - 2025-12-31
 
 ### Added

data/README.md

@@ -43,7 +43,7 @@ For error-handling guidance, see [ERRORS.md](ERRORS.md).
 ```ruby
 # app/controllers/application_controller.rb
 class ApplicationController < ActionController::API
-  include Pundit
+  include Pundit::Authorization
   include Verikloak::Pundit::Controller  # provides pundit_user
 
   # If you're also using verikloak-rails:
@@ -65,38 +65,28 @@ Where `user` is the **UserContext** provided by `pundit_user`.
 
 ## Configuration
 
+Most settings have sensible defaults and can be auto-configured. You only need to customize what's different for your application.
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `KEYCLOAK_RESOURCE_CLIENT` | Default resource client ID for resource roles | `"rails-api"` |
+
+### Auto-configuration with verikloak-rails
+
+When used alongside `verikloak-rails`, the following settings are automatically synchronized:
+
+- **`env_claims_key`**: Inherits from `Verikloak::Rails.config.user_env_key` if you haven't explicitly set it. This ensures both gems read claims from the same Rack env key.
+
+This means in most cases you can use a minimal initializer:
+
 ```ruby
-# config/initializers/verikloak_pundit.rb
 Verikloak::Pundit.configure do |c|
-  c.resource_client = "rails-api"   # default client for resource roles
-  c.role_map = {                    # optional role → permission mapping
+  c.role_map = {
     admin:  :manage_all,
-    editor: :write_notes,
-    reader: :read_notes
+    editor: :write_notes
   }
-  # Where to find claims in Rack env (when using verikloak/verikloak-rails)
-  c.env_claims_key = "verikloak.user"
-
-  # How to traverse JWT for roles
-  c.realm_roles_path    = %w[realm_access roles]                      # => claims["realm_access"]["roles"]
-  # Lambdas in the path may accept (cfg) or (cfg, client)
-  # where `client` is the argument passed to `user.resource_roles(client)`
-  c.resource_roles_path = ["resource_access", ->(cfg){ cfg.resource_client }, "roles"]
-
-  # Permission mapping scope for `user.has_permission?`:
-  #   :default_resource => realm roles + default client roles (recommended)
-  #   :all_resources    => realm roles + roles from all clients in resource_access
-  #                         (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
 ```
 
@@ -105,12 +95,11 @@ end
 - **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.
+  decoded claims under the same `env_claims_key` (default: `"verikloak.user"`,
+  which 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
@@ -319,35 +308,16 @@ RSpec.configure do |config|
 end
 ```
 
-An additional integration check exercises the gem together with the latest `verikloak` and `verikloak-rails` releases. This runs in CI automatically, and you can execute it locally with:
-
-```bash
-docker compose run --rm -e BUNDLE_FROZEN=0 dev bash -lc '
-  cd integration && \
-  apk add --no-cache --virtual .integration-build-deps \
-    build-base \
-    linux-headers \
-    openssl-dev \
-    yaml-dev && \
-  bundle config set --local path vendor/bundle && \
-  bundle install --jobs 4 --retry 3 && \
-  bundle exec ruby check.rb && \
-  apk del .integration-build-deps
-'
-```
-
 ## Contributing
 Bug reports and pull requests are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.
 
 ## Security
 If you find a security vulnerability, please follow the instructions in [SECURITY.md](SECURITY.md).
 
-### Operational guidance
+## 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.
+- 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/templates/initializer.rb

@@ -1,24 +1,28 @@
 # frozen_string_literal: true
 
 # Verikloak::Pundit initializer
-# Configure how to read roles from Keycloak claims and how to map them
-# into application permissions.
+#
+# Most settings are auto-configured from environment variables and verikloak-rails.
+# Uncomment and customize only what you need to override.
+#
+# Environment variables supported:
+#   KEYCLOAK_RESOURCE_CLIENT - resource client ID (default: 'rails-api')
+#
+# When used with verikloak-rails, env_claims_key is automatically synchronized.
 Verikloak::Pundit.configure do |c|
-  c.resource_client = ENV.fetch('KEYCLOAK_RESOURCE_CLIENT', 'rails-api')
-  c.role_map = {
-    # admin:  :manage_all,
-    # editor: :write_notes,
-    # reader: :read_notes
-  }
-  c.env_claims_key = 'verikloak.user'
-  # claims['realm_access']['roles']
-  c.realm_roles_path    = %w[realm_access roles]
-  # rubocop:disable Style/SymbolProc -- we need a Proc object here, not block pass
-  # claims['resource_access'][resource_client]['roles']
-  c.resource_roles_path = ['resource_access', ->(cfg) { cfg.resource_client }, 'roles']
-  # rubocop:enable Style/SymbolProc
-  # Permission mapping scope:
-  #   :default_resource => realm roles + default client roles (recommended)
-  #   :all_resources    => realm roles + roles from all clients in resource_access
-  c.permission_role_scope = :default_resource
+  # Resource client (optional - falls back to ENV['KEYCLOAK_RESOURCE_CLIENT'] or 'rails-api')
+  # c.resource_client = ENV.fetch('KEYCLOAK_RESOURCE_CLIENT', 'rails-api')
+
+  # Role to permission mapping (optional)
+  # c.role_map = {
+  #   admin:  :manage_all,
+  #   editor: :write_notes,
+  #   reader: :read_notes
+  # }
+
+  # Uncomment to customize JWT claims path and scope (usually not needed):
+  # c.env_claims_key = 'verikloak.user'
+  # c.realm_roles_path = %w[realm_access roles]
+  # c.resource_roles_path = ['resource_access', ->(cfg) { cfg.resource_client }, 'roles']
+  # c.permission_role_scope = :default_resource  # or :all_resources
 end

data/lib/verikloak/pundit/configuration.rb

@@ -22,11 +22,20 @@ module Verikloak
     # @!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,
+      attr_accessor :role_map, :env_claims_key,
                     :realm_roles_path, :resource_roles_path,
                     :permission_role_scope, :permission_resource_clients,
                     :expose_helper_method
 
+      attr_writer :resource_client
+
+      # Returns the resource client, falling back to ENV['KEYCLOAK_RESOURCE_CLIENT'] if not set.
+      #
+      # @return [String]
+      def resource_client
+        @resource_client || ENV.fetch('KEYCLOAK_RESOURCE_CLIENT', 'rails-api')
+      end
+
       # Build a new configuration, optionally copying values from another
       # configuration so callers can mutate a safe duplicate.
       #
@@ -77,7 +86,7 @@ module Verikloak
 
       # Populate default values that mirror the gem's out-of-the-box behavior.
       def initialize_defaults
-        @resource_client   = 'rails-api'
+        @resource_client   = nil # Falls back to ENV['KEYCLOAK_RESOURCE_CLIENT'] or 'rails-api'
         @role_map          = {} # e.g., { admin: :manage_all }
         @env_claims_key    = 'verikloak.user'
         @realm_roles_path  = %w[realm_access roles]

data/lib/verikloak/pundit/railtie.rb

@@ -12,6 +12,35 @@ module Verikloak
           include Verikloak::Pundit::Controller
         end
       end
+
+      # Synchronize configuration with verikloak-rails when available.
+      # Runs after verikloak-rails configuration is applied.
+      initializer 'verikloak_pundit.sync_configuration', after: 'verikloak.configure' do
+        sync_with_verikloak_rails if defined?(Verikloak::Rails)
+      end
+
+      class << self
+        # Sync env_claims_key with verikloak-rails configuration.
+        # Only applies if env_claims_key has not been explicitly set.
+        #
+        # @return [void]
+        def sync_with_verikloak_rails
+          return unless Verikloak::Rails.respond_to?(:config)
+
+          rails_config = Verikloak::Rails.config
+          return unless rails_config.respond_to?(:user_env_key) && rails_config.user_env_key
+
+          current_key = Verikloak::Pundit.config.env_claims_key
+          return unless current_key == 'verikloak.user'
+
+          # Use configure to properly update frozen config
+          Verikloak::Pundit.configure do |c|
+            c.env_claims_key = rails_config.user_env_key
+          end
+        rescue StandardError => e
+          warn "[verikloak-pundit] Failed to sync with verikloak-rails: #{e.message}"
+        end
+      end
     end
   end
 end

data/lib/verikloak/pundit/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: verikloak-pundit
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.2.4
 platform: ruby
 authors:
 - taiyaky
@@ -94,7 +94,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.2.3
+  documentation_uri: https://rubydoc.info/gems/verikloak-pundit/0.2.4
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: