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.

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).

• 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

bundle add verikloak-audience

In Rails applications, run the generator to create a configuration initializer:

rails g verikloak:audience:install

This creates config/initializers/verikloak_audience.rb with configuration options. The middleware is automatically inserted by the Railtie after Verikloak::Middleware.

Alternatively, you can manually insert after Verikloak::Middleware:

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

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.

• Middleware initialisation now fails fast when required_aud is empty. When Rails loads via the supplied Railtie, Verikloak::Audience.config.validate! runs after boot so configuration mistakes surface during startup instead of returning 403 for every request.
• 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 access tokens include aud: "account" by default. This is often unexpected for developers who expect the client ID to appear in the audience claim.

# Configuration
config.verikloak.audience = 'rails-api'

# Actual token payload
{
  "aud": "account",  # NOT "rails-api"!
  "sub": "user-123",
  ...
}

# Result: 403 Forbidden - audience validation fails

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:

{
  "aud": ["rails-api", "account"],
  ...
}

# config/initializers/verikloak.rb
Rails.application.configure do
  config.verikloak.audience = ['rails-api', 'account']
end

# With verikloak-audience middleware
use Verikloak::Audience::Middleware,
  profile: :allow_account,
  required_aud: ['rails-api']

# Only works if Keycloak Audience Mapper is configured
use Verikloak::Audience::Middleware,
  profile: :strict_single,
  required_aud: ['rails-api']

1. Check your token's aud claim:

   # 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

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-audience on RubyGems: https://rubygems.org/gems/verikloak-audience