omniauth_openid_federation 1.2.2

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

data/examples/config/open_id_connect_config.rb.example

@@ -0,0 +1,210 @@
+# OpenID Connect Configuration Class
+# This example shows how to structure OpenID Federation configuration
+# using a configuration class pattern (similar to Anyway::Config)
+#
+# Usage:
+#   1. Copy this file to config/configs/open_id_connect_config.rb
+#   2. Customize the configuration attributes for your needs
+#   3. Use it in your initializers (see federation_endpoint.rb.example)
+#
+# Environment Variables:
+#   OPEN_ID_CONNECT_ENABLED=true
+#   OPEN_ID_CONNECT_CLIENT_ID=your-client-id
+#   OPEN_ID_CONNECT_PRIVATE_KEY_PATH=config/client-private-key.pem
+#   OPEN_ID_CONNECT_SIGNING_KEY_PATH=config/client-signing-private-key.pem
+#   OPEN_ID_CONNECT_ENCRYPTION_KEY_PATH=config/client-encryption-private-key.pem
+#   OPEN_ID_CONNECT_REDIRECT_URI=https://your-app.example.com/users/auth/openid_federation/callback
+#   OPEN_ID_CONNECT_ENTITY_STATEMENT_URL=https://provider.example.com/.well-known/openid-federation
+#   OPEN_ID_CONNECT_CLIENT_ENTITY_STATEMENT_PATH=config/client-entity-statement.jwt
+#   OPEN_ID_CONNECT_CLIENT_ENTITY_STATEMENT_URL=https://your-app.example.com/.well-known/openid-federation
+#   OPEN_ID_CONNECT_ORGANIZATION_NAME=Your Organization Name
+
+require "openssl"
+require "json"
+
+# Base configuration class (if using Anyway::Config gem)
+# If not using Anyway::Config, you can use a simpler pattern:
+#
+# class ApplicationConfig
+#   class << self
+#     delegate_missing_to :instance
+#
+#     private
+#
+#     def instance
+#       @instance ||= new
+#     end
+#   end
+#
+#   def enabled?
+#     ["true", "1"].include?(ENV["#{config_name.to_s.upcase}_ENABLED"]&.to_s&.downcase)
+#   end
+# end
+
+class OpenIdConnectConfig < ApplicationConfig
+  config_name :open_id_connect
+
+  # Configuration attributes
+  # These can be set via environment variables with OPEN_ID_CONNECT_ prefix
+  # or via YAML files (if using Anyway::Config)
+  attr_config :enabled,
+    :client_id,
+    :private_key_path,
+    :private_key_base64,
+    :signing_key_path,
+    :signing_key_base64,
+    :encryption_key_path,
+    :encryption_key_base64,
+    :redirect_uri,
+    :entity_statement_path,
+    :entity_statement_url,
+    :entity_statement_fingerprint,
+    :client_entity_statement_path,
+    :client_entity_statement_url,
+    :client_entity_identifier,
+    :ftn_spname,
+    :acr_values,
+    :organization_name
+
+  # Load private key from file or base64 encoded string
+  # Used for both signing and encryption (DEV/TESTING ONLY)
+  # For production, use separate signing_key and encryption_key
+  def private_key
+    @private_key ||= begin
+      private_key_pem = if private_key_base64.present?
+        Base64.decode64(private_key_base64)
+      elsif private_key_path.present?
+        File.read(Rails.root.join(private_key_path))
+      end
+
+      raise "Private key not found. Set OPEN_ID_CONNECT_PRIVATE_KEY_PATH or OPEN_ID_CONNECT_PRIVATE_KEY_BASE64" if private_key_pem.blank?
+
+      OpenSSL::PKey::RSA.new(private_key_pem)
+    end
+  end
+
+  # Load signing key from file or base64 encoded string
+  # RECOMMENDED for production: Use separate signing key
+  def signing_key
+    return nil if signing_key_path.blank? && signing_key_base64.blank?
+
+    @signing_key ||= begin
+      signing_key_pem = if signing_key_base64.present?
+        Base64.decode64(signing_key_base64)
+      elsif signing_key_path.present?
+        File.read(Rails.root.join(signing_key_path))
+      end
+
+      return nil if signing_key_pem.blank?
+
+      OpenSSL::PKey::RSA.new(signing_key_pem)
+    end
+  end
+
+  # Load encryption key from file or base64 encoded string
+  # RECOMMENDED for production: Use separate encryption key
+  def encryption_key
+    return nil if encryption_key_path.blank? && encryption_key_base64.blank?
+
+    @encryption_key ||= begin
+      encryption_key_pem = if encryption_key_base64.present?
+        Base64.decode64(encryption_key_base64)
+      elsif encryption_key_path.present?
+        File.read(Rails.root.join(encryption_key_path))
+      end
+
+      return nil if encryption_key_pem.blank?
+
+      OpenSSL::PKey::RSA.new(encryption_key_pem)
+    end
+  end
+
+  # Note: client_jwk_signing_key is now automatically extracted by the
+  # omniauth_openid_federation gem from client_entity_statement_path or
+  # client_entity_statement_url when provided.
+  # No manual extraction needed - the library handles this automatically.
+
+  # OpenID Federation 1.0 Section 9: Entity Configuration endpoint
+  # Entity statements MUST be available at /.well-known/openid-federation
+  # URL is the source of truth per OpenID Federation spec
+  def entity_statement_absolute_path
+    return nil if entity_statement_path.blank?
+    @entity_statement_absolute_path ||= Rails.root.join(entity_statement_path)
+  end
+
+  # Get provider entity statement URL
+  # OpenID Federation 1.0 Section 9: MUST be at /.well-known/openid-federation
+  # URL is always required per OpenID Federation specification
+  def entity_statement_url
+    return values[:entity_statement_url] if values[:entity_statement_url].present?
+    nil # Return nil if not configured - must be provided via environment variable
+  end
+
+  # Get client entity statement absolute path
+  def client_entity_statement_absolute_path
+    return nil if client_entity_statement_path.blank?
+    @client_entity_statement_absolute_path ||= Rails.root.join(client_entity_statement_path)
+  end
+
+  # Get client entity statement path for strategy configuration
+  # Prefers URL over path - only returns path if URL is not available
+  def client_entity_statement_path_for_strategy
+    return nil if client_entity_statement_url.present?
+    client_entity_statement_absolute_path
+  end
+
+  # Get client registration type based on entity statement configuration
+  # :automatic - Uses entity statement for automatic client registration
+  # :explicit - Uses explicit client_id and manual registration
+  def client_registration_type
+    (values[:client_entity_statement_url].present? || values[:client_entity_statement_path].present?) ? :automatic : :explicit
+  end
+
+  # Generate client entity statement URL
+  # URL is for external consumers (providers) - we never access it ourselves
+  # Uses standard path /.well-known/openid-federation (mounted by library)
+  def client_entity_statement_url
+    return values[:client_entity_statement_url] if values[:client_entity_statement_url].present?
+    # Default to standard federation endpoint if not explicitly configured
+    app_url = ENV["APP_URL"] || "https://your-app.example.com"
+    "#{app_url}/.well-known/openid-federation"
+  end
+end
+
+# Usage in initializer (config/initializers/omniauth_openid_federation.rb):
+#
+# open_id_config = OpenIdConnectConfig.new
+# if open_id_config.enabled? && open_id_config.private_key.present?
+#   app_url = ENV["APP_URL"] || "https://your-app.example.com"
+#
+#   OmniauthOpenidFederation::FederationEndpoint.auto_configure(
+#     issuer: app_url,
+#     # Production (RECOMMENDED): Use separate keys
+#     signing_key: open_id_config.signing_key,
+#     encryption_key: open_id_config.encryption_key,
+#     # Development/Testing (NOT RECOMMENDED FOR PRODUCTION): Single key
+#     # private_key: open_id_config.private_key,
+#     entity_statement_path: open_id_config.client_entity_statement_absolute_path,
+#     metadata: {
+#       openid_relying_party: {
+#         redirect_uris: [
+#           open_id_config.redirect_uri
+#         ],
+#         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",
+#         organization_name: open_id_config.organization_name
+#       }
+#     },
+#     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
+

data/examples/config/routes.rb.example

@@ -0,0 +1,12 @@
+# Example routes.rb showing how to mount the federation endpoint
+Rails.application.routes.draw do
+  # Mount the federation endpoint (required for serving entity statements)
+  # This enables the /.well-known/openid-federation endpoint
+  OmniauthOpenidFederation::FederationEndpoint.mount_routes(self)
+
+  # Or mount manually:
+  # get "/.well-known/openid-federation", to: "omniauth_openid_federation/federation#show", as: :openid_federation
+
+  # Your other routes...
+end
+

data/examples/db/migrate/add_omniauth_to_users.rb.example

@@ -0,0 +1,16 @@
+# Example migration for adding OmniAuth fields to users table
+# Copy this to db/migrate/XXXXXX_add_omniauth_to_users.rb
+
+class AddOmniauthToUsers < ActiveRecord::Migration[7.0]
+  def change
+    add_column :users, :provider, :string
+    add_column :users, :uid, :string
+    add_index :users, [:provider, :uid], unique: true
+    
+    # Optional: add user info fields if not already present
+    add_column :users, :name, :string unless column_exists?(:users, :name)
+    add_column :users, :first_name, :string unless column_exists?(:users, :first_name)
+    add_column :users, :last_name, :string unless column_exists?(:users, :last_name)
+  end
+end
+