verikloak-audience 0.2.8 → 0.2.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 88a1386b46aebb2940ede856bdde5993bd68a05000d71f9f5784d73dd85c2fc6
-  data.tar.gz: cf84cfe50d3a6acf004ce0535b02b1644693d2c89b78e422d809b0f184e53cc3
+  metadata.gz: 53894e2af5f290a98ec6f438b9d0271e1f8e86d18c6404c9b0394c5cd5741312
+  data.tar.gz: 0cc799a43b2559f34113e6d738d1e2ee004c1292c86115dc83918ca32aeef04f
 SHA512:
-  metadata.gz: c97758819fac422b4f81e5d22655b677f7d1bd762430e8fd68d038b1fdf9adce004da3261b6de5d2af66874a9dc2a417a1c1272933d51acd979e55416131e4dc
-  data.tar.gz: b12d1fa1f74f5b4d1bb17e461956ecabf4e094eb673b9a03e47bb174603ebcacf3d6bc3a48bab9854df8c3d94b3f6a7d252080f83248ca841354465554191740
+  metadata.gz: 9536f08a7ce2f5de4113483215386221dec1867c6affbea7a0e3074239017c1d7e0d4135476f72cf45cbda1de2fc17781fdf9662d038eb110afdb336a5ee6bb3
+  data.tar.gz: 5730013314cd5dd393c9936256a5fe31cb3aa13fac4c3dda6dabb7ca308424167235d0482167f2cc92c13e26ee5bdef23eaeddab5f01b7898ea31474aeb3211d

data/CHANGELOG.md

@@ -7,6 +7,19 @@ 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

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/verikloak/audience/version.rb

@@ -4,6 +4,6 @@ module Verikloak
   module Audience
     # Current gem version.
     # @return [String]
-    VERSION = '0.2.8'
+    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.8
+  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.8
+  documentation_uri: https://rubydoc.info/gems/verikloak-audience/0.2.9
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: