verikloak-audience 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2d271ae972e5464242fbc23bd697f351c87f3ffb84379ba7ea4b17f52a477de7
-  data.tar.gz: 0cc935edcc2536918f7e6f44971e971e1dcf0b4a73ae9bb75b0c3c99c0eec180
+  metadata.gz: 14ece6bb132264abcd755a0904c92d4f8b4f63b3615e25dd76c9101b2af04a96
+  data.tar.gz: f546f6e3510e3453a62726cf6b2304653f78d9939f500a0ee2fff076332dd327
 SHA512:
-  metadata.gz: d78f43e41a67e402572643a5586e3b438498612f4d413a3462fcf7688085989018417f521af4a63fff651c256e3257e3aad3e15c1a1bca4e5127e7eae096656f
-  data.tar.gz: 1d1ed067177f17426399c27394e083c9231fbc6838ab0f90d99936e1e25182c07f5eb1b00c73780b88611565a96c7aa2ad854cb4d029d420a28ff54de2f10362
+  metadata.gz: 27062866e3d84df87c309ca11d29cdcd39b6b85909a572498c12ba88cce3d7ff135963de5fb0b560a8380340872dda10c1a81376962b86bcb3394398aab8567a
+  data.tar.gz: '08c8ea868d6db70f9f738a6967d49276bd9b72473c528a0302ea4f4aeadbe6c383ae7cdd153c25a7dcb2857ca35be26f5abc87eac2764fd12b859204536c0390'

data/CHANGELOG.md

@@ -7,6 +7,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [1.1.0] - 2026-07-03
+
+### Added
+- **Boot-time profile validation**: `Configuration#validate!` now rejects unknown `profile` values, so misspellings (e.g. `:strict_signle` instead of `:strict_single`) fail fast at startup instead of raising on the first request
+- **`Configuration#normalized_profile` / `#validated_profile`**: Shared profile coercion and validation helpers (Symbol coercion, default fallback, unknown-profile check) used by both `validate!` and `Checker`
+- **JSON 500 for request-time configuration errors**: When a `ConfigurationError` surfaces during a request (normally prevented by boot-time validation), the middleware now renders a JSON error response (`audience_configuration_error`, status 500) instead of leaking the exception through the Rack stack; the response body stays generic and the failure detail is written to the request logger
+- **`Checker.observed_audiences`**: Public helper returning the normalized audience values seen in a claims payload, used by the middleware so rejection logs show the same audiences the checker evaluated (including duck-typed `#to_hash` claims)
+- **CI Ruby matrix**: RSpec now runs against Ruby 3.1 / 3.2 / 3.3 / 3.4 (all series supported by the gemspec) — the Docker-based job covers the development Ruby (3.4) and a non-Docker `ruby/setup-ruby` matrix covers 3.1–3.3, mirroring verikloak core's CI layout
+- **Coverage floor**: SimpleCov now enforces a minimum line coverage of 90% in CI (not enforced for focused local runs)
+- **MAINTAINERS.md**: Release instructions referenced from the README now exist
+- Tests for the `Forbidden`/`Error`/`ConfigurationError` classes, the Railtie `discovery_url` guard, the `REQUEST_PATH` fallback, and Symbol inputs to the public checker predicates
+
+### Changed
+- **`Checker.suggest` accepts a `fallback:` keyword** (default `:strict_single`, preserving the 1.0 always-Symbol contract): the middleware passes `fallback: nil`, so rejection logs read `no profile matches the observed aud` instead of naming a misleading suggestion
+- **Middleware boot-time validation now evaluates the middleware's own (post-override) configuration**, so options passed via `config.middleware.use` are validated at startup even when the global configuration is untouched
+- Values synced from verikloak-rails now follow its own resolution rules: `user_env_key` is whitespace-stripped and blank values are treated as unset (both middlewares then share the `verikloak.user` default, mirroring `effective_user_env_key` in verikloak-rails >= 1.2), and blank `required_aud`/`resource_client` are treated as unset
+- Runtime dependency raised to `verikloak ~> 1.1` (was `~> 1.0`); lockfile updated to verikloak 1.1.0
+- `Checker::VALID_PROFILES` is now an alias of `Configuration::VALID_PROFILES` (same values; the canonical definition moved)
+- All public checker predicates (`strict_single?`, `allow_account?`, `any_match?`) now coerce `required` inputs consistently, accepting Symbols and single values
+- `Railtie.skip_validation?` combines the generator-mode and unconfigured checks and takes the configuration under validation as an argument; the middleware and the after-initialize hook now share it
+
+### Fixed
+- **CI coverage was never measured**: The `SIMPLECOV` environment variable set in GitHub Actions never reached the Docker container; `compose.yml` now passes it through, so coverage reports are actually generated in CI
+- Removed dead code paths (`env_key&.to_sym` safe navigation, unreachable `nil` check in `sync_env_claims_key`) and redundant `module_function` declarations in `Checker`
+
+---
+
 ## [1.0.0] - 2026-02-15
 
 ### Fixed

data/ERRORS.md

@@ -0,0 +1,48 @@
+# Verikloak Audience Error Reference
+
+This document captures the *current* error behaviour implemented by the `verikloak-audience` gem. Use it as a developer aid when wiring the middleware or surfacing audience failures to callers.
+
+## Response Shape
+- Status: `403 Forbidden` (or `500 Internal Server Error` for configuration failures, see below)
+- Headers: `Content-Type: application/json`
+- Body: `{ "error": <code>, "message": <text> }`
+- Authentication headers: none added by this gem (the upstream Verikloak middleware already emits `WWW-Authenticate`).
+
+Example 403 response:
+```http
+HTTP/1.1 403 Forbidden
+Content-Type: application/json
+
+{"error":"insufficient_audience","message":"Audience not acceptable for profile strict_single"}
+```
+
+## Error Catalog
+
+| Code                           | HTTP | Message template                                   | Trigger |
+|--------------------------------|------|----------------------------------------------------|---------|
+| `insufficient_audience`        | 403  | `Audience not acceptable for profile <profile>`    | Returned whenever the configured audience profile does not match the claims loaded from `env[config.env_claims_key]`. |
+| `audience_configuration_error` | 500  | `audience configuration error` | Returned when a configuration problem (e.g. an unknown `profile`) is detected while evaluating a request. The body stays generic; the failure detail (e.g. the invalid profile value) is written to the request logger only. Boot-time validation (`Configuration#validate!`) normally catches this before any request is served; this response guards deployments where validation was skipped (e.g. an unconfigured Rails boot). |
+
+### Trigger details
+- Claims are read from `env[config.env_claims_key]` (default: `"verikloak.user"`). Missing claims are treated as `{}`.
+- Validation is delegated to `Verikloak::Audience::Checker.ok?`, which supports profiles `:strict_single`, `:allow_account`, `:any_match`, and `:resource_or_aud`.
+- When validation fails and `config.suggest_in_logs` is true (default), the middleware emits a `warn` message to STDERR such as:
+  ```
+  [verikloak-audience] insufficient_audience; suggestion profile=:allow_account aud=["my-api","account"]
+  ```
+  When no profile would accept the observed claims, the log reads `no profile matches the observed aud` instead of naming a profile. This logging side-effect has no impact on the HTTP response.
+
+## Exception Classes
+
+| Class                                | Default code               | Default status | Notes |
+|--------------------------------------|----------------------------|----------------|-------|
+| `Verikloak::Audience::Error`         | `audience_error`           | 403            | Base class exposing `#code` and `#http_status`; not raised automatically by the middleware but available for host apps. |
+| `Verikloak::Audience::Forbidden`     | `insufficient_audience`    | 403            | Thin wrapper around `Error`. Useful if your application raises exceptions instead of returning JSON responses directly. |
+| `Verikloak::Audience::ConfigurationError` | `audience_configuration_error` | 500     | Raised by `Configuration#validate!` and configuration writers when settings are missing or inconsistent; rendered as the 500 JSON response if it surfaces during a request. |
+
+These classes exist for integration purposes (e.g., controller helpers) and mirror the JSON shape returned by the Rack middleware. If you rescue them inside a Rails app, you can map them to the same 403 payload shown above.
+
+## Operational Notes
+- Audience mismatches always resolve to the single 403 response. The only other status this gem emits is the 500 `audience_configuration_error` response described above, which signals a misconfiguration rather than a client failure.
+- Upstream Verikloak middleware remains responsible for token verification errors (401/503/etc.). Place `Verikloak::Audience::Middleware` after it so that verified claims are available for audience checks.
+- Adjust `config.required_aud`, `config.profile`, and `config.resource_client` to control what qualifies as a passing audience.

data/MAINTAINERS.md

@@ -0,0 +1,42 @@
+# Maintainers Guide
+
+Release instructions for `verikloak-audience`. For contribution guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Prerequisites
+
+- Push access to this repository and ownership of the gem on [RubyGems.org](https://rubygems.org/gems/verikloak-audience)
+- MFA enabled on your RubyGems account (`rubygems_mfa_required` is set in the gemspec, so pushes without MFA are rejected)
+
+## Release checklist
+
+1. Ensure `main` is green (RSpec across all supported Rubies, RuboCop, bundler-audit).
+2. Bump the version in `lib/verikloak/audience/version.rb` following [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+3. Add a dated entry to `CHANGELOG.md` describing the changes (Keep a Changelog format).
+4. Update `Gemfile.lock` so the lockfile records the new version:
+   ```bash
+   docker compose run --rm dev bundle install
+   ```
+5. Run the full test suite one more time:
+   ```bash
+   docker compose run --rm dev rspec
+   docker compose run --rm dev rubocop
+   ```
+6. Commit the release changes and open a pull request. Merge once CI passes.
+7. Tag the merge commit on `main` and push the tag:
+   ```bash
+   git tag v<VERSION>
+   git push origin v<VERSION>
+   ```
+8. Build and publish the gem:
+   ```bash
+   gem build verikloak-audience.gemspec
+   gem push verikloak-audience-<VERSION>.gem
+   ```
+9. Verify the release on [RubyGems.org](https://rubygems.org/gems/verikloak-audience) and check that
+   [rubydoc.info](https://rubydoc.info/gems/verikloak-audience) picks up the new version.
+
+## Compatibility policy
+
+- Keep the runtime dependency pinned to the current minor floor of the core gem (currently `verikloak ~> 1.1`).
+- Supported Ruby versions follow the gemspec (`>= 3.1`); the CI matrix must cover every supported series.
+- Coordinate breaking changes with the other gems in the Verikloak family (verikloak, verikloak-rails, verikloak-bff, verikloak-pundit) so error hierarchies and Rack env keys stay aligned.

data/README.md

@@ -69,7 +69,7 @@ See [`examples/rack.ru`](examples/rack.ru) for a full Rack sample. In Rails, alw
 `env_claims_key` assumes the preceding `Verikloak::Middleware` populates the Rack env. If the middleware order changes, claims will be missing and the audience check will always reject.
 
 ### Operational safeguards
-- Middleware initialisation now fails fast when `required_aud` is empty. When Rails loads via the supplied Railtie, `Verikloak::Audience.config.validate!` runs after boot so configuration mistakes surface during startup instead of returning 403 for every request.
+- Middleware initialisation now fails fast when `required_aud` is empty or `profile` is not one of the supported profiles. When Rails loads via the supplied Railtie, `Verikloak::Audience.config.validate!` runs after boot so configuration mistakes surface during startup instead of returning 403 for every request. If a configuration problem still slips through to request time (e.g. validation was skipped during an unconfigured boot), the middleware responds with a generic JSON 500 `audience_configuration_error` and logs the failure detail server-side instead of leaking an exception.
 - When audience validation fails, the middleware consults `env['verikloak.logger']`, `env['rack.logger']`, and `env['action_dispatch.logger']` (in that order) before falling back to Ruby's `Kernel#warn`, keeping failure logs consistent with Rails and Verikloak observers.
 - For the `:resource_or_aud` profile, `resource_client` must match one of the values in `required_aud`. A single-element `required_aud` automatically infers the client id, ensuring the same client identifier is shared with downstream BFF/Pundit integrations.
 

data/lib/verikloak/audience/checker.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'verikloak/audience/configuration'
+
 module Verikloak
   module Audience
     # Audience profile checker functions.
@@ -7,7 +9,9 @@ module Verikloak
     # This module provides predicate helpers used by the middleware to decide
     # whether a given set of claims satisfies the configured profile.
     module Checker
-      VALID_PROFILES = %i[strict_single allow_account any_match resource_or_aud].freeze
+      # Kept for backward compatibility; the canonical definition lives in
+      # {Verikloak::Audience::Configuration::VALID_PROFILES}.
+      VALID_PROFILES = Verikloak::Audience::Configuration::VALID_PROFILES
 
       module_function
 
@@ -15,18 +19,11 @@ module Verikloak
       #
       # @param claims [Hash] OIDC claims (expects keys like "aud", "resource_access")
       # @param cfg [Verikloak::Audience::Configuration]
+      # @raise [ConfigurationError] when the configured profile is unknown
       # @return [Boolean]
       def ok?(claims, cfg)
         claims = normalize_claims(claims)
-
-        profile = cfg.profile
-        profile = profile.to_sym if profile.respond_to?(:to_sym)
-        profile = :strict_single if profile.nil?
-
-        unless VALID_PROFILES.include?(profile)
-          raise Verikloak::Audience::ConfigurationError,
-                "unknown audience profile #{cfg.profile.inspect}"
-        end
+        profile = cfg.validated_profile
 
         case profile
         when :strict_single
@@ -43,23 +40,25 @@ module Verikloak
       # Validate that aud matches required exactly (order-insensitive).
       #
       # @param claims [Hash]
-      # @param required [Array<String>]
+      # @param required [Array<String,Symbol>, String, Symbol]
       # @return [Boolean]
       def strict_single?(claims, required)
         aud = normalized_audiences(claims)
+        required = normalized_required(required)
         return false if required.empty?
 
         # Must contain all required and have no unexpected extra (order-insensitive)
-        (aud.sort == required.map(&:to_s).sort)
+        aud.sort == required.sort
       end
 
       # Validate aud allowing "account" as an extra value.
       #
       # @param claims [Hash]
-      # @param required [Array<String>]
+      # @param required [Array<String,Symbol>, String, Symbol]
       # @return [Boolean]
       def allow_account?(claims, required)
         aud = normalized_audiences(claims)
+        required = normalized_required(required)
         return false if required.empty?
 
         # Permit 'account' extra
@@ -72,14 +71,15 @@ module Verikloak
       # More permissive than :strict_single; useful when multiple clients share audiences.
       #
       # @param claims [Hash]
-      # @param required [Array<String>]
+      # @param required [Array<String,Symbol>, String, Symbol]
       # @return [Boolean]
       def any_match?(claims, required)
         aud = normalized_audiences(claims)
+        required = normalized_required(required)
         return false if required.empty?
 
         # At least one of the required audiences must be present
-        aud.intersect?(required.map(&:to_s))
+        aud.intersect?(required)
       end
 
       # Permit when resource roles exist for the client; otherwise fallback to
@@ -87,7 +87,7 @@ module Verikloak
       #
       # @param claims [Hash]
       # @param client [String]
-      # @param required [Array<String>]
+      # @param required [Array<String,Symbol>, String, Symbol]
       # @return [Boolean]
       def resource_or_aud?(claims, client, required)
         roles = Array(claims.dig('resource_access', client, 'roles')).compact.reject { |r| r.to_s.empty? }
@@ -101,8 +101,11 @@ module Verikloak
       #
       # @param claims [Hash]
       # @param cfg [Verikloak::Audience::Configuration]
-      # @return [:strict_single, :allow_account, :resource_or_aud]
-      def suggest(claims, cfg)
+      # @param fallback [Symbol, nil] value returned when no profile accepts
+      #   the claims (defaults to :strict_single, preserving the 1.0 contract)
+      # @return [:strict_single, :allow_account, :any_match, :resource_or_aud, nil]
+      #   the most fitting profile, or the fallback when none accepts
+      def suggest(claims, cfg, fallback: :strict_single)
         claims = normalize_claims(claims)
 
         required = cfg.required_aud_list
@@ -111,7 +114,16 @@ module Verikloak
         return :any_match if any_match?(claims, required)
         return :resource_or_aud if resource_or_aud?(claims, cfg.resource_client.to_s, required)
 
-        :strict_single
+        fallback
+      end
+
+      # Audience values observed in the claims, normalized exactly like the
+      # profile checks normalize them (useful for consistent logging).
+      #
+      # @param claims [Object] raw claims value (Hash or #to_hash)
+      # @return [Array<String>]
+      def observed_audiences(claims)
+        normalized_audiences(normalize_claims(claims))
       end
 
       # Normalize incoming claims to a Hash to guard against unexpected
@@ -133,7 +145,6 @@ module Verikloak
         warn "[Verikloak::Audience] normalize_claims failed: #{e.class}: #{e.message}" if $DEBUG
         {}
       end
-      module_function :normalize_claims
       private_class_method :normalize_claims
 
       # Normalize audience claims into a predictable array of strings.
@@ -143,8 +154,17 @@ module Verikloak
       def normalized_audiences(claims)
         Array(claims['aud']).map(&:to_s)
       end
-      module_function :normalized_audiences
       private_class_method :normalized_audiences
+
+      # Coerce a required-audience input into an array of strings so that the
+      # public predicates accept Symbols and single values consistently.
+      #
+      # @param required [Array<String,Symbol>, String, Symbol, nil]
+      # @return [Array<String>]
+      def normalized_required(required)
+        Array(required).map(&:to_s)
+      end
+      private_class_method :normalized_required
     end
   end
 end

data/lib/verikloak/audience/configuration.rb

@@ -28,6 +28,10 @@ module Verikloak
     class Configuration
       DEFAULT_RESOURCE_CLIENT = 'rails-api'
       DEFAULT_ENV_CLAIMS_KEY = 'verikloak.user'
+      DEFAULT_PROFILE = :strict_single
+
+      # Enforcement profiles supported by {Verikloak::Audience::Checker}.
+      VALID_PROFILES = %i[strict_single allow_account any_match resource_or_aud].freeze
 
       attr_accessor :profile, :required_aud, :resource_client,
                     :suggest_in_logs, :skip_paths
@@ -37,7 +41,7 @@ module Verikloak
       #
       # @return [void]
       def initialize
-        @profile         = :strict_single
+        @profile         = DEFAULT_PROFILE
         @required_aud    = []
         @resource_client = DEFAULT_RESOURCE_CLIENT
         self.env_claims_key = DEFAULT_ENV_CLAIMS_KEY
@@ -66,6 +70,35 @@ module Verikloak
         Array(required_aud).map(&:to_s)
       end
 
+      # Coerce `profile` into a Symbol, falling back to the default when unset.
+      # Values that cannot be symbolized (e.g. an Integer) are returned as-is
+      # so {#validated_profile} can reject them with a precise error. The
+      # result is not guaranteed to be a member of {VALID_PROFILES}; use
+      # {#validated_profile} to enforce that.
+      #
+      # @return [Symbol, Object]
+      def normalized_profile
+        value = profile
+        value = value.to_sym if value.respond_to?(:to_sym)
+        value.nil? ? DEFAULT_PROFILE : value
+      end
+
+      # Coerce `profile` into a Symbol and ensure it is one of
+      # {VALID_PROFILES}. Single source of the unknown-profile check shared
+      # by {#validate!} and {Verikloak::Audience::Checker.ok?}.
+      #
+      # @raise [ConfigurationError] when the profile is unknown
+      # @return [Symbol]
+      def validated_profile
+        profile_name = normalized_profile
+        unless VALID_PROFILES.include?(profile_name)
+          raise Verikloak::Audience::ConfigurationError,
+                "unknown audience profile #{profile.inspect}"
+        end
+
+        profile_name
+      end
+
       # @param value [#to_s, nil]
       # @raise [ConfigurationError] when value is nil or blank
       # @return [void]
@@ -82,6 +115,9 @@ module Verikloak
 
       # Validate the configuration to ensure required values are present.
       #
+      # @raise [ConfigurationError] when `required_aud` is empty, `profile` is
+      #   not one of {VALID_PROFILES}, or `resource_client` conflicts with
+      #   `required_aud` under the `:resource_or_aud` profile
       # @return [Configuration] the validated configuration
       def validate!
         audiences = required_aud_list
@@ -90,9 +126,7 @@ module Verikloak
                 'required_aud must include at least one audience'
         end
 
-        profile_name = profile
-        profile_name = profile_name.to_sym if profile_name.respond_to?(:to_sym)
-        profile_name ||= :strict_single
+        profile_name = validated_profile
 
         ensure_resource_client!(audiences) if profile_name == :resource_or_aud
 

data/lib/verikloak/audience/middleware.rb

@@ -42,16 +42,15 @@ module Verikloak
         path = env['PATH_INFO'] || env['REQUEST_PATH'] || ''
         return @app.call(env) if skip?(path)
 
-        env_key = @config.env_claims_key
-        claims = env[env_key] || env[env_key&.to_sym] || {}
-        return @app.call(env) if Checker.ok?(claims, @config)
-
-        if @config.suggest_in_logs
-          suggestion = Checker.suggest(claims, @config)
-          aud_view = Array(claims['aud']).inspect
-          log_warning(env,
-                      "[verikloak-audience] insufficient_audience; suggestion profile=:#{suggestion} aud=#{aud_view}")
+        claims = read_claims(env)
+        begin
+          authorized = Checker.ok?(claims, @config)
+        rescue Verikloak::Audience::ConfigurationError => e
+          return configuration_error_response(env, e)
         end
+        return @app.call(env) if authorized
+
+        log_rejection(env, claims)
 
         Verikloak::ErrorResponse.build(
           code: 'insufficient_audience',
@@ -62,6 +61,50 @@ module Verikloak
 
       private
 
+      # Read verified claims from the Rack env under the configured key.
+      #
+      # @param env [Hash] Rack environment
+      # @return [Object] raw claims value (normalized later by {Checker})
+      def read_claims(env)
+        env_key = @config.env_claims_key
+        env[env_key] || env[env_key.to_sym] || {}
+      end
+
+      # Log a configuration failure and render it as a generic JSON error
+      # response instead of leaking a raw exception through the Rack stack.
+      # The failure detail goes to the server log only, never to the client.
+      # Boot-time validation normally prevents this path; it guards
+      # deployments where validation was skipped (e.g. unconfigured Rails
+      # boot).
+      #
+      # @param env [Hash] Rack environment
+      # @param error [Verikloak::Audience::ConfigurationError]
+      # @return [Array(Integer, Hash, #each)] Rack response triple
+      def configuration_error_response(env, error)
+        log_warning(env, "[verikloak-audience] configuration error: #{error.message}")
+
+        Verikloak::ErrorResponse.build(
+          code: error.code,
+          message: 'audience configuration error',
+          status: error.http_status
+        )
+      end
+
+      # Emit the failure log (with a profile suggestion when one fits) if
+      # `suggest_in_logs` is enabled.
+      #
+      # @param env [Hash] Rack environment
+      # @param claims [Object] raw claims value read from the env
+      # @return [void]
+      def log_rejection(env, claims)
+        return unless @config.suggest_in_logs
+
+        suggestion = Checker.suggest(claims, @config, fallback: nil)
+        detail = suggestion ? "suggestion profile=:#{suggestion}" : 'no profile matches the observed aud'
+        aud_view = Checker.observed_audiences(claims).inspect
+        log_warning(env, "[verikloak-audience] insufficient_audience; #{detail} aud=#{aud_view}")
+      end
+
       # Apply provided options to the configuration instance.
       #
       # @param opts [Hash] raw overrides provided to the middleware
@@ -82,23 +125,17 @@ module Verikloak
       # Determine whether configuration validation should run. This allows
       # Rails generators to boot without a fully-populated configuration since
       # the install task is responsible for creating it. Also skips validation
-      # when configuration is not explicitly set up.
+      # when configuration is not explicitly set up. The middleware's own
+      # (post-override) configuration decides the unconfigured case, so
+      # options passed to `use` are validated even when the global
+      # configuration is untouched.
       #
       # @return [Boolean]
       def skip_validation?
-        # Skip if Railtie indicates generator mode
-        if defined?(::Verikloak::Audience::Railtie)
-          if ::Verikloak::Audience::Railtie.respond_to?(:skip_configuration_validation?) && ::Verikloak::Audience::Railtie.skip_configuration_validation?
-            return true
-          end
-
-          # Skip if configuration is incomplete (no audiences configured)
-          if ::Verikloak::Audience::Railtie.respond_to?(:skip_unconfigured_validation?) && ::Verikloak::Audience::Railtie.skip_unconfigured_validation?
-            return true
-          end
-        end
+        return false unless defined?(::Verikloak::Audience::Railtie)
 
-        false
+        railtie = ::Verikloak::Audience::Railtie
+        railtie.respond_to?(:skip_validation?) && railtie.skip_validation?(@config)
       end
 
       # Emit a warning for failed audience checks using request-scoped loggers

data/lib/verikloak/audience/railtie.rb

@@ -69,11 +69,7 @@ module Verikloak
       end
 
       def discovery_url_configured?(value)
-        return false unless value
-        return !value.blank? if value.respond_to?(:blank?)
-        return !value.empty? if value.respond_to?(:empty?)
-
-        true
+        !value_blank?(value)
       end
 
       def middleware_not_found_error?(error)
@@ -116,11 +112,16 @@ module Verikloak
       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)
+        # Resolve the key the same way verikloak-rails' #effective_user_env_key
+        # does (>= 1.2): strip whitespace and treat blank as unset. The core
+        # middleware then falls back to its default env key, which matches our
+        # default, so both middlewares stay aligned on the same key.
+        user_key = rails_config.user_env_key.to_s.strip
+        return if user_key.empty?
 
-        current = cfg.env_claims_key
-        return unless current.nil? || current == Verikloak::Audience::Configuration::DEFAULT_ENV_CLAIMS_KEY
+        # env_claims_key is never nil (its writer rejects nil), so only the
+        # untouched default is eligible for syncing.
+        return unless cfg.env_claims_key == Verikloak::Audience::Configuration::DEFAULT_ENV_CLAIMS_KEY
 
         cfg.env_claims_key = user_key
       end
@@ -163,6 +164,7 @@ module Verikloak
 
       def value_blank?(value)
         return true if value.nil?
+        return value.blank? if value.respond_to?(:blank?)
         return true if value.respond_to?(:empty?) && value.empty?
 
         value.to_s.empty?
@@ -213,8 +215,7 @@ module Verikloak
 
       initializer 'verikloak_audience.configuration' do
         config.after_initialize do
-          next if Verikloak::Audience::Railtie.skip_configuration_validation?
-          next if Verikloak::Audience::Railtie.skip_unconfigured_validation?
+          next if Verikloak::Audience::Railtie.skip_validation?
 
           Verikloak::Audience.config.validate!
         end
@@ -256,6 +257,17 @@ module Verikloak
         self.middleware_insertion_attempted = false
       end
 
+      # Combined predicate used by the after-initialize hook and the
+      # middleware to decide whether configuration validation should run.
+      #
+      # @param config [Verikloak::Audience::Configuration] configuration whose
+      #   audiences decide the unconfigured-boot skip; the middleware passes
+      #   its own (post-override) configuration, the hook uses the global one
+      # @return [Boolean]
+      def self.skip_validation?(config = Verikloak::Audience.config)
+        skip_configuration_validation? || skip_unconfigured_validation?(config)
+      end
+
       def self.skip_configuration_validation?
         tokens = first_cli_tokens
         return false if tokens.empty?
@@ -265,12 +277,12 @@ module Verikloak
         tokens.any? { |token| verikloak_install_generator?(token) }
       end
 
-      def self.skip_unconfigured_validation?
-        audiences_unconfigured?
+      def self.skip_unconfigured_validation?(config = Verikloak::Audience.config)
+        audiences_unconfigured?(config)
       end
 
-      def self.audiences_unconfigured?
-        audiences = Verikloak::Audience.config.required_aud_list
+      def self.audiences_unconfigured?(config = Verikloak::Audience.config)
+        audiences = config.required_aud_list
 
         if audiences.empty?
           warn_unconfigured_once

data/lib/verikloak/audience/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: verikloak-audience
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - taiyaky
@@ -35,14 +35,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '1.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '1.1'
 description: |
   Rack middleware that enforces audience checks with deployable profiles,
   layering on top of Verikloak token verification.
@@ -51,7 +51,9 @@ extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
+- ERRORS.md
 - LICENSE
+- MAINTAINERS.md
 - README.md
 - lib/generators/verikloak/audience/install/install_generator.rb
 - lib/generators/verikloak/audience/install/templates/initializer.rb.erb
@@ -70,7 +72,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/1.0.0
+  documentation_uri: https://rubydoc.info/gems/verikloak-audience/1.1.0
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: