omniauth_openid_federation 1.2.2

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,37 @@
+# Example OmniAuth callback controller for Devise
+# Copy this to app/controllers/users/omniauth_callbacks_controller.rb
+
+class Users::OmniauthCallbacksController < Devise::OmniauthCallbacksController
+  # Skip Rails CSRF protection for OAuth callbacks
+  # OAuth callbacks from external providers cannot include Rails CSRF tokens
+  # CSRF protection is handled by OAuth state parameter validation in the strategy
+  skip_before_action :verify_authenticity_token, only: [:openid_federation, :failure]
+  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,131 @@
+# 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 ...
+
+  # OmniAuth 2.0+ defaults to POST only for CSRF protection (CVE-2015-9284)
+  # Always use POST for security - forms must include CSRF token
+  if defined?(OmniAuth)
+    OmniAuth.config.allowed_request_methods = [:post]
+    OmniAuth.config.silence_get_warning = false
+
+    # Configure CSRF validation to check tokens only for request phase (initiating OAuth)
+    # Callback phase uses OAuth state parameter for CSRF protection (validated in strategy)
+    # This ensures:
+    # - Request phase: Forms must include Rails CSRF tokens (standard Rails protection)
+    # - Callback phase: OAuth state parameter provides CSRF protection (external providers can't include Rails tokens)
+    OmniAuth.config.request_validation_phase = lambda do |env|
+      request = Rack::Request.new(env)
+      path = request.path
+
+      # Skip CSRF validation for callback paths (external providers can't include Rails CSRF tokens)
+      # OAuth state parameter provides CSRF protection for callbacks (validated in OpenIDFederation strategy)
+      return true if path.end_with?("/callback")
+
+      # For request phase, use Rails' standard CSRF token validation
+      # This ensures forms must include valid CSRF tokens when initiating OAuth
+      session = env["rack.session"] || {}
+      token = request.params["authenticity_token"] || request.get_header("X-CSRF-Token")
+      expected_token = session[:_csrf_token] || session["_csrf_token"]
+
+      # Validate CSRF token using constant-time comparison
+      if token.present? && expected_token.present?
+        ActiveSupport::SecurityUtils.secure_compare(token.to_s, expected_token.to_s)
+      else
+        false
+      end
+    end
+  end
+
+  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
+