omniauth_openid_federation 1.2.0

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
+

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)"
+

data/examples/config/mock_op.yml.example

@@ -0,0 +1,83 @@
+# Mock OpenID Provider (OP) Server Configuration
+#
+# Copy this file to config/mock_op.yml and customize for your testing needs
+
+# Entity Identifier (Entity ID) for the OP
+entity_id: "https://op.example.com"
+
+# Server host and port
+server_host: "localhost:9292"
+
+# Private key for signing entity statements and ID tokens
+# Can be:
+#   - PEM format (with BEGIN/END markers)
+#   - Base64 encoded PEM
+#   - Path to key file (not recommended for production)
+# If not provided, a new key will be generated (for testing only)
+signing_key: |
+  -----BEGIN RSA PRIVATE KEY-----
+  MIIEpAIBAAKCAQEA...
+  -----END RSA PRIVATE KEY-----
+
+# Trust Anchors for validating incoming RPs
+# Each trust anchor must have:
+#   - entity_id: Trust Anchor Entity Identifier
+#   - jwks: Trust Anchor JWKS for validation
+trust_anchors:
+  - entity_id: "https://ta.example.com"
+    jwks:
+      keys:
+        - kty: "RSA"
+          use: "sig"
+          kid: "ta-key-1"
+          n: "..."
+          e: "AQAB"
+
+# Authority hints (for OP's Entity Configuration)
+# List of Immediate Superiors' Entity Identifiers
+# Leave empty if this OP is a Trust Anchor
+authority_hints:
+  - "https://federation.example.com"
+
+# OP Metadata (OpenID Provider metadata)
+op_metadata:
+  issuer: "https://op.example.com"
+  authorization_endpoint: "https://op.example.com/auth"
+  token_endpoint: "https://op.example.com/token"
+  userinfo_endpoint: "https://op.example.com/userinfo"
+  jwks_uri: "https://op.example.com/.well-known/jwks.json"
+  signed_jwks_uri: "https://op.example.com/.well-known/signed-jwks.json"
+  client_registration_types_supported:
+    - "automatic"
+    - "explicit"
+  response_types_supported:
+    - "code"
+  grant_types_supported:
+    - "authorization_code"
+  id_token_signing_alg_values_supported:
+    - "RS256"
+  scopes_supported:
+    - "openid"
+    - "profile"
+    - "email"
+
+# Subordinate Statements (for Fetch Endpoint)
+# Maps subject Entity IDs to their Subordinate Statement configuration
+subordinate_statements:
+  "https://rp.example.com":
+    metadata:
+      openid_relying_party:
+        redirect_uris:
+          - "https://rp.example.com/callback"
+        client_registration_types:
+          - "automatic"
+        application_type: "web"
+    metadata_policy:
+      openid_relying_party:
+        grant_types:
+          subset_of:
+            - "authorization_code"
+        response_types:
+          subset_of:
+            - "code"
+