omniauth_openid_federation 1.0.0

data/examples/jobs/README.md

@@ -0,0 +1,194 @@
+# Background Job Examples for Federation Endpoints
+
+This directory contains example background jobs for generating and caching federation files.
+
+## Jobs
+
+### 1. FederationFilesGenerationJob
+
+**Purpose**: Generate and cache federation files (entity statement, JWKS) to disk.
+
+**When to use**:
+- Periodic generation (daily, weekly)
+- After key rotation
+- Before deployment
+- To ensure files are always available
+
+**What it does**:
+- Generates `config/.federation-entity-statement.jwt`
+- Generates `config/.federation-jwks.json`
+- Clears Rails cache for federation endpoints
+
+**Usage**:
+```ruby
+# Schedule in config/schedule.rb (whenever gem)
+every 1.day, at: '2:00 am' do
+  runner 'FederationFilesGenerationJob.perform_later'
+end
+
+# Or call manually
+FederationFilesGenerationJob.perform_later
+```
+
+### 2. FederationCacheRefreshJob
+
+**Purpose**: Refresh cached federation data without generating files.
+
+**When to use**:
+- Periodic cache refresh (hourly, daily)
+- After key rotation
+- When configuration changes
+- To pre-warm caches
+
+**What it does**:
+- Clears all federation-related Rails caches
+- Optionally pre-warms caches for immediate availability
+
+**Usage**:
+```ruby
+# Schedule in config/schedule.rb (whenever gem)
+every 1.hour do
+  runner 'FederationCacheRefreshJob.perform_later'
+end
+
+# Or call manually after key rotation
+FederationCacheRefreshJob.perform_later
+```
+
+## Setup Instructions
+
+### Step 1: Copy Job Files
+
+Copy the example job files to your `app/jobs/` directory:
+
+```bash
+cp examples/jobs/federation_files_generation_job.rb.example app/jobs/federation_files_generation_job.rb
+cp examples/jobs/federation_cache_refresh_job.rb.example app/jobs/federation_cache_refresh_job.rb
+```
+
+### Step 2: Configure Scheduling
+
+Add to `config/schedule.rb` (if using whenever gem):
+
+```ruby
+# Generate federation files daily at 2 AM
+every 1.day, at: '2:00 am' do
+  runner 'FederationFilesGenerationJob.perform_later'
+end
+
+# Refresh caches hourly
+every 1.hour do
+  runner 'FederationCacheRefreshJob.perform_later'
+end
+```
+
+Or use cron directly:
+
+```bash
+# Generate files daily at 2 AM
+0 2 * * * cd /path/to/app && bin/rails runner 'FederationFilesGenerationJob.perform_now'
+
+# Refresh caches hourly
+0 * * * * cd /path/to/app && bin/rails runner 'FederationCacheRefreshJob.perform_now'
+```
+
+### Step 3: Test Jobs
+
+Test the jobs manually:
+
+```bash
+# Test file generation
+bin/rails runner 'FederationFilesGenerationJob.perform_now'
+
+# Test cache refresh
+bin/rails runner 'FederationCacheRefreshJob.perform_now'
+```
+
+## When to Use Each Job
+
+### Use FederationFilesGenerationJob when:
+- ✅ You want files on disk for backup/recovery
+- ✅ You want to serve from files instead of generating on-demand
+- ✅ You need files for external tools or scripts
+- ✅ You want to version control generated files (not recommended for production)
+
+### Use FederationCacheRefreshJob when:
+- ✅ You only need in-memory caching (Rails.cache)
+- ✅ You want to refresh caches without generating files
+- ✅ You want faster cache refresh cycles
+- ✅ You don't need files on disk
+
+### Use Both when:
+- ✅ You want both file generation and cache refresh
+- ✅ You want redundancy (files + cache)
+- ✅ You have different refresh cycles for files vs cache
+
+## Key Rotation Workflow
+
+When rotating keys:
+
+1. **Before rotation**: Generate new files with new keys
+   ```bash
+   bin/rails runner 'FederationFilesGenerationJob.perform_now'
+   ```
+
+2. **After rotation**: Refresh caches
+   ```bash
+   bin/rails runner 'FederationCacheRefreshJob.perform_now'
+   ```
+
+3. **Verify**: Check that endpoints return new keys
+   ```bash
+   curl https://your-app.com/.well-known/jwks.json
+   curl https://your-app.com/.well-known/signed-jwks.json
+   ```
+
+## Monitoring
+
+Monitor job execution:
+
+```ruby
+# In your monitoring system
+FederationFilesGenerationJob.perform_later
+# Check logs for success/failure
+
+# Or use ActiveJob monitoring
+# Check GoodJob dashboard or similar
+```
+
+## Error Handling
+
+Both jobs include error handling:
+- Logs errors to Rails.logger
+- Raises exceptions for job retry (if configured)
+- Continues execution even if one step fails (where appropriate)
+
+## Performance Considerations
+
+- **File Generation**: Takes longer (file I/O), but files persist
+- **Cache Refresh**: Faster (in-memory), but data is ephemeral
+- **Pre-warming**: Optional, ensures data is ready immediately
+
+## Security Considerations
+
+- Generated files contain public keys only (safe to store)
+- Entity statement files are signed JWTs (safe to store)
+- Private keys are never written to files
+- Files should be in `config/` directory (not publicly accessible)
+
+## Troubleshooting
+
+### Job fails with "Federation endpoint not configured"
+- Ensure `FederationEndpoint.configure` is called in initializer
+- Check that all required configuration is set
+
+### Files not generated
+- Check write permissions on `config/` directory
+- Check Rails.logger for error messages
+- Verify configuration is valid
+
+### Cache not refreshing
+- Check that Rails.cache is configured
+- Verify cache keys match expected patterns
+- Check cache TTL settings
+

data/examples/jobs/federation_cache_refresh_job.rb.example

@@ -0,0 +1,78 @@
+# Background Job Example: Federation Cache Refresh
+#
+# This job refreshes cached federation data (entity statements, JWKS) without generating files.
+# Useful for periodic cache refresh or after key rotation.
+#
+# Usage:
+#   # Schedule in config/schedule.rb (whenever gem)
+#   every 1.hour do
+#     runner 'FederationCacheRefreshJob.perform_later'
+#   end
+#
+#   # Or call manually after key rotation
+#   FederationCacheRefreshJob.perform_later
+#
+# Requirements:
+#   - Rails application with ActiveJob configured
+#   - OmniauthOpenidFederation::FederationEndpoint configured
+#   - Rails.cache available
+#
+class FederationCacheRefreshJob < ApplicationJob
+  queue_as :default
+
+  # Refresh federation caches
+  #
+  # Clears all federation-related caches to force fresh data on next request.
+  # This is useful for:
+  #   - Periodic cache refresh
+  #   - After key rotation
+  #   - When configuration changes
+  def perform
+    require "omniauth_openid_federation"
+
+    Rails.logger.info "[FederationCacheRefreshJob] Starting cache refresh..."
+
+    # Clear all federation caches
+    if Rails.cache.respond_to?(:delete_matched)
+      Rails.cache.delete_matched("federation:*")
+      Rails.logger.info "[FederationCacheRefreshJob] Cleared federation caches"
+    else
+      # Fallback: clear known cache keys
+      Rails.cache.delete("federation:jwks")
+      Rails.cache.delete("federation:signed_jwks")
+      Rails.cache.delete("federation:entity_statement")
+      Rails.logger.info "[FederationCacheRefreshJob] Cleared federation caches (fallback)"
+    end
+
+    # Optionally: Pre-warm caches by generating data
+    # This ensures data is ready immediately after cache clear
+    begin
+      config = OmniauthOpenidFederation::FederationEndpoint.configuration
+      
+      # Pre-warm JWKS cache
+      if config.current_jwks || config.current_jwks_proc
+        jwks = OmniauthOpenidFederation::FederationEndpoint.current_jwks
+        cache_key = "federation:jwks:#{Digest::SHA256.hexdigest(jwks.to_json)}"
+        Rails.cache.write(cache_key, jwks.to_json, expires_in: config.jwks_cache_ttl || 3600)
+        Rails.logger.info "[FederationCacheRefreshJob] Pre-warmed JWKS cache"
+      end
+
+      # Pre-warm signed JWKS cache
+      signed_jwks = OmniauthOpenidFederation::FederationEndpoint.generate_signed_jwks
+      cache_key = "federation:signed_jwks:#{Digest::SHA256.hexdigest(signed_jwks)}"
+      config = OmniauthOpenidFederation::FederationEndpoint.configuration
+      Rails.cache.write(cache_key, signed_jwks, expires_in: config.jwks_cache_ttl || 3600)
+      Rails.logger.info "[FederationCacheRefreshJob] Pre-warmed signed JWKS cache"
+    rescue => e
+      Rails.logger.warn "[FederationCacheRefreshJob] Failed to pre-warm caches: #{e.message}"
+      # Don't fail the job if pre-warming fails - cache will be generated on-demand
+    end
+
+    Rails.logger.info "[FederationCacheRefreshJob] Completed successfully"
+  rescue => e
+    Rails.logger.error "[FederationCacheRefreshJob] Error: #{e.class} - #{e.message}"
+    Rails.logger.error "[FederationCacheRefreshJob] Backtrace: #{e.backtrace.first(5).join("\n")}"
+    raise
+  end
+end
+

data/examples/jobs/federation_files_generation_job.rb.example

@@ -0,0 +1,87 @@
+# Background Job Example: Federation Files Generation
+#
+# This job generates and caches federation files (entity statement, JWKS) for better performance.
+# Schedule this job to run periodically (e.g., daily or when keys rotate).
+#
+# Usage:
+#   # Schedule in config/schedule.rb (whenever gem)
+#   every 1.day, at: '2:00 am' do
+#     runner 'FederationFilesGenerationJob.perform_later'
+#   end
+#
+#   # Or call manually
+#   FederationFilesGenerationJob.perform_later
+#
+#   # Or perform synchronously
+#   FederationFilesGenerationJob.perform_now
+#
+# Requirements:
+#   - Rails application with ActiveJob configured
+#   - OmniauthOpenidFederation::FederationEndpoint configured
+#   - Write access to config/ directory
+#
+class FederationFilesGenerationJob < ApplicationJob
+  queue_as :default
+
+  # Generate and cache federation files
+  #
+  # Generates:
+  #   - config/federation-entity-statement.jwt - Entity statement JWT file
+  #   - config/federation-jwks.json - Current JWKS JSON file
+  #
+  # Also clears Rails cache for federation endpoints to ensure fresh data.
+  def perform
+    require "omniauth_openid_federation"
+    require "json"
+
+    config = OmniauthOpenidFederation::FederationEndpoint.configuration
+
+    # Validate configuration
+    unless config.issuer && config.private_key && config.jwks && config.metadata
+      Rails.logger.error "[FederationFilesGenerationJob] Federation endpoint not configured"
+      return
+    end
+
+    Rails.logger.info "[FederationFilesGenerationJob] Starting federation files generation..."
+
+    # Generate entity statement file
+    begin
+      entity_statement = OmniauthOpenidFederation::FederationEndpoint.generate_entity_statement
+      entity_statement_path = Rails.root.join("config", ".federation-entity-statement.jwt")
+      File.write(entity_statement_path, entity_statement)
+      Rails.logger.info "[FederationFilesGenerationJob] Generated entity statement: #{entity_statement_path}"
+    rescue => e
+      Rails.logger.error "[FederationFilesGenerationJob] Failed to generate entity statement: #{e.message}"
+      raise
+    end
+
+    # Generate JWKS file
+    begin
+      jwks = OmniauthOpenidFederation::FederationEndpoint.current_jwks
+      jwks_path = Rails.root.join("config", ".federation-jwks.json")
+      File.write(jwks_path, JSON.pretty_generate(jwks))
+      Rails.logger.info "[FederationFilesGenerationJob] Generated JWKS: #{jwks_path}"
+    rescue => e
+      Rails.logger.error "[FederationFilesGenerationJob] Failed to generate JWKS: #{e.message}"
+      raise
+    end
+
+    # Clear federation caches to ensure fresh data on next request
+    if Rails.cache.respond_to?(:delete_matched)
+      Rails.cache.delete_matched("federation:*")
+      Rails.logger.info "[FederationFilesGenerationJob] Cleared federation caches"
+    else
+      # Fallback: clear known cache keys
+      Rails.cache.delete("federation:jwks")
+      Rails.cache.delete("federation:signed_jwks")
+      Rails.logger.info "[FederationFilesGenerationJob] Cleared federation caches (fallback)"
+    end
+
+    Rails.logger.info "[FederationFilesGenerationJob] Completed successfully"
+  rescue => e
+    Rails.logger.error "[FederationFilesGenerationJob] Error: #{e.class} - #{e.message}"
+    Rails.logger.error "[FederationFilesGenerationJob] Backtrace: #{e.backtrace.first(5).join("\n")}"
+    raise
+  end
+end
+