omniauth_openid_federation 1.0.0

data/examples/README_MOCK_OP.md

@@ -0,0 +1,243 @@
+# Mock OpenID Provider (OP) Server
+
+A standalone Rack/Sinatra application for testing OpenID Federation flows.
+
+## Features
+
+- ✅ Entity Configuration endpoint (`/.well-known/openid-federation`)
+- ✅ Fetch Endpoint (`/.well-known/openid-federation/fetch`) for Subordinate Statements
+- ✅ Authorization Endpoint (`/auth`) with trust chain resolution
+- ✅ Token Endpoint (`/token`) with ID Token signing
+- ✅ JWKS endpoints (standard and signed)
+- ✅ UserInfo endpoint (mock)
+
+## Quick Start
+
+### 1. Install Dependencies
+
+```bash
+bundle install
+```
+
+### 2. Configure
+
+Copy the example configuration:
+
+```bash
+cp examples/config/mock_op.yml.example examples/config/mock_op.yml
+```
+
+Edit `examples/config/mock_op.yml` with your settings:
+
+```yaml
+entity_id: "https://op.example.com"
+server_host: "localhost:9292"
+signing_key: |
+  -----BEGIN RSA PRIVATE KEY-----
+  ...
+  -----END RSA PRIVATE KEY-----
+trust_anchors:
+  - entity_id: "https://ta.example.com"
+    jwks:
+      keys: [...]
+```
+
+### 3. Generate Keys (if needed)
+
+```bash
+# Generate OP signing key
+openssl genrsa -out op-private-key.pem 2048
+openssl rsa -in op-private-key.pem -pubout -out op-public-key.pem
+
+# Extract JWKS from public key (or use the rake task)
+rake openid_federation:prepare_client_keys
+```
+
+### 4. Run Server
+
+```bash
+# Option 1: Direct Ruby execution
+ruby examples/mock_op_server.rb
+
+# Option 2: Using Rack
+rackup examples/mock_op_server.ru
+
+# Option 3: With specific port
+rackup -p 9292 examples/mock_op_server.ru
+```
+
+## Configuration Options
+
+### Environment Variables
+
+Instead of YAML, you can use environment variables:
+
+```bash
+export OP_ENTITY_ID="https://op.example.com"
+export OP_SERVER_HOST="localhost:9292"
+export OP_SIGNING_KEY="$(cat op-private-key.pem)"
+export OP_TRUST_ANCHORS='[{"entity_id":"https://ta.example.com","jwks":{"keys":[...]}}]'
+export OP_AUTHORITY_HINTS="https://federation.example.com"
+```
+
+### YAML Configuration
+
+See `examples/config/mock_op.yml.example` for full configuration options.
+
+## Testing Scenarios
+
+### 1. Direct Entity Statement (No Trust Chain)
+
+```bash
+# Fetch OP's Entity Configuration
+curl http://localhost:9292/.well-known/openid-federation
+
+# Use in RP configuration
+config.omniauth :openid_federation,
+  issuer: "https://op.example.com",
+  entity_statement_url: "http://localhost:9292/.well-known/openid-federation",
+  client_options: { ... }
+```
+
+### 2. Trust Chain Resolution
+
+```bash
+# Configure trust anchors in mock_op.yml
+trust_anchors:
+  - entity_id: "https://ta.example.com"
+    jwks: {...}
+
+# RP with trust chain
+# The OP will resolve the RP's trust chain automatically
+curl "http://localhost:9292/auth?client_id=https://rp.example.com&redirect_uri=https://rp.example.com/callback"
+```
+
+### 3. Subordinate Statements
+
+```bash
+# Configure subordinate statements in mock_op.yml
+subordinate_statements:
+  "https://rp.example.com":
+    metadata: {...}
+    metadata_policy: {...}
+
+# Fetch Subordinate Statement
+curl "http://localhost:9292/.well-known/openid-federation/fetch?sub=https://rp.example.com"
+```
+
+## Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/.well-known/openid-federation` | GET | Entity Configuration (JWT) |
+| `/.well-known/openid-federation/fetch` | GET | Fetch Subordinate Statement (requires `sub` parameter) |
+| `/.well-known/jwks.json` | GET | Standard JWKS (JSON) |
+| `/.well-known/signed-jwks.json` | GET | Signed JWKS (JWT) |
+| `/auth` | GET | Authorization Endpoint (requires `client_id`, `redirect_uri`) |
+| `/token` | POST | Token Endpoint (requires `code`, `grant_type=authorization_code`) |
+| `/userinfo` | GET | UserInfo Endpoint (mock data) |
+| `/` | GET | Health check and endpoint list |
+
+## Example Flow
+
+### 1. RP Discovers OP
+
+```bash
+# RP fetches OP's Entity Configuration
+curl http://localhost:9292/.well-known/openid-federation
+```
+
+### 2. RP Initiates Authentication
+
+```bash
+# RP redirects user to authorization endpoint
+# client_id is the RP's Entity ID (for automatic registration)
+curl "http://localhost:9292/auth?client_id=https://rp.example.com&redirect_uri=https://rp.example.com/callback&state=xyz&nonce=abc"
+```
+
+### 3. OP Resolves RP's Trust Chain
+
+The OP automatically:
+- Resolves RP's trust chain using `TrustChainResolver`
+- Merges metadata policies using `MetadataPolicyMerger`
+- Validates RP's effective metadata
+- Redirects back to RP with authorization code
+
+### 4. RP Exchanges Code for Tokens
+
+```bash
+curl -X POST http://localhost:9292/token \
+  -d "grant_type=authorization_code" \
+  -d "code=<authorization_code>" \
+  -d "redirect_uri=https://rp.example.com/callback" \
+  -d "client_id=https://rp.example.com"
+```
+
+### 5. RP Validates ID Token
+
+The RP validates the ID Token using the OP's JWKS from the effective metadata.
+
+## Integration with Real RP
+
+To test with a real RP application:
+
+```ruby
+# In RP's config/initializers/devise.rb
+config.omniauth :openid_federation,
+  issuer: "http://localhost:9292",
+  entity_statement_url: "http://localhost:9292/.well-known/openid-federation",
+  trust_anchors: [
+    {
+      entity_id: "https://ta.example.com",
+      jwks: trust_anchor_jwks
+    }
+  ],
+  client_options: {
+    identifier: "https://rp.example.com", # RP's Entity ID
+    redirect_uri: "http://localhost:3000/users/auth/openid_federation/callback",
+    private_key: rp_private_key
+  }
+```
+
+## Limitations
+
+This is a **mock server for testing only**:
+
+- ⚠️ No real user authentication (always returns mock user)
+- ⚠️ Authorization codes stored in memory (lost on restart)
+- ⚠️ No database persistence
+- ⚠️ No production security hardening
+- ⚠️ ID Tokens contain mock user data
+
+## Production Considerations
+
+For production use, you would need:
+
+- Real user authentication system
+- Database for authorization codes and tokens
+- Proper session management
+- Security hardening (rate limiting, CSRF protection, etc.)
+- Real user data in ID Tokens
+- Proper error handling and logging
+
+## Troubleshooting
+
+**"Federation endpoint not configured"**
+- Ensure `signing_key` is provided in config
+- Check that `entity_id` is set
+
+**"Trust chain resolution failed"**
+- Verify `trust_anchors` are correctly configured
+- Ensure trust anchor JWKS are valid
+- Check that RP's Entity ID is resolvable
+
+**"Subordinate Statement not found"**
+- Configure `subordinate_statements` in `mock_op.yml`
+- Ensure subject Entity ID matches exactly
+
+## See Also
+
+- [OpenID Federation 1.0 Specification](https://openid.net/specs/openid-federation-1_0.html)
+- [Main README](../README.md)
+- [Federation Endpoint Documentation](../README.md#publishing-federation-endpoint)
+

data/examples/app/controllers/users/omniauth_callbacks_controller.rb.example

@@ -0,0 +1,33 @@
+# Example OmniAuth callback controller for Devise
+# Copy this to app/controllers/users/omniauth_callbacks_controller.rb
+
+class Users::OmniauthCallbacksController < Devise::OmniauthCallbacksController
+  skip_before_action :authenticate_user!, only: [:openid_federation, :failure]
+
+  def openid_federation
+    auth = request.env["omniauth.auth"]
+    
+    @user = User.find_or_create_from_omniauth(auth)
+    
+    if @user&.persisted?
+      sign_in_and_redirect @user, event: :authentication
+    else
+      redirect_to root_path, alert: "Authentication failed"
+    end
+  end
+
+  def failure
+    error_type = request.env["omniauth.error.type"] || :unknown
+    error_message = request.env["omniauth.error"]&.message || "Authentication failed"
+    
+    Rails.logger.error({
+      message: "OmniAuth authentication failure",
+      error_type: error_type,
+      error_message: error_message,
+      strategy: request.env["omniauth.strategy"]&.name
+    })
+    
+    redirect_to root_path, alert: "Authentication failed: #{error_type}"
+  end
+end
+

data/examples/app/jobs/jwks_rotation_job.rb.example

@@ -0,0 +1,60 @@
+# Background job for proactive JWKS key rotation
+# This job runs periodically to refresh JWKS cache before expiration,
+# ensuring keys are always up-to-date without blocking client requests.
+#
+# Usage:
+# 1. Schedule this job to run periodically (e.g., every 12 hours)
+# 2. Configure cache TTL to be longer than job frequency (e.g., 24 hours)
+# 3. This ensures keys are refreshed proactively, not reactively
+#
+# Example scheduling (using GoodJob, Sidekiq, or similar):
+#
+#   # config/initializers/schedule.rb (for GoodJob)
+#   GoodJob::Cron::Schedule.add("jwks_rotation", {
+#     cron: "0 */12 * * *", # Every 12 hours
+#     class: "JwksRotationJob"
+#   })
+#
+#   # Or with Sidekiq-Cron
+#   Sidekiq::Cron::Job.create(
+#     name: "JWKS Rotation",
+#     cron: "0 */12 * * *",
+#     class: "JwksRotationJob"
+#   )
+class JwksRotationJob < ApplicationJob
+  queue_as :default
+
+  # Rotate JWKS for a specific provider
+  #
+  # @param jwks_uri [String] The JWKS URI to refresh
+  # @param entity_statement_path [String, nil] Path to entity statement for signed JWKS
+  def perform(jwks_uri, entity_statement_path: nil)
+    OmniauthOpenidFederation.rotate_jwks(jwks_uri, entity_statement_path: entity_statement_path)
+  rescue => e
+    # Log error but don't fail - request-level rotation will handle it
+    Rails.logger.error("[JwksRotationJob] Failed to rotate JWKS for #{jwks_uri}: #{e.class} - #{e.message}")
+    # Optionally, send to error tracking service (Sentry, Rollbar, etc.)
+    # Sentry.capture_exception(e) if defined?(Sentry)
+    raise # Re-raise to allow job retry if configured
+  end
+
+  # Rotate JWKS for all configured providers
+  # This is useful when you have multiple providers configured
+  def self.rotate_all
+    # Example: Get all providers from Devise config
+    providers = Devise.omniauth_configs.keys.select { |k| k.to_s.start_with?("openid") }
+    
+    providers.each do |provider_name|
+      config = Devise.omniauth_configs[provider_name]
+      options = config.options
+      client_options = options[:client_options] || options["client_options"] || {}
+      jwks_uri = client_options[:jwks_uri] || client_options["jwks_uri"]
+      entity_statement_path = options[:entity_statement_path] || options["entity_statement_path"]
+
+      if jwks_uri
+        perform_later(jwks_uri, entity_statement_path: entity_statement_path)
+      end
+    end
+  end
+end
+

data/examples/app/models/user.rb.example

@@ -0,0 +1,39 @@
+# Example User model with OmniAuth integration
+# Add these methods to your existing User model
+
+class User < ApplicationRecord
+  # Required columns (add via migration):
+  # - provider (string)
+  # - uid (string)
+  # - email (string)
+  # - name (string)
+  # - first_name (string, optional)
+  # - last_name (string, optional)
+
+  def self.find_or_create_from_omniauth(auth)
+    user = find_by(provider: auth.provider, uid: auth.uid)
+    
+    if user
+      # Update existing user info
+      user.update(
+        email: auth.info.email,
+        name: auth.info.name,
+        first_name: auth.info.first_name,
+        last_name: auth.info.last_name
+      )
+    else
+      # Create new user
+      user = create(
+        provider: auth.provider,
+        uid: auth.uid,
+        email: auth.info.email,
+        name: auth.info.name,
+        first_name: auth.info.first_name,
+        last_name: auth.info.last_name
+      )
+    end
+    
+    user
+  end
+end
+

data/examples/config/initializers/devise.rb.example

@@ -0,0 +1,97 @@
+# Example Devise configuration for OmniAuth OpenID Federation
+# Copy this to config/initializers/devise.rb and customize for your provider
+
+require "omniauth_openid_federation"
+
+# Configure global settings (optional but recommended)
+OmniauthOpenidFederation.configure do |config|
+  # Security instrumentation - get notified about security events, MITM attacks, etc.
+  # Example with Sentry:
+  # config.instrumentation = ->(event, data) do
+  #   Sentry.capture_message(
+  #     "OpenID Federation: #{event}",
+  #     level: data[:severity] == :error ? :error : :warning,
+  #     extra: data
+  #   )
+  # end
+  
+  # Example with Honeybadger:
+  # config.instrumentation = ->(event, data) do
+  #   Honeybadger.notify("OpenID Federation: #{event}", context: data)
+  # end
+  
+  # Example with custom logger:
+  # config.instrumentation = ->(event, data) do
+  #   Rails.logger.warn("[Security] #{event}: #{data.inspect}")
+  # end
+  
+  # Cache configuration (optional)
+  # config.cache_ttl = 3600  # Refresh provider keys every hour
+  # config.rotate_on_errors = true  # Auto-handle provider key rotation
+end
+
+# Provider configuration
+provider_issuer = ENV["OPENID_PROVIDER_ISSUER"] || "https://provider.example.com"
+client_id = ENV["OPENID_CLIENT_ID"] || "your-client-id"
+redirect_uri = "#{ENV["APP_URL"] || "https://your-app.com"}/users/auth/openid_federation/callback"
+
+# File paths
+private_key_path = Rails.root.join("config", "client-private-key.pem")
+entity_statement_path = Rails.root.join("config", "provider-entity-statement.jwt")
+
+# Load private key
+unless File.exist?(private_key_path)
+  raise "Private key not found at #{private_key_path}. Generate it first using the example in README."
+end
+private_key = OpenSSL::PKey::RSA.new(File.read(private_key_path))
+
+# Resolve endpoints from entity statement or manual configuration
+endpoints = if File.exist?(entity_statement_path)
+  # Use entity statement if available (recommended for OpenID Federation)
+  OmniauthOpenidFederation::EndpointResolver.resolve(
+    entity_statement_path: entity_statement_path.to_s,
+    config: {}
+  )
+else
+  # Fallback to manual configuration
+  {
+    authorization_endpoint: ENV["OPENID_AUTHORIZATION_ENDPOINT"] || "/oauth2/authorize",
+    token_endpoint: ENV["OPENID_TOKEN_ENDPOINT"] || "/oauth2/token",
+    userinfo_endpoint: ENV["OPENID_USERINFO_ENDPOINT"] || "/oauth2/userinfo",
+    jwks_uri: ENV["OPENID_JWKS_URI"] || "/.well-known/jwks.json",
+    audience: provider_issuer
+  }
+end
+
+# Validate endpoints
+OmniauthOpenidFederation::EndpointResolver.validate_and_build_audience(
+  endpoints,
+  issuer_uri: URI.parse(provider_issuer)
+)
+
+Devise.setup do |config|
+  # ... your other Devise configuration ...
+
+  config.omniauth :openid_federation,
+    name: :openid_federation,
+    scope: [:openid],
+    response_type: "code",
+    discovery: true,
+    issuer: provider_issuer,
+    client_auth_method: :jwt_bearer,
+    client_signing_alg: :RS256,
+    audience: endpoints[:audience],
+    entity_statement_path: entity_statement_path.to_s,
+    client_options: {
+      identifier: client_id,
+      redirect_uri: redirect_uri,
+      private_key: private_key,
+      scheme: URI.parse(provider_issuer).scheme,
+      host: URI.parse(provider_issuer).host,
+      authorization_endpoint: endpoints[:authorization_endpoint],
+      token_endpoint: endpoints[:token_endpoint],
+      userinfo_endpoint: endpoints[:userinfo_endpoint],
+      jwks_uri: endpoints[:jwks_uri]
+    }
+end
+

data/examples/config/initializers/federation_endpoint.rb.example

@@ -0,0 +1,206 @@
+# Federation Endpoint Configuration
+# This enables publishing an entity statement at /.well-known/openid-federation
+# Required for OpenID Federation 1.0 compliance with signed JWKS support
+#
+# The entity statement is a self-signed JWT that contains:
+# - Entity metadata (endpoints, configuration)
+# - JWKS for signature validation (both signing and encryption keys)
+# - Issuer and subject information
+#
+# Supports two entity types:
+# - openid_relying_party (RP): For clients/relying parties (PRIMARY USE CASE)
+# - openid_provider (OP): For providers/servers (secondary use case)
+#
+# Automatic Key Provisioning:
+# - Extracts JWKS from entity_statement_path if provided (cached, supports key rotation)
+# - Supports separate signing_key and encryption_key (RECOMMENDED for production)
+# - Falls back to single private_key (DEV/TESTING ONLY - not recommended for production)
+# - Automatically generates both signing and encryption keys from provided keys
+
+require "omniauth_openid_federation"
+
+# ============================================================================
+# Global Configuration (Optional but Recommended)
+# ============================================================================
+OmniauthOpenidFederation.configure do |config|
+  # Security instrumentation - get notified about security events, MITM attacks, etc.
+  # Example with Sentry:
+  # config.instrumentation = ->(event, data) do
+  #   Sentry.capture_message(
+  #     "OpenID Federation: #{event}",
+  #     level: data[:severity] == :error ? :error : :warning,
+  #     extra: data
+  #   )
+  # end
+  
+  # Example with Honeybadger:
+  # config.instrumentation = ->(event, data) do
+  #   Honeybadger.notify("OpenID Federation: #{event}", context: data)
+  # end
+  
+  # Example with custom logger:
+  # config.instrumentation = ->(event, data) do
+  #   Rails.logger.warn("[Security] #{event}: #{data.inspect}")
+  # end
+  
+  # Cache configuration (optional)
+  # config.cache_ttl = 3600  # Refresh provider keys every hour
+  # config.rotate_on_errors = true  # Auto-handle provider key rotation
+end
+
+# ============================================================================
+# EXAMPLE 1: Relying Party (RP) Configuration (PRIMARY USE CASE)
+# ============================================================================
+# For client applications that authenticate users via OpenID Federation
+
+app_url = ENV["APP_URL"] || "https://your-app.example.com"
+
+# Production Setup (RECOMMENDED): Separate signing and encryption keys
+signing_key_path = Rails.root.join("config", "client-signing-private-key.pem")
+encryption_key_path = Rails.root.join("config", "client-encryption-private-key.pem")
+
+if File.exist?(signing_key_path) && File.exist?(encryption_key_path)
+  # Production: Use separate keys
+  signing_key = OpenSSL::PKey::RSA.new(File.read(signing_key_path))
+  encryption_key = OpenSSL::PKey::RSA.new(File.read(encryption_key_path))
+
+  OmniauthOpenidFederation::FederationEndpoint.auto_configure(
+    issuer: app_url,
+    signing_key: signing_key,
+    encryption_key: encryption_key,
+    entity_statement_path: Rails.root.join("config", "client-entity-statement.jwt"), # Cache for key rotation
+    metadata: {
+      openid_relying_party: {
+        redirect_uris: [
+          "#{app_url}/users/auth/openid_federation/callback"
+        ],
+        client_registration_types: ["automatic"],
+        application_type: "web",
+        grant_types: ["authorization_code"],
+        response_types: ["code"],
+        token_endpoint_auth_method: "private_key_jwt",
+        token_endpoint_auth_signing_alg: "RS256",
+        request_object_signing_alg: "RS256",
+        id_token_encrypted_response_alg: "RSA-OAEP",
+        id_token_encrypted_response_enc: "A128CBC-HS256"
+      }
+    },
+    expiration_seconds: (ENV["FEDERATION_EXPIRATION_SECONDS"] || 86400).to_i,
+    jwks_cache_ttl: (ENV["FEDERATION_JWKS_CACHE_TTL"] || 3600).to_i,
+    auto_provision_keys: true
+  )
+else
+  # Development/Testing (NOT RECOMMENDED FOR PRODUCTION): Single private key
+  private_key_path = Rails.root.join("config", "client-private-key.pem")
+  unless File.exist?(private_key_path)
+    Rails.logger.warn "[FederationEndpoint] Private key not found at #{private_key_path}. Generate it first."
+    Rails.logger.warn "  Run: bundle exec rake omniauth_openid_federation:prepare_client_keys"
+    next
+  end
+  private_key = OpenSSL::PKey::RSA.new(File.read(private_key_path))
+
+  OmniauthOpenidFederation::FederationEndpoint.auto_configure(
+    issuer: app_url,
+    private_key: private_key, # DEV/TESTING ONLY - not recommended for production
+    entity_statement_path: Rails.root.join("config", "client-entity-statement.jwt"),
+    metadata: {
+      openid_relying_party: {
+        redirect_uris: [
+          "#{app_url}/users/auth/openid_federation/callback"
+        ],
+        client_registration_types: ["automatic"],
+        application_type: "web",
+        grant_types: ["authorization_code"],
+        response_types: ["code"],
+        token_endpoint_auth_method: "private_key_jwt",
+        token_endpoint_auth_signing_alg: "RS256",
+        request_object_signing_alg: "RS256",
+        id_token_encrypted_response_alg: "RSA-OAEP",
+        id_token_encrypted_response_enc: "A128CBC-HS256"
+      }
+    },
+    expiration_seconds: (ENV["FEDERATION_EXPIRATION_SECONDS"] || 86400).to_i,
+    jwks_cache_ttl: (ENV["FEDERATION_JWKS_CACHE_TTL"] || 3600).to_i,
+    auto_provision_keys: true
+  )
+end
+
+# ============================================================================
+# EXAMPLE 2: OpenID Provider (OP) Configuration (SECONDARY USE CASE)
+# ============================================================================
+# For provider/server applications that serve authentication
+# Uncomment and configure if you're building a provider:
+
+# Production Setup (RECOMMENDED): Separate signing and encryption keys
+# provider_url = ENV["PROVIDER_URL"] || "https://provider.example.com"
+#
+# signing_key = OpenSSL::PKey::RSA.new(File.read("config/provider-signing-key.pem"))
+# encryption_key = OpenSSL::PKey::RSA.new(File.read("config/provider-encryption-key.pem"))
+#
+# OmniauthOpenidFederation::FederationEndpoint.auto_configure(
+#   issuer: provider_url,
+#   signing_key: signing_key,
+#   encryption_key: encryption_key,
+#   entity_statement_path: Rails.root.join("config", "provider-entity-statement.jwt"),
+#   metadata: {
+#     openid_provider: {
+#       issuer: provider_url,
+#       authorization_endpoint: "#{provider_url}/oauth2/authorize",
+#       token_endpoint: "#{provider_url}/oauth2/token",
+#       userinfo_endpoint: "#{provider_url}/oauth2/userinfo",
+#       jwks_uri: "#{provider_url}/.well-known/jwks.json",
+#       signed_jwks_uri: "#{provider_url}/.well-known/signed-jwks.json",
+#       federation_fetch_endpoint: "#{provider_url}/.well-known/openid-federation/fetch" # Auto-added for OPs
+#     }
+#   },
+#   expiration_seconds: (ENV["FEDERATION_EXPIRATION_SECONDS"] || 86400).to_i,
+#   jwks_cache_ttl: (ENV["FEDERATION_JWKS_CACHE_TTL"] || 3600).to_i,
+#   auto_provision_keys: true
+# )
+
+# Development/Testing (NOT RECOMMENDED FOR PRODUCTION): Single private key
+# provider_url = ENV["PROVIDER_URL"] || "https://provider.example.com"
+# private_key = OpenSSL::PKey::RSA.new(File.read("config/provider-private-key.pem"))
+#
+# OmniauthOpenidFederation::FederationEndpoint.auto_configure(
+#   issuer: provider_url,
+#   private_key: private_key, # DEV/TESTING ONLY - not recommended for production
+#   entity_statement_path: Rails.root.join("config", "provider-entity-statement.jwt"),
+#   metadata: {
+#     openid_provider: {
+#       issuer: provider_url,
+#       authorization_endpoint: "#{provider_url}/oauth2/authorize",
+#       token_endpoint: "#{provider_url}/oauth2/token",
+#       userinfo_endpoint: "#{provider_url}/oauth2/userinfo",
+#       jwks_uri: "#{provider_url}/.well-known/jwks.json",
+#       signed_jwks_uri: "#{provider_url}/.well-known/signed-jwks.json",
+#       federation_fetch_endpoint: "#{provider_url}/.well-known/openid-federation/fetch" # Auto-added for OPs
+#     }
+#   },
+#   expiration_seconds: (ENV["FEDERATION_EXPIRATION_SECONDS"] || 86400).to_i,
+#   jwks_cache_ttl: (ENV["FEDERATION_JWKS_CACHE_TTL"] || 3600).to_i,
+#   auto_provision_keys: true
+# )
+
+# ============================================================================
+# Routes Configuration
+# ============================================================================
+# Add to config/routes.rb:
+#
+#   OmniauthOpenidFederation::FederationEndpoint.mount_routes(self)
+#
+# This mounts all endpoints:
+#   - GET /.well-known/openid-federation (entity statement)
+#   - GET /.well-known/openid-federation/fetch (fetch endpoint - OPs only)
+#   - GET /.well-known/jwks.json (standard JWKS)
+#   - GET /.well-known/signed-jwks.json (signed JWKS)
+#
+# Or manually:
+#   get "/.well-known/openid-federation", to: "omniauth_openid_federation/federation#show"
+#   get "/.well-known/openid-federation/fetch", to: "omniauth_openid_federation/federation#fetch"
+#   get "/.well-known/jwks.json", to: "omniauth_openid_federation/federation#jwks"
+#   get "/.well-known/signed-jwks.json", to: "omniauth_openid_federation/federation#signed_jwks"
+
+Rails.logger.info "[FederationEndpoint] Configured. Add the route in config/routes.rb:"
+Rails.logger.info "  OmniauthOpenidFederation::FederationEndpoint.mount_routes(self)"
+