verikloak-rails

Rails integration for Verikloak.

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.

• 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

• Ruby: >= 3.1
• Rails: 6.1 – 8.x
• verikloak: >= 0.2.0, < 1.0.0

bundle add verikloak verikloak-rails
rails g verikloak:install

Then configure config/initializers/verikloak.rb.

The helpers follow this priority order:

1. Primary: request.env (Rack environment) - Set directly by Verikloak::Middleware
2. Fallback: RequestStore.store (when available) - Thread-local storage for background jobs

Examples:

# In a controller action (normal case)
current_user_claims  # reads from request.env['verikloak.user']
current_token        # reads from request.env['verikloak.token']

# In a background job triggered during request
# (when RequestStore gem is present and middleware has mirrored values)
current_user_claims  # falls back to RequestStore.store[:verikloak_user]
current_token        # falls back to RequestStore.store[:verikloak_token]

# When RequestStore is not available or disabled
current_user_claims  # returns nil if not in request.env
current_token        # returns nil if not in request.env

Custom Environment Keys: If you configure custom token_env_key or user_env_key, the helpers automatically adapt to use those keys instead of the defaults.

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

If you disable auto-inclusion of the controller concern, add it manually:

# 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

Support for BFF header handling (e.g., normalizing or enforcing X-Forwarded-Access-Token) now lives in a dedicated gem: verikloak-bff. Note: verikloak-bff's HeaderGuard never overwrites an existing Authorization header.

• Gem: https://github.com/taiyaky/verikloak-bff
• Rails guide: docs/rails.md in that repository

When verikloak-bff is on the load path, verikloak-rails automatically inserts Verikloak::Bff::HeaderGuard before the base middleware so forwarded headers are normalized before verification. Control this via config.verikloak.auto_insert_bff_header_guard and the bff_header_guard_insert_before/after knobs.

Use verikloak-bff alongside this gem when you front Rails with a BFF/proxy such as oauth2-proxy and need to enforce trusted forwarding and header consistency.

Assign config.verikloak.bff_header_guard_options to customize the guard before it is inserted. Provide either a Hash (merged via attribute writers) or a block/ callable that receives the Verikloak::BFF.configure object so you can set advanced options such as trusted proxies, forwarded header names, or custom log hooks directly from the Rails initializer.

Keys under config.verikloak:

Environment variable examples are in the generated initializer.

• Required: set discovery_url to your provider’s OIDC discovery document URL.
• Recommended: set audience (expected aud), and issuer when known.

# 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'

  # For BFF/proxy header handling, see verikloak-bff (auto inserted when present)
  # To customize ordering:
  # config.verikloak.middleware_insert_before = Rack::Attack
  # config.verikloak.auto_insert_bff_header_guard = false
end

Notes:

• For array-like values (audience, skip_paths), prefer defining Ruby arrays in the initializer. If passing via ENV, use comma-separated strings and parse in the initializer.

# 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]

  config.verikloak.logger_tags = %i[request_id sub]
  config.verikloak.render_500_json = ENV.fetch('VERIKLOAK_RENDER_500', 'false') == 'true'

  # Optional Pundit rescue (403 JSON). Leave commented if you use
  # verikloak-pundit so it can disable the built-in handler automatically.
  # config.verikloak.rescue_pundit = ENV.fetch('VERIKLOAK_RESCUE_PUNDIT', 'true') == 'true'
end

This gem standardizes JSON error responses and HTTP statuses. See ERRORS.md for details and examples.

Customize rendering by assigning config.verikloak.error_renderer.

Example: return a compact JSON shape while preserving WWW-Authenticate for 401.

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:

class CompactErrorRenderer
  private
  def sanitize_quoted(val)
    # Escape quotes/backslashes and strip CR/LF (collapse runs to a single space)
    val.to_s.gsub(/(["\\])/) { |m| "\\#{m}" }.gsub(/[\r\n]+/, ' ')
  end
end

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.

When the optional verikloak-pundit gem is loaded, the built-in rescue is automatically disabled to avoid double-handling errors—as long as the initializer leaves config.verikloak.rescue_pundit unset. Uncomment the initializer line (or set the value elsewhere) if you prefer different behavior.

Toggle with config.verikloak.rescue_pundit (default: true; leave unset to allow verikloak-pundit to disable it). Environment example:

# 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

# When Pundit raises:
raise Pundit::NotAuthorizedError, 'forbidden'
# The concern rescues and renders:
# { error: 'forbidden', message: 'forbidden' } with status 403

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:

# config/application.rb
module YourApp
  class Application < Rails::Application
    config.active_support.to_time_preserves_timezone = :zone
  end
end

Clone and install dependencies:

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.

All pull requests and pushes are automatically tested with RSpec and RuboCop via GitHub Actions. See the CI badge at the top for current build status.

To run the test suite locally:

docker compose run --rm dev rspec
docker compose run --rm dev rubocop -a

Bug reports and pull requests are welcome! Please see CONTRIBUTING.md for details.

If you find a security vulnerability, please follow the instructions in SECURITY.md.

This project is licensed under the MIT License.

Gem release instructions are documented separately in MAINTAINERS.md.

See CHANGELOG.md for release history.

• verikloak-rails (this gem): https://rubygems.org/gems/verikloak-rails
• verikloak-bff: https://rubygems.org/gems/verikloak-bff
• Verikloak (base gem): https://github.com/taiyaky/verikloak
• Verikloak on RubyGems: https://rubygems.org/gems/verikloak