verikloak-bff

A framework-agnostic Rack middleware that hardens the BFF / reverse-auth boundary (oauth2-proxy, Nginx auth_request, etc.). It normalizes access tokens from X-Forwarded-Access-Token into Authorization and optionally checks consistency between X-Auth-Request-* headers and JWT claims. Signature and iss/aud/exp validation are performed by the core verikloak middleware placed after this middleware.

• Prefer / require X-Forwarded-Access-Token (configurable)
• Trust-boundary checking for proxy IPs (X-Forwarded-For parsing)
• Header consistency enforcement (Authorization vs Forwarded)
• Claims consistency checks (e.g., email/sub/groups) against X-Auth-Request-*
• Strip suspicious/forged headers before downstream
• Logging hooks for request_id, sub, kid, iss/aud

bundle add verikloak-bff

• Rack-only apps: use Verikloak::BFF::HeaderGuard before your core Verikloak middleware.
• Rails apps: see the full guide in docs/rails.md (Gemfile, middleware order、initializer、proxy examples)。

Use enforce_claims_consistency: { email: :email, user: :sub, groups: :realm_roles } to enable. Header names can be remapped via auth_request_headers.

See examples/rack.ru for a tiny Rack app demo.

This gem returns concise, RFC 6750–style error responses with stable codes. See ERRORS.md for details and examples.

Note: This middleware does not verify JWT signatures or iss/aud/exp itself; it normalizes and guards headers so the core verikloak middleware always performs final verification.

For full reverse proxy examples (Nginx auth_request / oauth2-proxy), see docs/rails.md.

• Peer preference: prefer REMOTE_ADDR before XFF

  • Set peer_preference: :remote_then_xff (default) to evaluate trust using the direct peer first, then fall back to the nearest (rightmost) X-Forwarded-For value.
  • If you run only behind a single, known proxy chain and want to rely solely on XFF ordering, use peer_preference: :xff_only and control position with xff_strategy.

• Header name customization

  • Forwarded-access-token header can be changed via:
    • forwarded_header_name: 'HTTP_X_CUSTOM_FORWARD_TOKEN'
  • X-Auth-Request-* header names can be remapped via:
    • auth_request_headers: { email: 'HTTP_X_EMAIL', user: 'HTTP_X_USER', groups: 'HTTP_X_GROUPS' }

• Authorization seeding from priority headers

  • When no token is chosen and HTTP_AUTHORIZATION is empty, the middleware consults token_header_priority to seed Authorization.
  • HTTP_AUTHORIZATION itself is never used as a source; forwarded headers are considered only from trusted peers.

• Observability helpers

  • Downstream can inspect env['verikloak.bff.token'] (chosen token, unverified) and env['verikloak.bff.selected_peer'] (peer IP selected for trust decisions).
  • Provide a structured log hook with log_with: ->(payload) { logger.info(payload.to_json) } to consume the same fields emitted to logger.
  • Caution: avoid logging the entire Rack env in application logs. Treat env['verikloak.bff.token'] as sensitive; never emit raw tokens or PII (e.g., emails) to logs.

Clone and install dependencies:

git clone https://github.com/taiyaky/verikloak-bff.git
cd verikloak-bff
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 (core): https://github.com/taiyaky/verikloak
• verikloak-rails (Rails integration): https://github.com/taiyaky/verikloak-rails
• verikloak-bff on RubyGems: https://rubygems.org/gems/verikloak-bff