verikloak-rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d258ce7b00c8aed380623cc36b26669d86cf80c3c06e748bc677c4f8af93a4f1
+  data.tar.gz: 874e2f3c8ed2eb372d7fd4238639f4fc16e9cdd0ee6a3de7dadc57e24bbcf629
+SHA512:
+  metadata.gz: 3e035ee3bfa25ad7c9e9eb36d1279f2ea265445c60270aa2d8a8d3fcce1757cad6003892715a1faaec22cb62148bda295522ba6c12cc3bfa7858f3d2100182eb
+  data.tar.gz: c94c073924c9ed1530978aadd7abd84855e7478350572ab70338b9e8cc0a8dd7b739865517dd488b347d87a23739580b09beee206bc8aeeda4afd40d0e5ab13e

data/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [0.1.0] - 2025-09-07
+
+### Added
+- Initial release of `verikloak-rails` (Rails integration for Verikloak).
+- Railtie auto-wiring via `config.verikloak.*` and installer generator `rails g verikloak:install`.
+- Controller concern with authentication helpers:
+  - `before_action :authenticate_user!`
+  - `current_user_claims`, `current_subject`, `current_token`, `authenticated?`, `with_required_audience!`
+- Rack middleware integration:
+  - Auto-inserts `Verikloak::Rails::MiddlewareIntegration::ForwardedAccessToken` and base `Verikloak::Middleware`.
+  - Optional BFF header promotion from `X-Forwarded-Access-Token` to `Authorization`, gated by `trust_forwarded_access_token` and `trusted_proxy_subnets` (never overwrites existing `Authorization`).
+  - Token sourcing priority configurable via `token_header_priority`.
+- Consistent JSON error responses and statuses:
+  - 401/403/503 standardized; `WWW-Authenticate` header on 401.
+  - Optional global 500 JSON via `config.verikloak.render_500_json`.
+- Optional Pundit integration: rescue `Pundit::NotAuthorizedError` to 403 JSON (`config.verikloak.rescue_pundit`).
+- Request logging tags (`:request_id`, `:sub`) via `config.verikloak.logger_tags`.
+- Configurable initializer: `discovery_url`, `audience`, `issuer`, `leeway`, `skip_paths`, `trust_forwarded_access_token`, `trusted_proxy_subnets`, `auto_include_controller`, `error_renderer`, and more.
+- Compatibility: Ruby >= 3.1, Rails 6.1–8.x; depends on `verikloak` >= 0.1.2, < 0.2.

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2025 taiyaky
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,342 @@
+# verikloak-rails
+
+[![CI](https://github.com/taiyaky/verikloak-rails/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/taiyaky/verikloak-rails/actions/workflows/ci.yml)
+[![Gem Version](https://img.shields.io/gem/v/verikloak-rails)](https://rubygems.org/gems/verikloak-rails)
+![Ruby Version](https://img.shields.io/badge/ruby-%3E%3D%203.1-blue)
+[![Downloads](https://img.shields.io/gem/dt/verikloak-rails)](https://rubygems.org/gems/verikloak-rails)
+
+Rails integration for Verikloak.
+
+## Purpose
+Provide drop-in, token-based authentication for Rails APIs via Verikloak (OIDC discovery and JWKS verification). It installs middleware and a controller concern to authenticate Bearer tokens, exposes helpers for claims and subject, and returns standardized JSON error responses (401/403/503) with `WWW-Authenticate` on 401. Defaults prioritize security while keeping configuration minimal.
+
+## Features
+- Auto-wiring via Railtie (`config.verikloak.*`)
+- Controller concern with `before_action :authenticate_user!`
+- Helpers: `current_user_claims`, `current_subject`, `current_token`, `authenticated?`
+- Exceptions → standardized JSON (401/403/503) with `WWW-Authenticate` on 401
+- Log tagging (`request_id`, `sub`)
+- Installer generator: `rails g verikloak:install`
+
+## Compatibility
+- Ruby: >= 3.1
+- Rails: 6.1 – 8.x
+- verikloak: >= 0.1.2, < 0.2
+
+## Quick Start
+```bash
+bundle add verikloak verikloak-rails
+rails g verikloak:install
+```
+
+Then configure `config/initializers/verikloak.rb`.
+
+## Controller Helpers
+### Available Methods
+| Method | Purpose | Returns | On failure |
+| --- | --- | --- | --- |
+| `authenticate_user!` | Use as a `before_action` to require a valid Bearer token | `void` | Renders standardized 401 JSON and sets `WWW-Authenticate: Bearer` when token is absent/invalid |
+| `authenticated?` | Whether verified user claims are present | `Boolean` | — |
+| `current_user_claims` | Verified JWT claims (string keys) | `Hash` or `nil` | — |
+| `current_subject` | Convenience accessor for `sub` claim | `String` or `nil` | — |
+| `current_token` | Raw Bearer token from the request | `String` or `nil` | — |
+| `with_required_audience!(*aud)` | Enforce that `aud` includes all required entries | `void` | Renders standardized 403 JSON when requirements are not met |
+
+### Data Sources
+| Value | Rack env keys | Fallback (RequestStore) | Notes |
+| --- | --- | --- | --- |
+| `current_user_claims` | `verikloak.user` | `:verikloak_user` | Uses RequestStore only when available |
+| `current_token` | `verikloak.token` | `:verikloak_token` | Uses RequestStore only when available |
+
+### Example Controller
+
+```ruby
+class ApiController < ApplicationController
+  # Auto-included by default; if disabled, add explicitly:
+  # include Verikloak::Rails::Controller
+
+  def me
+    render json: { sub: current_subject, claims: current_user_claims }
+  end
+
+  def must_have_aud
+    with_required_audience!('my-api')
+    render json: { ok: true }
+  end
+end
+```
+
+### Manual Include (disable auto-include)
+If you disable auto-inclusion of the controller concern, add it manually:
+
+```ruby
+# config/initializers/verikloak.rb
+Rails.application.configure do
+  config.verikloak.auto_include_controller = false
+end
+
+# app/controllers/application_controller.rb
+class ApplicationController < ActionController::Base
+  include Verikloak::Rails::Controller
+end
+```
+
+## Middleware
+### Inserted Middlewares
+| Component | Inserted after | Purpose |
+| --- | --- | --- |
+| `Verikloak::Rails::MiddlewareIntegration::ForwardedAccessToken` | `Rails::Rack::Logger` | Promote trusted `X-Forwarded-Access-Token` to `Authorization` and, when `Authorization` is empty, set it from a prioritized list of headers |
+| `Verikloak::Middleware` | `ForwardedAccessToken` | Validate Bearer JWT (OIDC discovery + JWKS), set `verikloak.user`/`verikloak.token`, and honor `skip_paths` |
+
+### Header Sources and Trust
+- Never overwrites an existing `Authorization` header.
+- Considers `X-Forwarded-Access-Token` only when both are true: `config.verikloak.trust_forwarded_access_token` is enabled and the direct peer IP is within `config.verikloak.trusted_proxy_subnets`.
+- `config.verikloak.token_header_priority` decides which env header can seed `Authorization` when it is empty. Note: `HTTP_AUTHORIZATION` is ignored as a source (it is the target header); include other headers if you need additional sources. Forwarded headers are skipped if not trusted.
+- Direct peer detection prefers `REMOTE_ADDR`, falling back to the nearest proxy in `X-Forwarded-For` when needed.
+
+### BFF Header Promotion
+When fronted by a BFF (e.g., oauth2-proxy) that injects `X-Forwarded-Access-Token`, you can promote that header to `Authorization` from trusted sources only.
+
+Enable promotion and restrict to trusted subnets:
+
+```ruby
+Rails.application.configure do
+  config.verikloak.trust_forwarded_access_token = true
+  config.verikloak.trusted_proxy_subnets = [
+    '10.0.0.0/8',
+    '192.168.0.0/16'
+  ]
+end
+```
+
+### Reordering or Disabling (advanced)
+You can adjust the stack in an initializer after the gem loads, for example:
+
+```ruby
+Rails.application.configure do
+  # Remove header-promotion middleware if you never use BFF tokens
+  config.middleware.delete Verikloak::Rails::MiddlewareIntegration::ForwardedAccessToken
+
+  # Or move the middleware earlier/later if your stack requires it
+  # config.middleware.insert_before SomeOtherMiddleware, Verikloak::Rails::MiddlewareIntegration::ForwardedAccessToken,
+  #   trust_forwarded: Verikloak::Rails.config.trust_forwarded_access_token,
+  #   trusted_proxies: Verikloak::Rails.config.trusted_proxy_subnets,
+  #   header_priority: Verikloak::Rails.config.token_header_priority
+end
+```
+
+## Configuration (initializer)
+### Keys
+Keys under `config.verikloak`:
+
+| Key | Type | Description | Default |
+| --- | --- | --- | --- |
+| `discovery_url` | String | OIDC discovery URL | `nil` |
+| `audience` | String or Array | Expected `aud` | `nil` |
+| `issuer` | String | Expected `iss` | `nil` |
+| `leeway` | Integer | Clock skew allowance (seconds) | `60` |
+| `skip_paths` | Array<String> | Paths to skip verification | `['/up','/health','/rails/health']` |
+| `trust_forwarded_access_token` | Boolean | Trust `X-Forwarded-Access-Token` from trusted proxies | `false` |
+| `trusted_proxy_subnets` | Array<String or IPAddr> | Subnets allowed to be treated as trusted | `[]` (treat all as trusted; set explicit ranges in production) |
+| `logger_tags` | Array<Symbol> | Tags to add to Rails logs. Supports `:request_id`, `:sub` | `[:request_id, :sub]` |
+| `error_renderer` | Object responding to `render(controller, error)` | Override error rendering | built-in JSON renderer |
+| `auto_include_controller` | Boolean | Auto-include controller concern | `true` |
+| `render_500_json` | Boolean | Rescue `StandardError` and render JSON 500 | `false` |
+| `token_header_priority` | Array<String> | Env header priority to source bearer token | `['HTTP_X_FORWARDED_ACCESS_TOKEN','HTTP_AUTHORIZATION']` |
+| `rescue_pundit` | Boolean | Rescue `Pundit::NotAuthorizedError` to 403 JSON when Pundit is present | `true` |
+
+Environment variable examples are in the generated initializer.
+
+### Minimum Setup
+- Required: set `discovery_url` to your provider’s OIDC discovery document URL.
+- Recommended: set `audience` (expected `aud`), and `issuer` when known.
+- Optional: enable BFF header promotion only with explicit `trusted_proxy_subnets`.
+
+```ruby
+# config/initializers/verikloak.rb
+Rails.application.configure do
+  config.verikloak.discovery_url = ENV['KEYCLOAK_DISCOVERY_URL']
+  config.verikloak.audience      = ENV.fetch('VERIKLOAK_AUDIENCE', 'rails-api')
+  # Optional but recommended when you know it
+  # config.verikloak.issuer        = 'https://idp.example.com/realms/myrealm'
+
+  # Leave header promotion off unless you run a trusted BFF/proxy
+  # config.verikloak.trust_forwarded_access_token = false
+  # config.verikloak.trusted_proxy_subnets = ['10.0.0.0/8']
+end
+```
+
+Notes:
+- For array-like values (`audience`, `skip_paths`, `trusted_proxy_subnets`, `token_header_priority`), prefer defining Ruby arrays in the initializer. If passing via ENV, use comma-separated strings and parse in the initializer.
+- Header sourcing/trust behavior is described in “Middleware → Header Sources and Trust”.
+
+### Full Example (selected options)
+```ruby
+# config/initializers/verikloak.rb
+Rails.application.configure do
+  config.verikloak.discovery_url = ENV['KEYCLOAK_DISCOVERY_URL']
+  config.verikloak.audience      = ENV.fetch('VERIKLOAK_AUDIENCE', 'rails-api')
+  config.verikloak.leeway        = Integer(ENV.fetch('VERIKLOAK_LEEWAY', '60'))
+  config.verikloak.skip_paths    = %w[/up /health /rails/health]
+
+  # Enable BFF header promotion only from trusted subnets
+  config.verikloak.trust_forwarded_access_token = ENV.fetch('VERIKLOAK_TRUST_FWD_TOKEN', 'false') == 'true'
+  config.verikloak.trusted_proxy_subnets = [
+    '10.0.0.0/8', # internal LB
+    # '192.168.0.0/16'
+  ]
+
+  config.verikloak.logger_tags = %i[request_id sub]
+  config.verikloak.render_500_json = ENV.fetch('VERIKLOAK_RENDER_500', 'false') == 'true'
+  config.verikloak.token_header_priority = %w[HTTP_X_FORWARDED_ACCESS_TOKEN HTTP_AUTHORIZATION]
+
+  # Optional Pundit rescue (403 JSON)
+  config.verikloak.rescue_pundit = ENV.fetch('VERIKLOAK_RESCUE_PUNDIT', 'true') == 'true'
+end
+```
+
+### ENV Mapping
+
+| Key | ENV var |
+| --- | --- |
+| `discovery_url` | `KEYCLOAK_DISCOVERY_URL` |
+| `audience` | `VERIKLOAK_AUDIENCE` |
+| `issuer` | `VERIKLOAK_ISSUER` |
+| `leeway` | `VERIKLOAK_LEEWAY` |
+| `trust_forwarded_access_token` | `VERIKLOAK_TRUST_FWD_TOKEN` |
+| `render_500_json` | `VERIKLOAK_RENDER_500` |
+| `rescue_pundit` | `VERIKLOAK_RESCUE_PUNDIT` |
+
+### Notes
+- Default for `trust_forwarded_access_token` is secure (`false`). Set `trusted_proxy_subnets` before enabling.
+- The middleware never overwrites an existing `Authorization` header.
+- If `trusted_proxy_subnets` is empty, all peers are treated as trusted. In production, set explicit subnets or keep `trust_forwarded_access_token` disabled.
+
+## Errors
+This gem standardizes JSON error responses and HTTP statuses. See [ERRORS.md](ERRORS.md) for details and examples.
+
+### Statuses
+| Status | Typical code(s) | When | Headers | Body (example) |
+| --- | --- | --- | --- | --- |
+| 401 Unauthorized | `invalid_token`, `unauthorized` | Missing/invalid Bearer token; failed signature/expiry/issuer/audience checks | `WWW-Authenticate: Bearer` with optional `error` and `error_description` | `{ "error": "invalid_token", "message": "token expired" }` |
+| 403 Forbidden | `forbidden` | Audience check failure via `with_required_audience!`; optionally `Pundit::NotAuthorizedError` when rescue is enabled | — | `{ "error": "forbidden", "message": "Required audience not satisfied" }` |
+| 503 Service Unavailable | `jwks_fetch_failed`, `jwks_parse_failed`, `discovery_metadata_fetch_failed`, `discovery_metadata_invalid` | Upstream metadata/JWKS issues | — | `{ "error": "jwks_fetch_failed", "message": "..." }` |
+
+### Customize
+Customize rendering by assigning `config.verikloak.error_renderer`.
+
+Example: return a compact JSON shape while preserving `WWW-Authenticate` for 401.
+
+```ruby
+class CompactErrorRenderer
+  def render(controller, error)
+    code = error.respond_to?(:code) ? error.code : 'unauthorized'
+    message = error.message.to_s
+
+    status = case code
+             when 'forbidden' then 403
+             when 'jwks_fetch_failed', 'jwks_parse_failed', 'discovery_metadata_fetch_failed', 'discovery_metadata_invalid' then 503
+             else 401
+             end
+
+    if status == 401
+      hdr = +'Bearer'
+      hdr << %( error="#{sanitize_quoted(code)}") if code
+      hdr << %( error_description="#{sanitize_quoted(message)}") if message && !message.empty?
+      controller.response.set_header('WWW-Authenticate', hdr)
+    end
+
+    controller.render json: { code: code, msg: message }, status: status
+  end
+end
+
+Rails.application.configure do
+  config.verikloak.error_renderer = CompactErrorRenderer.new
+end
+```
+
+Note: Always sanitize values placed into `WWW-Authenticate` header parameters to avoid header injection. For example:
+
+```ruby
+class CompactErrorRenderer
+  private
+  def sanitize_quoted(val)
+    # Escape quotes/backslashes and strip CR/LF
+    val.to_s.gsub(/(["\\])/) { |m| "\\#{m}" }.gsub(/[\r\n]/, ' ')
+  end
+end
+```
+
+## Optional Pundit Rescue
+If the `pundit` gem is present, `Pundit::NotAuthorizedError` is rescued to a standardized 403 JSON. This is a lightweight convenience only; deeper Pundit integration (policies, helpers) is out of scope and can live in a separate plugin.
+
+### Toggle
+Toggle with `config.verikloak.rescue_pundit` (default: true). Environment example:
+
+```ruby
+# config/initializers/verikloak.rb
+Rails.application.configure do
+  # Disable the built-in rescue if you handle Pundit errors yourself
+  config.verikloak.rescue_pundit = ENV.fetch('VERIKLOAK_RESCUE_PUNDIT', 'true') == 'true'
+end
+```
+
+### Behavior Example
+```ruby
+# When Pundit raises:
+raise Pundit::NotAuthorizedError, 'forbidden'
+# The concern rescues and renders:
+# { error: 'forbidden', message: 'forbidden' } with status 403
+```
+
+## Rails 8.0/8.1 Timezone Note
+Rails 8.0 shows a deprecation for the upcoming 8.1 change where `to_time` preserves the receiver timezone. This gem does not call `to_time`, but your app may. To opt in and silence the deprecation, set:
+```ruby
+# config/application.rb
+module YourApp
+  class Application < Rails::Application
+    config.active_support.to_time_preserves_timezone = :zone
+  end
+end
+```
+
+## Development (for contributors)
+Clone and install dependencies:
+
+```bash
+git clone https://github.com/taiyaky/verikloak-rails.git
+cd verikloak-rails
+bundle install
+```
+See **Testing** below to run specs and RuboCop. For releasing, see **Publishing**.
+
+## 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.
+
+To run the test suite locally:
+
+```bash
+docker compose run --rm dev rspec
+docker compose run --rm dev rubocop -a
+```
+
+## 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).
+
+## License
+This project is licensed under the [MIT License](LICENSE).
+
+## Publishing (for maintainers)
+Gem release instructions are documented separately in [MAINTAINERS.md](MAINTAINERS.md).
+
+## Changelog
+See [CHANGELOG.md](CHANGELOG.md) for release history.
+
+## References
+- verikloak-rails (this gem): https://rubygems.org/gems/verikloak-rails
+- Verikloak (base gem): https://github.com/taiyaky/verikloak
+- Verikloak on RubyGems: https://rubygems.org/gems/verikloak

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module Verikloak
+  module Generators
+    # Rails generator that creates `config/initializers/verikloak.rb` and prints
+    # follow-up instructions for configuring verikloak-rails.
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Creates an initializer for verikloak-rails and documents basic usage.'
+
+      # Create the initializer file under config/initializers.
+      # @return [void]
+      # @example
+      #   rails g verikloak:install
+      def create_initializer
+        template 'initializer.rb.erb', 'config/initializers/verikloak.rb'
+      end
+
+      # Print next steps for configuring the gem.
+      # @return [void]
+      def say_next_steps
+        say <<~MSG
+          ✅ verikloak: initializer created.
+
+          Next steps:
+          1) Ensure the base gem is installed:   gem 'verikloak', '>= 0.1.2', '< 0.2'
+          2) Set discovery_url / audience in config/initializers/verikloak.rb
+          3) (Optional) If you disable auto-include, add this line to ApplicationController:
+               include Verikloak::Rails::Controller
+        MSG
+      end
+    end
+  end
+end

data/lib/verikloak/rails/configuration.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require 'ipaddr'
+
+module Verikloak
+  module Rails
+    # Configuration for verikloak-rails.
+    #
+    # Controls how the Rack middleware is initialized (discovery, audience,
+    # issuer, leeway, skip paths) and Rails-specific behavior such as
+    # controller inclusion, logging tags, and error rendering.
+    #
+    # @!attribute [rw] discovery_url
+    #   OIDC discovery document URL.
+    #   @return [String, nil]
+    # @!attribute [rw] audience
+    #   Expected audience (`aud`) claim. Accepts String or Array.
+    #   @return [String, Array<String>, nil]
+    # @!attribute [rw] issuer
+    #   Expected issuer (`iss`) claim.
+    #   @return [String, nil]
+    # @!attribute [rw] leeway
+    #   Clock skew allowance in seconds.
+    #   @return [Integer]
+    # @!attribute [rw] skip_paths
+    #   Paths to skip verification.
+    #   @return [Array<String>]
+    # @!attribute [rw] trust_forwarded_access_token
+    #   Whether to trust `X-Forwarded-Access-Token` from trusted proxies.
+    #   @return [Boolean]
+    # @!attribute [r] trusted_proxy_subnets
+    #   Trusted proxy subnets.
+    #   @return [Array<IPAddr>]
+    # @!attribute [rw] logger_tags
+    #   Log tags to include (supports :request_id, :sub).
+    #   @return [Array<Symbol>]
+    # @!attribute [rw] error_renderer
+    #   Custom error renderer object responding to `render(controller, error)`.
+    #   @return [Object]
+    # @!attribute [rw] auto_include_controller
+    #   Auto-include the controller concern into ActionController::Base.
+    #   @return [Boolean]
+    # @!attribute [rw] render_500_json
+    #   Rescue StandardError and render a JSON 500 response.
+    #   @return [Boolean]
+    # @!attribute [rw] token_header_priority
+    #   Env header keys in priority order for sourcing bearer token.
+    #   @return [Array<String>]
+    class Configuration
+      attr_accessor :discovery_url, :audience, :issuer, :leeway, :skip_paths, :trust_forwarded_access_token,
+                    :logger_tags, :error_renderer, :auto_include_controller, :render_500_json, :token_header_priority,
+                    :rescue_pundit
+      attr_reader   :trusted_proxy_subnets
+
+      def initialize
+        @discovery_url = nil
+        @audience      = nil
+        @issuer        = nil
+        @leeway        = 60
+        @skip_paths    = ['/up', '/health', '/rails/health']
+        @trust_forwarded_access_token = false
+        @trusted_proxy_subnets = []
+        @logger_tags    = %i[request_id sub]
+        @error_renderer = Verikloak::Rails::ErrorRenderer.new
+        @auto_include_controller = true
+        @render_500_json = false
+        @token_header_priority = %w[HTTP_X_FORWARDED_ACCESS_TOKEN HTTP_AUTHORIZATION]
+        @rescue_pundit = true
+      end
+
+      # Assign trusted proxy subnets.
+      # @param list [Array<String, IPAddr>, String, IPAddr] one or more CIDRs or IPAddr instances
+      def trusted_proxy_subnets=(list)
+        @trusted_proxy_subnets = Array(list).map { |e| e.is_a?(IPAddr) ? e : IPAddr.new(e) }
+      end
+
+      # Options forwarded to the base Verikloak Rack middleware.
+      # @return [Hash]
+      # @example
+      #   Verikloak::Rails.config.middleware_options
+      #   #=> { discovery_url: 'https://example/.well-known/openid-configuration', leeway: 60, ... }
+      def middleware_options
+        {
+          discovery_url: discovery_url,
+          audience: audience,
+          issuer: issuer,
+          leeway: leeway,
+          skip_paths: skip_paths
+        }.compact
+      end
+    end
+  end
+end

data/lib/verikloak/rails/controller.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+
+module Verikloak
+  module Rails
+    # Controller concern providing Verikloak helpers and JSON error handling.
+    #
+    # Includes `before_action :authenticate_user!`, helpers such as
+    # `current_user_claims`, and consistent 401/403 responses. Optionally wraps
+    # requests with tagged logging and a 500 JSON renderer.
+    module Controller
+      extend ActiveSupport::Concern
+
+      included do
+        before_action :authenticate_user!
+        # Register generic error handler first so specific handlers take precedence.
+        if Verikloak::Rails.config.render_500_json
+          rescue_from StandardError do |_e|
+            render json: { error: 'internal_server_error', message: 'An unexpected error occurred' },
+                   status: :internal_server_error
+          end
+        end
+        if defined?(::Pundit::NotAuthorizedError) && Verikloak::Rails.config.rescue_pundit
+          rescue_from ::Pundit::NotAuthorizedError do |e|
+            render json: { error: 'forbidden', message: e.message }, status: :forbidden
+          end
+        end
+        rescue_from ::Verikloak::Error do |e|
+          Verikloak::Rails.config.error_renderer.render(self, e)
+        end
+        around_action :_verikloak_tag_logs
+      end
+
+      # Ensures a user is authenticated, otherwise renders a JSON 401 response.
+      #
+      # @return [void]
+      # @example In a controller
+      #   class ApiController < ApplicationController
+      #     before_action :authenticate_user!
+      #   end
+      def authenticate_user!
+        return if authenticated?
+
+        e = begin
+          ::Verikloak::Error.new('unauthorized')
+        rescue StandardError
+          StandardError.new('Unauthorized')
+        end
+        Verikloak::Rails.config.error_renderer.render(self, e)
+      end
+
+      # Whether the request has verified user claims.
+      # @return [Boolean]
+      def authenticated? = current_user_claims.present?
+
+      # The verified JWT claims for the current user.
+      # Prefer Rack env; fall back to RequestStore when available.
+      # @return [Hash, nil]
+      def current_user_claims
+        env_claims = request.env['verikloak.user']
+        return env_claims unless env_claims.nil?
+        return ::RequestStore.store[:verikloak_user] if defined?(::RequestStore) && ::RequestStore.respond_to?(:store)
+
+        nil
+      end
+
+      # The raw bearer token used for the current request.
+      # Prefer Rack env; fall back to RequestStore when available.
+      # @return [String, nil]
+      def current_token
+        env_token = request.env['verikloak.token']
+        return env_token unless env_token.nil?
+        return ::RequestStore.store[:verikloak_token] if defined?(::RequestStore) && ::RequestStore.respond_to?(:store)
+
+        nil
+      end
+
+      # The `sub` (subject) claim from the current user claims.
+      # @return [String, nil]
+      def current_subject = current_user_claims && current_user_claims['sub']
+
+      # Enforces that the current user has all required audiences.
+      #
+      # @param required [Array<String>] one or more audiences to require
+      # @return [void]
+      # @example
+      #   with_required_audience!('my-api', 'payments')
+      def with_required_audience!(*required)
+        aud = Array(current_user_claims&.dig('aud'))
+        return if required.flatten.all? { |r| aud.include?(r) }
+
+        render json: { error: 'forbidden', message: 'Required audience not satisfied' }, status: :forbidden
+      end
+
+      private
+
+      # Wraps the request in tagged logs for request ID and subject when available.
+      # @yieldreturn [Object] result of the block
+      # @return [Object]
+      def _verikloak_tag_logs(&)
+        tags = []
+        if Verikloak::Rails.config.logger_tags.include?(:request_id)
+          rid = request.request_id || request.headers['X-Request-Id']
+          tags << "req:#{rid}" if rid
+        end
+        tags << "sub:#{current_subject}" if Verikloak::Rails.config.logger_tags.include?(:sub) && current_subject
+        if ::Rails.logger.respond_to?(:tagged) && tags.any?
+          ::Rails.logger.tagged(*tags, &)
+        else
+          yield
+        end
+      end
+    end
+  end
+end

data/lib/verikloak/rails/error_renderer.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Verikloak
+  module Rails
+    # Renders JSON errors for authentication/authorization failures.
+    #
+    # When status is 401, adds a `WWW-Authenticate: Bearer` header including
+    # `error` and `error_description` fields when available.
+    class ErrorRenderer
+      DEFAULT_STATUS_MAP = {
+        'invalid_token' => 401,
+        'unauthorized' => 401,
+        'forbidden' => 403,
+        'jwks_fetch_failed' => 503,
+        'jwks_parse_failed' => 503,
+        'discovery_metadata_fetch_failed' => 503,
+        'discovery_metadata_invalid' => 503
+      }.freeze
+
+      # Render an error as JSON, adding `WWW-Authenticate` when appropriate.
+      #
+      # @param controller [#response,#render] a Rails controller instance
+      # @param error [Exception] the error to render
+      # @return [void]
+      # @example
+      #   begin
+      #     do_auth!
+      #   rescue Verikloak::Error => e
+      #     Verikloak::Rails.config.error_renderer.render(self, e)
+      #   end
+      def render(controller, error)
+        code, message = extract_code_message(error)
+        status = status_for(error, code)
+        headers = {}
+        if status == 401
+          hdr = +'Bearer'
+          hdr << %( error="#{sanitize_quoted(code)}") if code
+          hdr << %( error_description="#{sanitize_quoted(message)}") if message
+          headers['WWW-Authenticate'] = hdr
+        end
+        headers.each { |k, v| controller.response.set_header(k, v) }
+        controller.render json: { error: code || 'unauthorized', message: message }, status: status
+      end
+
+      private
+
+      # Extract error code and message from a given exception.
+      # @param error [Exception]
+      # @return [Array<(String, String)>]
+      def extract_code_message(error)
+        code = if error.respond_to?(:code) && error.code
+                 error.code
+               else
+                 error.class.name.split('::').last.gsub(/Error$/, '').downcase
+               end
+        [code, error.message.to_s]
+      end
+
+      # Map an error to an HTTP status code.
+      # @param error [Exception]
+      # @param code [String, nil]
+      # @return [Integer]
+      def status_for(error, code)
+        if error.is_a?(::Verikloak::Error)
+          DEFAULT_STATUS_MAP[code] || 401
+        else
+          401
+        end
+      end
+
+      # Sanitize a value for inclusion inside a quoted HTTP header parameter.
+      # Escapes quotes and backslashes, and strips CR/LF to prevent header injection.
+      # Why block replacement? String replacements like '\\1' are parsed as
+      # backreferences/escapes in Ruby, making precise escaping error‑prone.
+      # The block receives the literal match and we return it prefixed with a
+      # backslash, guaranteeing predictable escaping for both " and \\.
+      # @param val [String]
+      # @return [String]
+      def sanitize_quoted(val)
+        val.to_s.gsub(/(["\\])/) { |m| "\\#{m}" }.gsub(/[\r\n]/, ' ')
+      end
+    end
+  end
+end

data/lib/verikloak/rails/middleware_integration.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require 'ipaddr'
+
+module Verikloak
+  module Rails
+    # Internal namespace for Rack middleware glue.
+    module MiddlewareIntegration
+      # Promotes forwarded access tokens to Authorization when trusted.
+      #
+      # - Optionally trusts `X-Forwarded-Access-Token` from configured subnets
+      # - Never overwrites an existing `Authorization` header
+      # - Can derive the token from a prioritized list of headers
+      class ForwardedAccessToken
+        # Initialize the middleware.
+        #
+        # @param app [#call] next Rack app
+        # @param trust_forwarded [Boolean] whether to trust forwarded access tokens
+        # @param trusted_proxies [Array<IPAddr>, Array<String>] subnets considered trusted
+        # @param header_priority [Array<String>] env header keys to search, in order
+        def initialize(app, trust_forwarded:, trusted_proxies:,
+                       header_priority: %w[HTTP_X_FORWARDED_ACCESS_TOKEN HTTP_AUTHORIZATION])
+          @app = app
+          @trust_forwarded = trust_forwarded
+          @trusted_proxies = Array(trusted_proxies)
+          @header_priority = header_priority
+        end
+
+        # Rack entry point: possibly promote a token and pass to the next app.
+        #
+        # @param env [Hash] Rack environment
+        # @return [Array(Integer, Hash, #each)] Rack response triple from downstream app
+        # @example Promote forwarded token
+        #   env = { 'REMOTE_ADDR' => '10.0.0.1', 'HTTP_X_FORWARDED_ACCESS_TOKEN' => 'abc' }
+        #   status, headers, body = middleware.call(env)
+        def call(env)
+          promote_forwarded_if_trusted(env)
+          first = resolve_first_token_header(env)
+          set_authorization_from(env, first) if first
+          @app.call(env)
+        end
+
+        private
+
+        # Promote X-Forwarded-Access-Token to Authorization when trusted.
+        # @param env [Hash]
+        # @return [void]
+        def promote_forwarded_if_trusted(env)
+          return unless @trust_forwarded && from_trusted_proxy?(env)
+
+          forwarded = env['HTTP_X_FORWARDED_ACCESS_TOKEN']
+          return if forwarded.to_s.empty?
+          return unless env['HTTP_AUTHORIZATION'].to_s.empty?
+
+          env['HTTP_AUTHORIZATION'] = ensure_bearer(forwarded)
+        end
+
+        # Resolve the first header key from which to source a bearer token.
+        # Respects trust policy for forwarded tokens and never returns
+        # 'HTTP_AUTHORIZATION'.
+        #
+        # @param env [Hash]
+        # @return [String, nil]
+        def resolve_first_token_header(env)
+          candidates = @header_priority.dup
+          candidates -= ['HTTP_X_FORWARDED_ACCESS_TOKEN'] unless @trust_forwarded && from_trusted_proxy?(env)
+          candidates.find { |k| (val = env[k]) && !val.to_s.empty? && k != 'HTTP_AUTHORIZATION' }
+        end
+
+        # Set Authorization header from the given env header key.
+        # @param env [Hash]
+        # @param header_key [String]
+        # @return [void]
+        def set_authorization_from(env, header_key)
+          token = env[header_key]
+          env['HTTP_AUTHORIZATION'] ||= ensure_bearer(token)
+        end
+
+        # Ensure the token string is prefixed with 'Bearer '.
+        # @param token [String]
+        # @return [String]
+        def ensure_bearer(token)
+          token.start_with?('Bearer') ? token : "Bearer #{token}"
+        end
+
+        # Whether the request originates from a trusted proxy subnet.
+        # @param env [Hash]
+        # @return [Boolean]
+        def from_trusted_proxy?(env)
+          return true if @trusted_proxies.empty?
+
+          # Prefer REMOTE_ADDR (direct peer). Fallback to the nearest proxy from X-Forwarded-For if present.
+          ip = (env['REMOTE_ADDR'] || '').to_s.strip
+          ip = env['HTTP_X_FORWARDED_FOR'].to_s.split(',').last.to_s.strip if ip.empty? && env['HTTP_X_FORWARDED_FOR']
+          return false if ip.empty?
+
+          begin
+            req_ip = IPAddr.new(ip)
+            @trusted_proxies.any? { |subnet| subnet.include?(req_ip) }
+          rescue IPAddr::InvalidAddressError
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/verikloak/rails/railtie.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'rails/railtie'
+require 'verikloak/middleware'
+
+module Verikloak
+  module Rails
+    # Hooks verikloak-rails into a Rails application lifecycle.
+    #
+    # - Applies configuration from `config.verikloak`
+    # - Inserts middleware (`ForwardedAccessToken`, then `Verikloak::Middleware`)
+    # - Auto-includes controller concern when enabled
+    class Railtie < ::Rails::Railtie
+      config.verikloak = ActiveSupport::OrderedOptions.new
+
+      # Apply configuration and insert middleware.
+      # @return [void]
+      initializer 'verikloak.configure' do |app|
+        Verikloak::Rails.configure do |c|
+          rails_cfg = app.config.verikloak
+          %i[discovery_url audience issuer leeway skip_paths trust_forwarded_access_token
+             trusted_proxy_subnets logger_tags error_renderer auto_include_controller
+             render_500_json token_header_priority rescue_pundit].each do |key|
+            c.send("#{key}=", rails_cfg[key]) if rails_cfg.key?(key)
+          end
+        end
+        app.middleware.insert_after ::Rails::Rack::Logger,
+                                    Verikloak::Rails::MiddlewareIntegration::ForwardedAccessToken,
+                                    trust_forwarded: Verikloak::Rails.config.trust_forwarded_access_token,
+                                    trusted_proxies: Verikloak::Rails.config.trusted_proxy_subnets,
+                                    header_priority: Verikloak::Rails.config.token_header_priority
+        app.middleware.insert_after Verikloak::Rails::MiddlewareIntegration::ForwardedAccessToken,
+                                    ::Verikloak::Middleware,
+                                    **Verikloak::Rails.config.middleware_options
+      end
+
+      # Optionally include the controller concern when ActionController loads.
+      # @return [void]
+      initializer 'verikloak.controller' do |_app|
+        ActiveSupport.on_load(:action_controller_base) do
+          include Verikloak::Rails::Controller if Verikloak::Rails.config.auto_include_controller
+        end
+      end
+    end
+  end
+end

data/lib/verikloak/rails/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Verikloak
+  module Rails
+    VERSION = '0.1.0'
+  end
+end

data/lib/verikloak/rails.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'verikloak/rails/version'
+require 'verikloak/rails/configuration'
+require 'verikloak/rails/error_renderer'
+require 'verikloak/rails/controller'
+require 'verikloak/rails/middleware_integration'
+require 'verikloak/rails/railtie'
+
+module Verikloak
+  # Rails integration surface for Verikloak.
+  #
+  # Exposes configuration and Railtie hooks to wire middleware and controller
+  # helpers into a Rails application.
+  module Rails
+    class << self
+      # Global configuration object for verikloak-rails.
+      #
+      # @return [Verikloak::Rails::Configuration]
+      # @example Read current leeway
+      #   Verikloak::Rails.config.leeway #=> 60
+      def config
+        @config ||= Configuration.new
+      end
+
+      # Configure verikloak-rails.
+      #
+      # @yieldparam [Verikloak::Rails::Configuration] config
+      # @return [void]
+      # @example
+      #   Verikloak::Rails.configure do |c|
+      #     c.discovery_url = ENV['KEYCLOAK_DISCOVERY_URL']
+      #     c.audience      = 'rails-api'
+      #     c.leeway        = 30
+      #   end
+      def configure
+        yield(config)
+      end
+    end
+  end
+end

data/lib/verikloak-rails.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require 'verikloak/rails'

metadata

@@ -0,0 +1,96 @@
+--- !ruby/object:Gem::Specification
+name: verikloak-rails
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- taiyaky
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: verikloak
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.2
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.2
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+description: 'Rails integration for Verikloak: auto middleware, helpers, JSON errors,
+  BFF header support.'
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/generators/verikloak/install/install_generator.rb
+- lib/verikloak-rails.rb
+- lib/verikloak/rails.rb
+- lib/verikloak/rails/configuration.rb
+- lib/verikloak/rails/controller.rb
+- lib/verikloak/rails/error_renderer.rb
+- lib/verikloak/rails/middleware_integration.rb
+- lib/verikloak/rails/railtie.rb
+- lib/verikloak/rails/version.rb
+homepage: https://github.com/taiyaky/verikloak-rails
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/taiyaky/verikloak-rails
+  changelog_uri: https://github.com/taiyaky/verikloak-rails/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/taiyaky/verikloak-rails/issues
+  documentation_uri: https://rubydoc.info/gems/verikloak-rails/0.1.0
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Rails integration for Verikloak (Keycloak JWT via Rack middleware)
+test_files: []