verikloak-audience 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 983947348061c7b7dd379572850ec12de6bddda37b511b03466301b22c15256f
+  data.tar.gz: 2bd99a2a76fdc020d4f3a51a1db11151d0b38e9429847294f0431abb7e47dd17
+SHA512:
+  metadata.gz: 6bca90d90c7d35408009fcd6007ac317115743eda14dc4e8f1e9853a3fdb9350f4cb5db426e032631faf2e4ef9f96a86885942145bad40d7e809b5eb1a748905
+  data.tar.gz: 3bcc1d7a44a094a3e15d8b33e79fe46ac66e21eb84175799d0469f701522949340e82b43df0d6e029a7396febc9c0ab16a196efdc1cce6bb25358b674019463e

data/CHANGELOG.md

@@ -0,0 +1,17 @@
+# 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-20
+
+### Added
+- Rack middleware for audience validation with configurable profiles (`:strict_single`, `:allow_account`, `:resource_or_aud`).
+- Configuration helpers and profile checker with suggestion logging.
+- Rails railtie for automatic middleware insertion after core Verikloak.
+- Error reference documentation (`ERRORS.md`) describing 403 responses and exception classes.
+- English README with installation, configuration tables, and integration guidance.

data/LICENSE

@@ -0,0 +1,19 @@
+MIT License
+
+Copyright (c) 2025
+
+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 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,85 @@
+# verikloak-audience
+
+Rack middleware for validating the `aud` claim of Keycloak-issued tokens on top of the Verikloak stack. It ships with deploy-friendly presets that address common Keycloak patterns such as `account` co-existence and `resource_access`-driven role enforcement.
+
+For the full error behaviour (response shapes, exception classes, logging hints), see [ERRORS.md](ERRORS.md).
+
+> Insert the middleware immediately **after** `Verikloak::Middleware`. Doing so ensures the token is already verified and the claims are available via `env["verikloak.user"]` (default).
+
+## Why
+- Keycloak often emits multiple audiences (e.g. `["rails-api","account"]`)
+- Some deployments primarily rely on `resource_access[client].roles`
+- Re-implementing permissive/strict `aud` checks per app is a maintenance burden
+
+## Profiles
+
+| Profile | Summary | Suggested scenarios / when `suggest_in_logs` points here |
+|---------|---------|-----------------------------------------------------------|
+| `:strict_single` *(recommended)* | Requires `aud` to match `required_aud` exactly (order-insensitive, no extras). | APIs where audiences are cleanly separated. Logged suggestion when the observed `aud` already equals the configured list. |
+| `:allow_account` | Allows `account` in addition to required audiences (e.g. `["rails-api","account"]`). | SPA + API mixes where Keycloak always emits `account`. Suggested when strict mode fails and the log shows `profile=:allow_account`. |
+| `:resource_or_aud` | Passes when `resource_access[client].roles` is present; otherwise falls back to `:allow_account`. | Services relying on resource roles. Suggested when logs output `profile=:resource_or_aud`. |
+
+## Installation
+
+```bash
+bundle add verikloak-audience
+```
+
+## Rack / Rails usage
+
+Insert **after** `Verikloak::Middleware`:
+
+```ruby
+# config/application.rb
+config.middleware.insert_after Verikloak::Middleware, Verikloak::Audience::Middleware,
+  profile: :allow_account,
+  required_aud: ["rails-api"],
+  resource_client: "rails-api",
+  env_claims_key: "verikloak.user",
+  suggest_in_logs: true
+```
+
+See [`examples/rack.ru`](examples/rack.ru) for a full Rack sample. In Rails, always insert immediately after the core middleware; otherwise `env['verikloak.user']` will be empty and every request will fail with 403.
+
+## Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `profile` | Symbol | `:strict_single` | Profile selector. Accepts `:strict_single`, `:allow_account`, or `:resource_or_aud`. |
+| `required_aud` | Array/String/Symbol | `[]` | Required audience values; coerced to an array internally. |
+| `resource_client` | String | `"rails-api"` | Keycloak client id used to look up `resource_access[client].roles`. |
+| `env_claims_key` | String | `"verikloak.user"` | Rack env key where verified claims are stored. |
+| `suggest_in_logs` | Boolean | `true` | Emits a WARN log with the suggested profile when validation fails. |
+
+`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.
+
+## 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 (core): https://github.com/taiyaky/verikloak
+- verikloak-rails (Rails integration): https://github.com/taiyaky/verikloak-rails
+- verikloak-audience on RubyGems: https://rubygems.org/gems/verikloak-audience

data/lib/verikloak/audience/checker.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Verikloak
+  module Audience
+    # Audience profile checker functions.
+    #
+    # This module provides predicate helpers used by the middleware to decide
+    # whether a given set of claims satisfies the configured profile.
+    module Checker
+      module_function
+
+      # Returns whether the given claims satisfy the configured profile.
+      #
+      # @param claims [Hash] OIDC claims (expects keys like "aud", "resource_access")
+      # @param cfg [Verikloak::Audience::Configuration]
+      # @return [Boolean]
+      def ok?(claims, cfg)
+        profile = cfg.profile.to_sym
+        profile = :strict_single unless %i[strict_single allow_account resource_or_aud].include?(profile)
+
+        case profile
+        when :strict_single
+          strict_single?(claims, cfg.required_aud_list)
+        when :allow_account
+          allow_account?(claims, cfg.required_aud_list)
+        when :resource_or_aud
+          resource_or_aud?(claims, cfg.resource_client.to_s, cfg.required_aud_list)
+        end
+      end
+
+      # Validate that aud matches required exactly (order-insensitive).
+      #
+      # @param claims [Hash]
+      # @param required [Array<String>]
+      # @return [Boolean]
+      def strict_single?(claims, required)
+        aud = Array(claims['aud']).map(&:to_s)
+        return false if required.empty?
+
+        # Must contain all required and have no unexpected extra (order-insensitive)
+        (aud.sort == required.map(&:to_s).sort)
+      end
+
+      # Validate aud allowing "account" as an extra value.
+      #
+      # @param claims [Hash]
+      # @param required [Array<String>]
+      # @return [Boolean]
+      def allow_account?(claims, required)
+        aud = Array(claims['aud']).map(&:to_s)
+        return false if required.empty?
+
+        # Permit 'account' extra
+        extras = aud - required
+        extras.delete('account')
+        extras.empty? && (required - aud).empty?
+      end
+
+      # Permit when resource roles exist for the client; otherwise fallback to
+      # {#allow_account?}.
+      #
+      # @param claims [Hash]
+      # @param client [String]
+      # @param required [Array<String>]
+      # @return [Boolean]
+      def resource_or_aud?(claims, client, required)
+        roles = Array(claims.dig('resource_access', client, 'roles'))
+        return true unless roles.empty? # if roles for client exist, pass
+
+        # otherwise enforce allow_account semantics by default
+        allow_account?(claims, required)
+      end
+
+      # Suggest which profile might fit better, for migration aid.
+      #
+      # @param claims [Hash]
+      # @param cfg [Verikloak::Audience::Configuration]
+      # @return [:strict_single, :allow_account, :resource_or_aud]
+      def suggest(claims, cfg)
+        aud = Array(claims['aud']).map(&:to_s)
+        req = cfg.required_aud_list
+        has_roles = !Array(claims.dig('resource_access', cfg.resource_client.to_s, 'roles')).empty?
+
+        return :strict_single if aud.sort == req.sort
+        return :allow_account if (aud - req) == ['account'] && (req - aud).empty?
+        return :resource_or_aud if has_roles
+
+        :strict_single
+      end
+    end
+  end
+end

data/lib/verikloak/audience/configuration.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Verikloak
+  module Audience
+    # Configuration holder for verikloak-audience.
+    #
+    # @!attribute [rw] profile
+    #   The enforcement profile to use.
+    #   @return [:strict_single, :allow_account, :resource_or_aud]
+    # @!attribute [rw] required_aud
+    #   Required audience(s). Can be a String/Symbol or an Array of them.
+    #   @return [Array<String,Symbol>, String, Symbol]
+    # @!attribute [rw] resource_client
+    #   Client id to use for `resource_access[client].roles` lookup.
+    #   @return [String]
+    # @!attribute [rw] env_claims_key
+    #   Rack env key from which to read verified claims.
+    #   @return [String]
+    # @!attribute [rw] suggest_in_logs
+    #   Whether to log a suggestion when audience validation fails.
+    #   @return [Boolean]
+    class Configuration
+      attr_accessor :profile, :required_aud, :resource_client,
+                    :env_claims_key, :suggest_in_logs
+
+      # Create a configuration with safe defaults.
+      #
+      # @return [void]
+      def initialize
+        @profile         = :strict_single
+        @required_aud    = []
+        @resource_client = 'rails-api'
+        @env_claims_key  = 'verikloak.user'
+        @suggest_in_logs = true
+      end
+
+      # Coerce `required_aud` into an array of strings.
+      #
+      # @return [Array<String>]
+      def required_aud_list
+        Array(required_aud).map(&:to_s)
+      end
+    end
+  end
+end

data/lib/verikloak/audience/errors.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Verikloak
+  module Audience
+    # Base error for audience failures.
+    #
+    # @!attribute [r] code
+    #   Machine-friendly error code (e.g. "insufficient_audience").
+    #   @return [String]
+    # @!attribute [r] http_status
+    #   HTTP status code associated with the error.
+    #   @return [Integer]
+    class Error < StandardError
+      attr_reader :code, :http_status
+
+      # @param msg [String] human-readable error message
+      # @param code [String] machine-friendly error code
+      # @param http_status [Integer] associated HTTP status
+      def initialize(msg = 'audience error', code: 'audience_error', http_status: 403)
+        super(msg)
+        @code = code
+        @http_status = http_status
+      end
+    end
+
+    # Raised when audience is insufficient for the configured profile.
+    class Forbidden < Error
+      # @param msg [String]
+      def initialize(msg = 'insufficient audience')
+        super(msg, code: 'insufficient_audience', http_status: 403)
+      end
+    end
+  end
+end

data/lib/verikloak/audience/middleware.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'verikloak/audience'
+require 'verikloak/audience/configuration'
+require 'verikloak/audience/checker'
+require 'verikloak/audience/errors'
+
+module Verikloak
+  module Audience
+    # Rack middleware that validates audience claims according to configured profile.
+    #
+    # Place this middleware after the core {::Verikloak::Middleware} so that
+    # verified token claims are already available in the Rack env.
+    class Middleware
+      # @param app [#call] next Rack application
+      # @param opts [Hash] configuration overrides (see {Configuration})
+      # @option opts [Symbol] :profile
+      # @option opts [Array<String>,String,Symbol] :required_aud
+      # @option opts [String] :resource_client
+      # @option opts [String] :env_claims_key
+      # @option opts [Boolean] :suggest_in_logs
+      def initialize(app, **opts)
+        @app = app
+        @config = Verikloak::Audience.configure
+        apply_overrides!(opts)
+      end
+
+      # Evaluate the request against the audience profile.
+      #
+      # @param env [Hash] Rack environment
+      # @return [Array(Integer, Hash, #each)] Rack response triple
+      def call(env)
+        claims = env[@config.env_claims_key] || {}
+        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
+          warn("[verikloak-audience] insufficient_audience; suggestion profile=:#{suggestion} aud=#{aud_view}")
+        end
+
+        body = { error: 'insufficient_audience',
+                 message: "Audience not acceptable for profile #{@config.profile}" }.to_json
+        headers = { 'Content-Type' => 'application/json' }
+        [403, headers, [body]]
+      end
+
+      private
+
+      # Apply provided options to the configuration instance.
+      #
+      # @param opts [Hash]
+      # @return [void]
+      def apply_overrides!(opts)
+        cfg = @config
+        opts.each do |k, v|
+          cfg.public_send("#{k}=", v) if cfg.respond_to?("#{k}=")
+        end
+      end
+    end
+  end
+end

data/lib/verikloak/audience/railtie.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'rails/railtie'
+
+module Verikloak
+  module Audience
+    # Rails integration for verikloak-audience.
+    #
+    # This Railtie automatically inserts {Verikloak::Audience::Middleware}
+    # into the Rails middleware stack directly after {::Verikloak::Middleware}
+    # when it is present.
+    #
+    # If the core Verikloak middleware is not available, nothing is inserted.
+    # You may still customize the placement in your application via
+    # `config.middleware`.
+    #
+    # @example Configure placement and options
+    #   # config/application.rb
+    #   config.middleware.insert_after Verikloak::Middleware,
+    #     Verikloak::Audience::Middleware,
+    #     profile: :allow_account,
+    #     required_aud: ['rails-api'],
+    #     resource_client: 'rails-api',
+    #     env_claims_key: 'verikloak.user',
+    #     suggest_in_logs: true
+    class Railtie < ::Rails::Railtie
+      # Adds the audience middleware after the core Verikloak middleware
+      # when available.
+      #
+      # @param app [Rails::Application] the Rails application instance
+      initializer 'verikloak_audience.middleware' do |app|
+        # Insert automatically after core verikloak if present
+        self.class.insert_middleware(app)
+      end
+
+      # Performs the insertion into the middleware stack when the core
+      # Verikloak middleware is available. Extracted for testability without
+      # requiring a full Rails boot process.
+      #
+      # @param app [#middleware] An object exposing a Rack middleware stack via `#middleware`.
+      # @return [void]
+      def self.insert_middleware(app)
+        return unless defined?(::Verikloak::Middleware)
+
+        app.middleware.insert_after ::Verikloak::Middleware, ::Verikloak::Audience::Middleware
+      end
+    end
+  end
+end

data/lib/verikloak/audience/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Verikloak
+  module Audience
+    # Current gem version.
+    # @return [String]
+    VERSION = '0.1.0'
+  end
+end

data/lib/verikloak/audience.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+# Verikloak::Audience provides Audience integration over Keycloak claims.
+require 'verikloak/audience/version'
+require 'verikloak/audience/configuration'
+require 'verikloak/audience/errors'
+require 'verikloak/audience/checker'
+require 'verikloak/audience/middleware'
+require 'verikloak/audience/railtie' if defined?(Rails::Railtie)
+
+module Verikloak
+  # Audience configuration entrypoint and helpers.
+  # This file also requires the public components of the gem.
+  module Audience
+    class << self
+      # Configure verikloak-audience.
+      #
+      # When a block is given, the current configuration is yielded so callers
+      # can mutate settings in one place.
+      #
+      # @yield [config] yields the current configuration for mutation
+      # @yieldparam config [Verikloak::Audience::Configuration]
+      # @return [Verikloak::Audience::Configuration] the resulting configuration
+      def configure
+        @config ||= Configuration.new
+        yield @config if block_given?
+        @config
+      end
+
+      # Access the current configuration without mutating it.
+      #
+      # @return [Verikloak::Audience::Configuration]
+      def config
+        @config ||= Configuration.new
+      end
+    end
+  end
+end

data/lib/verikloak-audience.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# Minimal shim to load the namespaced entrypoint.
+#
+# This file preserves compatibility with Bundler's default require
+# (`require 'verikloak-audience'`) by delegating to the real entrypoint
+# under the namespaced path (`verikloak/audience`).
+require 'verikloak/audience'

metadata

@@ -0,0 +1,96 @@
+--- !ruby/object:Gem::Specification
+name: verikloak-audience
+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: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.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: |
+  Rack middleware that enforces audience checks with deployable profiles,
+  layering on top of Verikloak token verification.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/verikloak-audience.rb
+- lib/verikloak/audience.rb
+- lib/verikloak/audience/checker.rb
+- lib/verikloak/audience/configuration.rb
+- lib/verikloak/audience/errors.rb
+- lib/verikloak/audience/middleware.rb
+- lib/verikloak/audience/railtie.rb
+- lib/verikloak/audience/version.rb
+homepage: https://github.com/taiyaky/verikloak-audience
+licenses:
+- MIT
+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.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: Audience profiles for Keycloak on top of Verikloak
+test_files: []