verikloak-audience 0.2.5 → 0.2.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3b5e110926bc9c76f3fd1060601f6633ac033e1d8e4609e87be95a7a7d96f0a4
-  data.tar.gz: 50fb3c748a6702d63a049a3dc70d27739bf80e00719880d195d00e854d6c0586
+  metadata.gz: 59d9195c0dfe4835b91a16bf8f08a58369f398890b5aff664979421a388a91d1
+  data.tar.gz: 8bd59e610df30f6eb1238b06f12a2778ddb0287264a967424751db38acae2f81
 SHA512:
-  metadata.gz: c3555c88018205a6d4f7926c8316e9b188e7401a920376cae45cf1100830c29b47dfb3f8d6f0975bb37fbeab09758327f91975ede97e3dedc1427a4dd603f557
-  data.tar.gz: 9e701c727b9049fe912fdca6763c3e88e57bf53f951d69303653ec0430d6ff814ff69d2bdef36277c98c9dbf47c29ef00f4b209c84a2cf6cfd3c70f300dca967
+  metadata.gz: 0d5d65f4ff5ca863d1f638b7e19a71edb256aa905bcc21b1ac49802b4c8db53697ed50d6f45bd67730a147a215972ddadbc78a403155e5d3b6ea1cf5b341dc69
+  data.tar.gz: c149176b446b3021204c039d2a07f9297676b57db52ae63f40812029b7f899c7398a425ba1a1542f058303e5a0615d51ebd793b5610d1c9feeb98bd7009c1c88

data/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [0.2.7] - 2025-09-27
+
+### Changed
+- Rails Railtie now syncs `env_claims_key`, `required_aud`, and `resource_client` defaults with verikloak-rails configuration after boot.
+- Generator template converted to ERB and bundled with the gem so `rails g verikloak:audience:install` produces the initializer without relying on Rails internals.
+- Middleware option validation tightened to fail fast on unknown overrides with clearer error messages.
+
+### Documentation
+- Added RubyDoc comments across the Railtie to clarify initializer responsibilities and helper methods.
+
+## [0.2.6] - 2025-09-23
+
+### Added
+- Rails generator `verikloak:audience:install` to create an initializer that inserts the audience middleware once the core Verikloak middleware is available.
+
+### Changed
+- Improved warning message when core Verikloak middleware is not present in the Rails middleware stack.
+- Enhanced middleware insertion logic to provide clearer guidance on setup requirements.
+
 ## [0.2.5] - 2025-09-23
 
 ### Changed

data/README.md

@@ -30,9 +30,17 @@ For the full error behaviour (response shapes, exception classes, logging hints)
 bundle add verikloak-audience
 ```
 
-## Rack / Rails usage
+In Rails applications, generate the initializer that automatically inserts the middleware:
 
-Insert **after** `Verikloak::Middleware`:
+```bash
+rails g verikloak:audience:install
+```
+
+This creates `config/initializers/verikloak_audience.rb` that will insert the audience middleware after the core Verikloak middleware once it's available.
+
+## Manual Rack / Rails setup
+
+Alternatively, you can manually insert **after** `Verikloak::Middleware`:
 
 ```ruby
 # config/application.rb

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+begin
+  require 'rails/generators'
+  require 'rails/generators/base'
+rescue LoadError
+  raise unless defined?(Rails::Generators::Base)
+end
+
+module Verikloak
+  module Audience
+    module Generators
+      # Installs the verikloak audience middleware configuration into a Rails
+      # application. This generator creates an initializer that inserts the
+      # audience middleware after the core Verikloak middleware once it is
+      # available.
+      class InstallGenerator < Rails::Generators::Base
+        source_root File.expand_path('templates', __dir__)
+
+        def create_initializer
+          template 'initializer.rb.erb', 'config/initializers/verikloak_audience.rb'
+        end
+      end
+    end
+  end
+end

data/lib/generators/verikloak/audience/install/templates/initializer.rb.erb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# Insert the audience middleware after the core Verikloak middleware once it
+# has been loaded into the application.
+if defined?(Rails) && Rails.respond_to?(:application)
+  Verikloak::Audience::Railtie.insert_middleware(Rails.application)
+end

data/lib/verikloak/audience/checker.rb

@@ -44,7 +44,7 @@ module Verikloak
       # @param required [Array<String>]
       # @return [Boolean]
       def strict_single?(claims, required)
-        aud = Array(claims['aud']).map(&:to_s)
+        aud = normalized_audiences(claims)
         return false if required.empty?
 
         # Must contain all required and have no unexpected extra (order-insensitive)
@@ -57,7 +57,7 @@ module Verikloak
       # @param required [Array<String>]
       # @return [Boolean]
       def allow_account?(claims, required)
-        aud = Array(claims['aud']).map(&:to_s)
+        aud = normalized_audiences(claims)
         return false if required.empty?
 
         # Permit 'account' extra
@@ -89,13 +89,10 @@ module Verikloak
       def suggest(claims, cfg)
         claims = normalize_claims(claims)
 
-        aud = Array(claims['aud']).map(&:to_s)
-        req = cfg.required_aud_list
-        has_roles = !Array(claims.dig('resource_access', cfg.resource_client.to_s, 'roles')).empty?
-
-        return :strict_single if aud.sort == req.sort
-        return :allow_account if (aud - req) == ['account'] && (req - aud).empty?
-        return :resource_or_aud if has_roles
+        required = cfg.required_aud_list
+        return :strict_single if strict_single?(claims, required)
+        return :allow_account if allow_account?(claims, required)
+        return :resource_or_aud if resource_or_aud?(claims, cfg.resource_client.to_s, required)
 
         :strict_single
       end
@@ -120,6 +117,16 @@ module Verikloak
       end
       module_function :normalize_claims
       private_class_method :normalize_claims
+
+      # Normalize audience claims into a predictable array of strings.
+      #
+      # @param claims [Hash]
+      # @return [Array<String>]
+      def normalized_audiences(claims)
+        Array(claims['aud']).map(&:to_s)
+      end
+      module_function :normalized_audiences
+      private_class_method :normalized_audiences
     end
   end
 end

data/lib/verikloak/audience/configuration.rb

@@ -23,6 +23,7 @@ module Verikloak
     #   @return [Boolean]
     class Configuration
       DEFAULT_RESOURCE_CLIENT = 'rails-api'
+      DEFAULT_ENV_CLAIMS_KEY = 'verikloak.user'
 
       attr_accessor :profile, :required_aud, :resource_client,
                     :suggest_in_logs
@@ -35,7 +36,7 @@ module Verikloak
         @profile         = :strict_single
         @required_aud    = []
         @resource_client = DEFAULT_RESOURCE_CLIENT
-        self.env_claims_key = 'verikloak.user'
+        self.env_claims_key = DEFAULT_ENV_CLAIMS_KEY
         @suggest_in_logs = true
       end
 
@@ -121,23 +122,19 @@ module Verikloak
       # @return [void]
       def ensure_resource_client!(audiences)
         client = resource_client.to_s
+        error_msg = 'resource_client must match one of required_aud when using :resource_or_aud profile'
 
-        needs_inference = needs_resource_client_inference?(client, audiences)
+        if needs_resource_client_inference?(client, audiences)
+          raise Verikloak::Audience::ConfigurationError, error_msg unless audiences.one?
+
+          self.resource_client = audiences.first
+          client = resource_client.to_s
 
-        if needs_inference
-          if audiences.one?
-            self.resource_client = audiences.first
-            client = resource_client.to_s
-          else
-            raise Verikloak::Audience::ConfigurationError,
-                  'resource_client must match one of required_aud when using :resource_or_aud profile'
-          end
         end
 
         return if audiences.include?(client)
 
-        raise Verikloak::Audience::ConfigurationError,
-              'resource_client must match one of required_aud when using :resource_or_aud profile'
+        raise Verikloak::Audience::ConfigurationError, error_msg
       end
 
       # Decide whether the resource client should be inferred from the

data/lib/verikloak/audience/middleware.rb

@@ -57,16 +57,14 @@ module Verikloak
       # @return [void]
       def apply_overrides!(opts)
         cfg = @config
-        opts.each_key do |key|
+        opts.each do |key, value|
           writer = "#{key}="
-          next if cfg.respond_to?(writer)
+          unless cfg.respond_to?(writer)
+            raise Verikloak::Audience::ConfigurationError,
+                  "unknown middleware option :#{key}"
+          end
 
-          raise Verikloak::Audience::ConfigurationError,
-                "unknown middleware option :#{key}"
-        end
-
-        opts.each do |k, v|
-          cfg.public_send("#{k}=", v)
+          cfg.public_send(writer, value)
         end
       end
 
@@ -90,11 +88,9 @@ module Verikloak
       # @return [void]
       def log_warning(env, message)
         logger = env['verikloak.logger'] || env['rack.logger'] || env['action_dispatch.logger']
-        if logger.respond_to?(:warn)
-          logger.warn(message)
-        else
-          warn(message)
-        end
+        return logger.warn(message) if logger.respond_to?(:warn)
+
+        Kernel.warn(message)
       end
     end
   end

data/lib/verikloak/audience/railtie.rb

@@ -35,6 +35,7 @@ module Verikloak
 
       initializer 'verikloak_audience.configuration' do
         config.after_initialize do
+          self.class.apply_verikloak_rails_configuration
           next if Verikloak::Audience::Railtie.skip_configuration_validation?
 
           Verikloak::Audience.config.validate!
@@ -42,15 +43,61 @@ module Verikloak
       end
 
       # Performs the insertion into the middleware stack when the core
-      # Verikloak middleware is available. Extracted for testability without
-      # requiring a full Rails boot process.
+      # Verikloak middleware is available and already present. Extracted for
+      # testability without requiring a full Rails boot process.
+      #
+      # Insert the audience middleware after the base Verikloak middleware when
+      # both are available on the stack.
       #
       # @param app [#middleware] An object exposing a Rack middleware stack via `#middleware`.
       # @return [void]
       def self.insert_middleware(app)
         return unless defined?(::Verikloak::Middleware)
 
-        app.middleware.insert_after ::Verikloak::Middleware, ::Verikloak::Audience::Middleware
+        middleware_stack = app.middleware
+        return unless middleware_stack.respond_to?(:include?)
+
+        return if middleware_stack.include?(::Verikloak::Audience::Middleware)
+
+        unless middleware_stack.include?(::Verikloak::Middleware)
+          warn_missing_core_middleware
+          return
+        end
+
+        middleware_stack.insert_after ::Verikloak::Middleware, ::Verikloak::Audience::Middleware
+      end
+
+      WARNING_MESSAGE = <<~MSG
+        [verikloak-audience] Skipping automatic middleware insertion because ::Verikloak::Middleware
+        is not present in the Rails middleware stack.
+
+        To enable verikloak-audience, first ensure that the core Verikloak middleware (`Verikloak::Middleware`)
+        is added to your Rails middleware stack. Once the core middleware is present, you can run
+        `rails g verikloak:audience:install` to generate the initializer for the audience middleware,
+        or manually add:
+
+          config.middleware.insert_after Verikloak::Middleware, Verikloak::Audience::Middleware
+
+        This warning will disappear once the core middleware is properly configured and the audience
+        middleware is inserted.
+      MSG
+
+      # Logs a warning message when the core Verikloak middleware is missing
+      # from the Rails middleware stack. Uses the Rails logger if available,
+      # otherwise falls back to Kernel.warn for output.
+      #
+      # This method is called when automatic middleware insertion is skipped
+      # due to the absence of the required core middleware.
+      #
+      # @return [void]
+      def self.warn_missing_core_middleware
+        logger = (::Rails.logger if defined?(::Rails) && ::Rails.respond_to?(:logger))
+
+        if logger
+          logger.warn(WARNING_MESSAGE)
+        else
+          Kernel.warn(WARNING_MESSAGE)
+        end
       end
 
       # Rails short commands (`g`, `d`) are stripped from ARGV fairly early in
@@ -64,25 +111,32 @@ module Verikloak
       #
       # @return [Boolean]
       def self.skip_configuration_validation?
-        command = first_rails_command
-        return false unless command
+        tokens = first_cli_tokens
+        return false if tokens.empty?
+
+        command = tokens.first
+        return true if COMMANDS_SKIPPING_VALIDATION.include?(command)
 
-        COMMANDS_SKIPPING_VALIDATION.include?(command) || verikloak_install_generator?(command)
+        tokens.any? { |token| verikloak_install_generator?(token) }
       end
 
-      # Capture the first non-option argument passed to the Rails CLI,
-      # ignoring wrapper tokens such as "rails".
+      # Capture the first non-option arguments passed to the Rails CLI,
+      # ignoring wrapper tokens such as "rails". Only the first two tokens are
+      # relevant for generator detection, so we keep the return list short.
       #
-      # @return [String, nil]
-      def self.first_rails_command
+      # @return [Array<String>] ordered CLI tokens that may signal a generator
+      def self.first_cli_tokens
+        tokens = []
+
         ARGV.each do |arg|
           next if arg.start_with?('-')
           next if arg == 'rails'
 
-          return arg
+          tokens << arg
+          break if tokens.size >= 2
         end
 
-        nil
+        tokens
       end
 
       # Detect whether the provided CLI token refers to a Verikloak install
@@ -95,6 +149,118 @@ module Verikloak
 
         command.start_with?('verikloak:') && command.end_with?(':install')
       end
+
+      class << self
+        # Synchronize configuration with verikloak-rails when it is present.
+        # Aligns env_claims_key, required_aud, and resource_client defaults so
+        # that both gems operate on the same Rack env payload and audience list.
+        #
+        # @return [void]
+        def apply_verikloak_rails_configuration
+          rails_config = verikloak_rails_config
+          return unless rails_config
+
+          Verikloak::Audience.configure do |cfg|
+            sync_env_claims_key(cfg, rails_config)
+            sync_required_aud(cfg, rails_config)
+            sync_resource_client(cfg, rails_config)
+          end
+        end
+
+        private
+
+        # Resolve the verikloak-rails configuration object if the gem is loaded.
+        #
+        # @return [Verikloak::Rails::Configuration, nil]
+        def verikloak_rails_config
+          return unless defined?(::Verikloak::Rails)
+          return unless ::Verikloak::Rails.respond_to?(:config)
+
+          ::Verikloak::Rails.config
+        rescue StandardError
+          nil
+        end
+
+        # Align the environment claims key with the one configured in verikloak-rails.
+        #
+        # @param cfg [Verikloak::Audience::Configuration]
+        # @param rails_config [Verikloak::Rails::Configuration]
+        # @return [void]
+        def sync_env_claims_key(cfg, rails_config)
+          return unless rails_config.respond_to?(:user_env_key)
+
+          user_key = rails_config.user_env_key
+          return if blank?(user_key)
+
+          current = cfg.env_claims_key
+          return unless current.nil? || current == Verikloak::Audience::Configuration::DEFAULT_ENV_CLAIMS_KEY
+
+          cfg.env_claims_key = user_key
+        end
+
+        # Populate required audiences from the verikloak-rails configuration when absent.
+        #
+        # @param cfg [Verikloak::Audience::Configuration]
+        # @param rails_config [Verikloak::Rails::Configuration]
+        # @return [void]
+        def sync_required_aud(cfg, rails_config)
+          return unless cfg_required_aud_blank?(cfg)
+          return unless rails_config.respond_to?(:audience)
+
+          audiences = normalized_audiences(rails_config.audience)
+          return if audiences.empty?
+
+          cfg.required_aud = audiences.size == 1 ? audiences.first : audiences
+        end
+
+        # Infer the resource client based on the configured audience when possible.
+        #
+        # @param cfg [Verikloak::Audience::Configuration]
+        # @param rails_config [Verikloak::Rails::Configuration]
+        # @return [void]
+        def sync_resource_client(cfg, rails_config)
+          return unless rails_config.respond_to?(:audience)
+
+          audiences = normalized_audiences(rails_config.audience)
+          return unless audiences.size == 1
+
+          current_client = cfg.resource_client
+          unless blank?(current_client) || current_client == Verikloak::Audience::Configuration::DEFAULT_RESOURCE_CLIENT
+            return
+          end
+
+          cfg.resource_client = audiences.first
+        end
+
+        # Determine whether the audience configuration is effectively empty.
+        #
+        # @param cfg [Verikloak::Audience::Configuration]
+        # @return [Boolean]
+        def cfg_required_aud_blank?(cfg)
+          value_blank?(cfg.required_aud)
+        end
+
+        # Generic blank? helper that tolerates nil, empty, or blank-ish values.
+        #
+        # @param value [Object]
+        # @return [Boolean]
+        def value_blank?(value)
+          return true if value.nil?
+          return true if value.respond_to?(:empty?) && value.empty?
+
+          value.to_s.empty?
+        end
+
+        alias blank? value_blank?
+
+        # Coerce the given source into an array of non-empty string audiences.
+        #
+        # @param source [Object]
+        # @return [Array<String>]
+        def normalized_audiences(source)
+          Array(source).compact.map(&:to_s).reject(&:empty?)
+        end
+      end
     end
   end
 end

data/lib/verikloak/audience/version.rb

@@ -4,6 +4,6 @@ module Verikloak
   module Audience
     # Current gem version.
     # @return [String]
-    VERSION = '0.2.5'
+    VERSION = '0.2.7'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: verikloak-audience
 version: !ruby/object:Gem::Version
-  version: 0.2.5
+  version: 0.2.7
 platform: ruby
 authors:
 - taiyaky
@@ -59,6 +59,8 @@ files:
 - CHANGELOG.md
 - LICENSE
 - README.md
+- lib/generators/verikloak/audience/install/install_generator.rb
+- lib/generators/verikloak/audience/install/templates/initializer.rb.erb
 - lib/verikloak-audience.rb
 - lib/verikloak/audience.rb
 - lib/verikloak/audience/checker.rb
@@ -74,7 +76,7 @@ metadata:
   source_code_uri: https://github.com/taiyaky/verikloak-audience
   changelog_uri: https://github.com/taiyaky/verikloak-audience/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/taiyaky/verikloak-audience/issues
-  documentation_uri: https://rubydoc.info/gems/verikloak-audience/0.2.5
+  documentation_uri: https://rubydoc.info/gems/verikloak-audience/0.2.7
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: