verikloak-audience 0.2.8 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 88a1386b46aebb2940ede856bdde5993bd68a05000d71f9f5784d73dd85c2fc6
-  data.tar.gz: cf84cfe50d3a6acf004ce0535b02b1644693d2c89b78e422d809b0f184e53cc3
+  metadata.gz: d97d79e3f6ccd8f2c920cc7dcb66612e9edbd577ba4be2f5948eddd16145dd9b
+  data.tar.gz: 4517ee945923ec595fa7447f33dd0e9370cc72a2a561bc04d4f910efed018595
 SHA512:
-  metadata.gz: c97758819fac422b4f81e5d22655b677f7d1bd762430e8fd68d038b1fdf9adce004da3261b6de5d2af66874a9dc2a417a1c1272933d51acd979e55416131e4dc
-  data.tar.gz: b12d1fa1f74f5b4d1bb17e461956ecabf4e094eb673b9a03e47bb174603ebcacf3d6bc3a48bab9854df8c3d94b3f6a7d252080f83248ca841354465554191740
+  metadata.gz: 83c14846297272179ccf6f4480dab677c82be3d21b32a6c374c3b40fc5be04dd0cf9c9c439457e9dd33d4b4a9fca393aca31b7104b4282479b872ad8987c8632
+  data.tar.gz: e2e125eab982f983e6447166bcd6b9d9413f15573301335f15ef53ba0bafb6d07020848ec942e9b532db69b29ab3fc6280ae9fc6f74d12ff9786a39fc64dccde

data/CHANGELOG.md

@@ -7,6 +7,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [0.3.0] - 2026-01-01
+
+### Fixed
+- **Rails 8.x+ middleware insertion**: Fixed automatic middleware insertion not working in Rails 8.x+ due to queued middleware operations not being visible via `include?` checks.
+
+### Changed
+- Railtie initializer now specifies `before: :build_middleware_stack` to ensure middleware insertion is queued before stack construction.
+- Middleware insertion now uses `app.config.middleware` instead of `app.middleware` for more reliable queuing in Rails 8.x+.
+- Extracted `middleware_not_found_error?` method to handle error detection across Rails versions (Rails 7's `MiddlewareNotFound` and Rails 8+'s `RuntimeError`).
+
+### Added
+- `@middleware_insertion_attempted` class variable to prevent duplicate middleware insertion when both railtie and generator initializer run.
+- `reset_middleware_insertion_flag!` method for testing purposes.
+- Support for alternative error message patterns (`"does not exist"`, `/middleware.*not found/i`) for future Rails version compatibility.
+- Comprehensive test coverage for:
+  - `include?` early return when middleware is already present
+  - Duplicate insertion prevention via flag
+  - Rails 7 `MiddlewareNotFound` exception handling
+  - Alternative error message patterns
+  - Unexpected exception re-raising
+
+## [0.2.9] - 2025-12-31
+
+### Added
+- **Keycloak Integration** documentation section in README:
+  - Default audience behavior explanation (Access Token: `"account"`, ID Token: Client ID)
+  - Step-by-step guide for configuring Audience Mapper in Keycloak
+  - Configuration examples using `:allow_account` profile and array audiences
+  - Troubleshooting guide with JWT decoding commands
+
+### Documentation
+- Added guidance for common Keycloak + audience validation issues
+- Clarified the relationship between Keycloak client configuration and token `aud` claims
+
 ## [0.2.8] - 2025-09-28
 
 ### Changed

data/README.md

@@ -71,6 +71,103 @@ See [`examples/rack.ru`](examples/rack.ru) for a full Rack sample. In Rails, alw
 - 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.
 
+## Keycloak Integration
+
+### Default Audience Behavior
+
+Keycloak access tokens include `aud: "account"` by default. This is often unexpected for developers who expect the client ID to appear in the audience claim.
+
+| Token Type | Default `aud` Value |
+|------------|---------------------|
+| Access Token | `"account"` |
+| ID Token | Client ID |
+
+### Common Issue
+
+```ruby
+# Configuration
+config.verikloak.audience = 'rails-api'
+
+# Actual token payload
+{
+  "aud": "account",  # NOT "rails-api"!
+  "sub": "user-123",
+  ...
+}
+
+# Result: 403 Forbidden - audience validation fails
+```
+
+### Solution: Configure Audience Mapper in Keycloak
+
+To add a custom audience to access tokens:
+
+1. Go to **Clients** → Select your client (e.g., `rails-api`)
+2. Navigate to **Client scopes** tab
+3. Click on the dedicated scope (e.g., `rails-api-dedicated`)
+4. Go to **Mappers** tab → **Add mapper** → **By configuration**
+5. Select **Audience**
+6. Configure:
+   - **Name**: `rails-api-audience`
+   - **Included Client Audience**: `rails-api`
+   - **Add to access token**: ON
+7. Save
+
+After this configuration, tokens will include:
+```json
+{
+  "aud": ["rails-api", "account"],
+  ...
+}
+```
+
+### Configuration Examples
+
+#### Option 1: Allow both custom and account audience
+
+```ruby
+# config/initializers/verikloak.rb
+Rails.application.configure do
+  config.verikloak.audience = ['rails-api', 'account']
+end
+```
+
+#### Option 2: Use :allow_account profile
+
+```ruby
+# With verikloak-audience middleware
+use Verikloak::Audience::Middleware,
+  profile: :allow_account,
+  required_aud: ['rails-api']
+```
+
+#### Option 3: Strict single audience (requires Keycloak Mapper)
+
+```ruby
+# Only works if Keycloak Audience Mapper is configured
+use Verikloak::Audience::Middleware,
+  profile: :strict_single,
+  required_aud: ['rails-api']
+```
+
+### Troubleshooting
+
+#### "Audience validation failed" errors
+
+1. Check your token's `aud` claim:
+   ```bash
+   # Decode JWT (paste your token)
+   echo "YOUR_TOKEN" | cut -d. -f2 | base64 -d | jq .aud
+   ```
+
+2. If `aud` is only `"account"`:
+   - Add an Audience Mapper in Keycloak (see above)
+   - OR use `:allow_account` profile
+
+3. If using oauth2-proxy:
+   - Ensure the correct client ID is configured
+   - Check that the token is being forwarded correctly
+
 ## Testing
 All pull requests and pushes are automatically tested with [RSpec](https://rspec.info/) and [RuboCop](https://rubocop.org/) via GitHub Actions.
 See the CI badge at the top for current build status.

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

@@ -2,6 +2,10 @@
 
 # Insert the audience middleware after the core Verikloak middleware once it
 # has been loaded into the application.
+#
+# The Railtie's insert_middleware method includes internal guards to prevent
+# duplicate insertion when both the railtie initializer and this generated
+# initializer are loaded. This is safe to call multiple times.
 if defined?(Rails) && Rails.respond_to?(:application)
   Verikloak::Audience::Railtie.insert_middleware(Rails.application)
 end

data/lib/verikloak/audience/railtie.rb

@@ -28,7 +28,9 @@ module Verikloak
       # when available.
       #
       # @param app [Rails::Application] the Rails application instance
-      initializer 'verikloak_audience.middleware' do |app|
+      initializer 'verikloak_audience.middleware',
+                  after: 'verikloak.configure',
+                  before: :build_middleware_stack do |app|
         # Insert automatically after core verikloak if present
         self.class.insert_middleware(app)
       end
@@ -42,6 +44,17 @@ module Verikloak
         end
       end
 
+      # Tracks whether middleware insertion has been attempted to prevent
+      # duplicate insertions when both railtie and generator initializer run.
+      # In Rails 8.x+, middleware operations may be queued and `include?` may
+      # not reflect pending insertions, so we use this flag as an additional
+      # safeguard.
+      @middleware_insertion_attempted = false
+
+      class << self
+        attr_accessor :middleware_insertion_attempted
+      end
+
       # Performs the insertion into the middleware stack when the core
       # Verikloak middleware is available and already present. Extracted for
       # testability without requiring a full Rails boot process.
@@ -49,22 +62,72 @@ module Verikloak
       # Insert the audience middleware after the base Verikloak middleware when
       # both are available on the stack.
       #
+      # In Rails 8.x+, middleware stack operations may be queued rather than
+      # immediately applied, so `include?` checks may return false even when
+      # the middleware will be inserted. We use `insert_after` with exception
+      # handling to gracefully handle this case.
+      #
       # @param app [#middleware] An object exposing a Rack middleware stack via `#middleware`.
       # @return [void]
       def self.insert_middleware(app)
         return unless defined?(::Verikloak::Middleware)
 
-        middleware_stack = app.middleware
-        return unless middleware_stack.respond_to?(:include?)
+        # Skip if we have already attempted insertion (handles Rails 8+ queued operations)
+        return if middleware_insertion_attempted
 
-        return if middleware_stack.include?(::Verikloak::Audience::Middleware)
+        # Use app.config.middleware for queued operations in Rails 8.x+
+        # This ensures the insert_after operation is queued and applied during
+        # build_middleware_stack, maintaining proper ordering with verikloak-rails
+        middleware_stack = app.respond_to?(:config) ? app.config.middleware : app.middleware
 
-        unless middleware_stack.include?(::Verikloak::Middleware)
-          warn_missing_core_middleware
+        # Skip if already present (avoid duplicate insertion)
+        if middleware_stack.respond_to?(:include?) &&
+           middleware_stack.include?(::Verikloak::Audience::Middleware)
           return
         end
 
-        middleware_stack.insert_after ::Verikloak::Middleware, ::Verikloak::Audience::Middleware
+        # Mark as attempted before insertion to prevent concurrent/subsequent calls
+        self.middleware_insertion_attempted = true
+
+        # Attempt to insert after the core Verikloak middleware.
+        # In Rails 8.x+, the middleware may be queued but not yet visible via include?,
+        # so we try the insertion and handle any exceptions gracefully.
+        begin
+          middleware_stack.insert_after ::Verikloak::Middleware, ::Verikloak::Audience::Middleware
+        rescue StandardError => e
+          # Handle middleware not found errors (varies by Rails version):
+          # - Rails 8+: RuntimeError with "No such middleware" message
+          # - Earlier: ActionDispatch::MiddlewareStack::MiddlewareNotFound
+          raise unless middleware_not_found_error?(e)
+
+          warn_missing_core_middleware
+        end
+      end
+
+      # Determines if the given exception indicates a middleware not found error.
+      # This handles variations across Rails versions:
+      # - Rails 8+: RuntimeError with "No such middleware" message
+      # - Rails 7 and earlier: ActionDispatch::MiddlewareStack::MiddlewareNotFound
+      #
+      # @param error [StandardError] the exception to check
+      # @return [Boolean] true if the error indicates missing middleware
+      def self.middleware_not_found_error?(error)
+        # Check exception class name (works for Rails 7's MiddlewareNotFound)
+        return true if error.class.name.to_s.include?('MiddlewareNotFound')
+
+        # Check message patterns for Rails 8+ RuntimeError
+        message = error.message.to_s
+        message.include?('No such middleware') ||
+          message.include?('does not exist') ||
+          message.match?(/middleware.*not found/i)
+      end
+
+      # Resets the insertion flag. Primarily used for testing to allow
+      # multiple insertion attempts within the same process.
+      #
+      # @return [void]
+      def self.reset_middleware_insertion_flag!
+        self.middleware_insertion_attempted = false
       end
 
       WARNING_MESSAGE = <<~MSG

data/lib/verikloak/audience/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: verikloak-audience
 version: !ruby/object:Gem::Version
-  version: 0.2.8
+  version: 0.3.0
 platform: ruby
 authors:
 - taiyaky
@@ -35,7 +35,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.2.0
+        version: 0.3.0
     - - "<"
       - !ruby/object:Gem::Version
         version: 1.0.0
@@ -45,7 +45,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.2.0
+        version: 0.3.0
     - - "<"
       - !ruby/object:Gem::Version
         version: 1.0.0
@@ -76,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.8
+  documentation_uri: https://rubydoc.info/gems/verikloak-audience/0.3.0
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: