verikloak-audience 0.2.7 → 0.2.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 59d9195c0dfe4835b91a16bf8f08a58369f398890b5aff664979421a388a91d1
-  data.tar.gz: 8bd59e610df30f6eb1238b06f12a2778ddb0287264a967424751db38acae2f81
+  metadata.gz: 53894e2af5f290a98ec6f438b9d0271e1f8e86d18c6404c9b0394c5cd5741312
+  data.tar.gz: 0cc799a43b2559f34113e6d738d1e2ee004c1292c86115dc83918ca32aeef04f
 SHA512:
-  metadata.gz: 0d5d65f4ff5ca863d1f638b7e19a71edb256aa905bcc21b1ac49802b4c8db53697ed50d6f45bd67730a147a215972ddadbc78a403155e5d3b6ea1cf5b341dc69
-  data.tar.gz: c149176b446b3021204c039d2a07f9297676b57db52ae63f40812029b7f899c7398a425ba1a1542f058303e5a0615d51ebd793b5610d1c9feeb98bd7009c1c88
+  metadata.gz: 9536f08a7ce2f5de4113483215386221dec1867c6affbea7a0e3074239017c1d7e0d4135476f72cf45cbda1de2fc17781fdf9662d038eb110afdb336a5ee6bb3
+  data.tar.gz: 5730013314cd5dd393c9936256a5fe31cb3aa13fac4c3dda6dabb7ca308424167235d0482167f2cc92c13e26ee5bdef23eaeddab5f01b7898ea31474aeb3211d

data/CHANGELOG.md

@@ -7,6 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [0.2.9] - 2025-12-31
+
+### Added
+- **Keycloak Integration** documentation section in README:
+  - Default audience behavior explanation (Access Token: `"account"`, ID Token: Client ID)
+  - Step-by-step guide for configuring Audience Mapper in Keycloak
+  - Configuration examples using `:allow_account` profile and array audiences
+  - Troubleshooting guide with JWT decoding commands
+
+### Documentation
+- Added guidance for common Keycloak + audience validation issues
+- Clarified the relationship between Keycloak client configuration and token `aud` claims
+
+## [0.2.8] - 2025-09-28
+
+### Changed
+- Require `rails/generators` directly in the install generator and inherit via `::Rails::Generators::Base` to avoid constant lookup issues in non-Rails contexts.
+- Document the generator purpose with a `desc` string so `rails g --help` includes a clearer description.
+
+### Fixed
+- Stub Thor semantics in the generator spec and restore `tmpdir` usage so error handling tests assert `Thor::Error`, matching the real generator behavior.
+- Ensure the generator spec recreates missing template and destination conflict scenarios using the same API surface Rails provides.
+
 ## [0.2.7] - 2025-09-27
 
 ### Changed

data/README.md

@@ -71,6 +71,103 @@ See [`examples/rack.ru`](examples/rack.ru) for a full Rack sample. In Rails, alw
 - 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 Integration
+
+### Default Audience Behavior
+
+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.
+
+| Token Type | Default `aud` Value |
+|------------|---------------------|
+| Access Token | `"account"` |
+| ID Token | Client ID |
+
+### Common Issue
+
+```ruby
+# Configuration
+config.verikloak.audience = 'rails-api'
+
+# Actual token payload
+{
+  "aud": "account",  # NOT "rails-api"!
+  "sub": "user-123",
+  ...
+}
+
+# Result: 403 Forbidden - audience validation fails
+```
+
+### Solution: Configure Audience Mapper in Keycloak
+
+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:
+```json
+{
+  "aud": ["rails-api", "account"],
+  ...
+}
+```
+
+### Configuration Examples
+
+#### Option 1: Allow both custom and account audience
+
+```ruby
+# config/initializers/verikloak.rb
+Rails.application.configure do
+  config.verikloak.audience = ['rails-api', 'account']
+end
+```
+
+#### Option 2: Use :allow_account profile
+
+```ruby
+# With verikloak-audience middleware
+use Verikloak::Audience::Middleware,
+  profile: :allow_account,
+  required_aud: ['rails-api']
+```
+
+#### Option 3: Strict single audience (requires Keycloak Mapper)
+
+```ruby
+# Only works if Keycloak Audience Mapper is configured
+use Verikloak::Audience::Middleware,
+  profile: :strict_single,
+  required_aud: ['rails-api']
+```
+
+### Troubleshooting
+
+#### "Audience validation failed" errors
+
+1. Check your token's `aud` claim:
+   ```bash
+   # 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
+
 ## 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.

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

@@ -1,11 +1,6 @@
 # frozen_string_literal: true
 
-begin
-  require 'rails/generators'
-  require 'rails/generators/base'
-rescue LoadError
-  raise unless defined?(Rails::Generators::Base)
-end
+require 'rails/generators'
 
 module Verikloak
   module Audience
@@ -14,9 +9,11 @@ module Verikloak
       # application. This generator creates an initializer that inserts the
       # audience middleware after the core Verikloak middleware once it is
       # available.
-      class InstallGenerator < Rails::Generators::Base
+      class InstallGenerator < ::Rails::Generators::Base
         source_root File.expand_path('templates', __dir__)
 
+        desc 'Creates an initializer for verikloak-audience middleware integration.'
+
         def create_initializer
           template 'initializer.rb.erb', 'config/initializers/verikloak_audience.rb'
         end

data/lib/verikloak/audience/version.rb

@@ -4,6 +4,6 @@ module Verikloak
   module Audience
     # Current gem version.
     # @return [String]
-    VERSION = '0.2.7'
+    VERSION = '0.2.9'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: verikloak-audience
 version: !ruby/object:Gem::Version
-  version: 0.2.7
+  version: 0.2.9
 platform: ruby
 authors:
 - taiyaky
@@ -35,7 +35,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.2.0
+        version: 0.3.0
     - - "<"
       - !ruby/object:Gem::Version
         version: 1.0.0
@@ -45,7 +45,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.2.0
+        version: 0.3.0
     - - "<"
       - !ruby/object:Gem::Version
         version: 1.0.0
@@ -76,7 +76,7 @@ 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.2.7
+  documentation_uri: https://rubydoc.info/gems/verikloak-audience/0.2.9
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: