better_auth-oidc 0.10.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9646ecf4d95be3d28384445b5a3b460fc4ee8c3595664314a7a440d0c26650cc
+  data.tar.gz: aea87903329b9d2bfcb3fc8daf06082c09a6285a406ff64ea67b1dfb67487fd3
+SHA512:
+  metadata.gz: 58b8f64358ad8904db13f6ab687a24c07dd35a6f76c43c9141803ae7c66916cb1b8ca502fa43c930b93fac289abf6012dad9be07b1a08952956bdded208e2f71
+  data.tar.gz: de48d85d3db4ef09297177aed53f604abb4a4a46a0f826e8baf78ea2e993ecee3aba89e696d6dc8597719689d6d1c475112d8ada6892dc85d60486ead915fa8d

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## Unreleased
+
+- Split OIDC relying-party code out of `better_auth-sso` into a dedicated gem without `ruby-saml`.
+
+## 0.10.0
+
+- Initial release (extracted from `better_auth-sso` 0.10.0).

data/README.md

@@ -0,0 +1,25 @@
+# Better Auth OIDC
+
+Enterprise OpenID Connect relying-party helpers for Better Auth Ruby.
+
+Use this package when you need OIDC discovery, JWKS validation, and plugin extensions without pulling in SAML/XML dependencies.
+
+```ruby
+require "better_auth"
+require "better_auth/oidc"
+```
+
+For the full SSO plugin (provider CRUD, domain verification, composed routes), add `better_auth-sso`:
+
+```ruby
+gem "better_auth-sso"
+gem "better_auth-saml" # only when using SAML identity providers
+```
+
+```ruby
+require "better_auth/sso"
+
+BetterAuth.auth(plugins: [BetterAuth::Plugins.sso])
+```
+
+SCIM provisioning is separate (`better_auth-scim`). SAML SP primitives live in `better_auth-saml`.

data/lib/better_auth/oidc/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module OIDC
+    VERSION = "0.10.0"
+  end
+end

data/lib/better_auth/oidc.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "better_auth"
+require "jwt"
+require_relative "oidc/version"
+require_relative "sso/oidc"
+require_relative "sso/oidc/discovery"
+require_relative "sso/oidc/errors"
+require_relative "sso/oidc/types"
+require_relative "sso/plugin/oidc_core"
+require_relative "plugins/oidc"

data/lib/better_auth/plugins/oidc.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "base64"
+require "cgi"
+require "json"
+require "jwt"
+require "net/http"
+require "openssl"
+require "resolv"
+require "securerandom"
+require "time"
+require "uri"
+require "zlib"
+
+require_relative "../sso/plugin/oidc_discovery"
+require_relative "../sso/plugin/oidc_runtime"

data/lib/better_auth/sso/oidc/discovery.rb

@@ -0,0 +1,259 @@
+# frozen_string_literal: true
+
+require "uri"
+require "json"
+require "net/http"
+
+module BetterAuth
+  module SSO
+    module OIDC
+      module Discovery
+        module_function
+
+        REQUIRED_DISCOVERY_FIELDS = %i[issuer authorization_endpoint token_endpoint jwks_uri].freeze
+        DISCOVERY_URL_FIELDS = %i[
+          token_endpoint
+          authorization_endpoint
+          jwks_uri
+          userinfo_endpoint
+          revocation_endpoint
+          end_session_endpoint
+          introspection_endpoint
+        ].freeze
+
+        def compute_discovery_url(issuer)
+          "#{issuer.to_s.sub(%r{/+\z}, "")}/.well-known/openid-configuration"
+        end
+
+        def validate_discovery_url(url, trusted_origin = nil)
+          uri = parse_http_url!(url, "discoveryEndpoint", details: {url: url})
+          return true unless trusted_origin && !trusted_origin.call(uri.to_s)
+
+          raise DiscoveryError.new(
+            "discovery_untrusted_origin",
+            "The main discovery endpoint \"#{uri}\" is not trusted by your trusted origins configuration.",
+            details: {url: uri.to_s}
+          )
+        end
+
+        def validate_discovery_document(document, issuer)
+          doc = BetterAuth::Plugins.normalize_hash(document || {})
+          missing = REQUIRED_DISCOVERY_FIELDS.select { |field| doc[field].to_s.empty? }
+          unless missing.empty?
+            raise DiscoveryError.new(
+              "discovery_incomplete",
+              "OIDC discovery document is missing required fields: #{missing.join(", ")}",
+              details: {missingFields: missing.map(&:to_s)}
+            )
+          end
+
+          discovered = doc[:issuer].to_s.sub(%r{/+\z}, "")
+          configured = issuer.to_s.sub(%r{/+\z}, "")
+          return true if discovered == configured
+
+          raise DiscoveryError.new(
+            "issuer_mismatch",
+            "OIDC discovery issuer does not match configured issuer",
+            details: {discovered: doc[:issuer], configured: issuer}
+          )
+        end
+
+        def normalize_discovery_urls(document, issuer, trusted_origin = nil)
+          doc = BetterAuth::Plugins.normalize_hash(document || {}).dup
+          DISCOVERY_URL_FIELDS.each do |field|
+            next if doc[field].to_s.empty?
+
+            doc[field] = normalize_url(field.to_s, doc[field], issuer, trusted_origin)
+          end
+          doc
+        end
+
+        def fetch_discovery_document(url, timeout: nil, fetch: nil)
+          response = if fetch
+            fetch.call(url, timeout: timeout)
+          else
+            uri = URI(url)
+            Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", read_timeout: timeout) do |http|
+              http.get(uri.request_uri)
+            end
+          end
+          parse_discovery_fetch_response(response)
+        rescue DiscoveryError
+          raise
+        rescue Timeout::Error
+          raise DiscoveryError.new("discovery_timeout", "OIDC discovery request timed out", details: {url: url})
+        rescue => exception
+          if exception.message.match?(/aborted/i)
+            raise DiscoveryError.new("discovery_timeout", "OIDC discovery request timed out", details: {url: url})
+          end
+
+          raise DiscoveryError.new("discovery_unexpected_error", "OIDC discovery request failed", details: {url: url, error: exception.message})
+        end
+
+        def discover_oidc_config(issuer:, fetch: nil, existing_config: nil, discovery_endpoint: nil, trusted_origin: nil, is_trusted_origin: nil, timeout: nil)
+          existing = BetterAuth::Plugins.normalize_hash(existing_config || {})
+          origin_check = trusted_origin || is_trusted_origin
+          discovery_url = discovery_endpoint || existing[:discovery_endpoint] || compute_discovery_url(issuer)
+          validate_discovery_url(discovery_url, origin_check)
+
+          document = fetch_discovery_document(discovery_url, timeout: timeout, fetch: fetch)
+          validate_discovery_document(document, issuer)
+          normalized_document = normalize_discovery_urls(document, issuer, origin_check)
+
+          {
+            issuer: existing[:issuer] || normalized_document[:issuer],
+            discovery_endpoint: existing[:discovery_endpoint] || discovery_url,
+            client_id: existing[:client_id],
+            client_secret: existing[:client_secret],
+            authorization_endpoint: existing[:authorization_endpoint] || normalized_document[:authorization_endpoint],
+            token_endpoint: existing[:token_endpoint] || normalized_document[:token_endpoint],
+            jwks_endpoint: existing[:jwks_endpoint] || normalized_document[:jwks_uri],
+            user_info_endpoint: existing[:user_info_endpoint] || normalized_document[:userinfo_endpoint],
+            token_endpoint_authentication: select_token_endpoint_auth_method(normalized_document, existing[:token_endpoint_authentication]),
+            scopes_supported: existing[:scopes_supported] || normalized_document[:scopes_supported],
+            pkce: existing[:pkce],
+            override_user_info: existing[:override_user_info],
+            mapping: existing[:mapping]
+          }.compact
+        end
+
+        def normalize_url(name_or_value, value_or_issuer, issuer = nil, trusted_origin = nil)
+          name = issuer.nil? ? "url" : name_or_value.to_s
+          value = issuer.nil? ? name_or_value : value_or_issuer
+          issuer_value = issuer.nil? ? value_or_issuer : issuer
+          normalized = normalize_endpoint_url(name, value, issuer_value)
+
+          if trusted_origin && !trusted_origin.call(normalized)
+            raise DiscoveryError.new(
+              "discovery_untrusted_origin",
+              "The #{name} \"#{normalized}\" is not trusted by your trusted origins configuration.",
+              details: {endpoint: name, url: normalized}
+            )
+          end
+
+          normalized
+        end
+
+        def needs_runtime_discovery?(oidc_config)
+          config = BetterAuth::Plugins.normalize_hash(oidc_config || {})
+          config[:authorization_endpoint].to_s.empty? ||
+            config[:token_endpoint].to_s.empty? ||
+            config[:jwks_endpoint].to_s.empty?
+        end
+
+        def ensure_runtime_discovery(config, issuer, trusted_origin, fetch: nil, timeout: nil)
+          normalized = BetterAuth::Plugins.normalize_hash(config || {})
+          return config unless needs_runtime_discovery?(normalized)
+
+          discovered = discover_oidc_config(
+            issuer: issuer,
+            existing_config: normalized,
+            trusted_origin: trusted_origin,
+            fetch: fetch,
+            timeout: timeout
+          )
+          normalized.merge(
+            authorization_endpoint: discovered[:authorization_endpoint],
+            token_endpoint: discovered[:token_endpoint],
+            token_endpoint_authentication: discovered[:token_endpoint_authentication],
+            user_info_endpoint: discovered[:user_info_endpoint],
+            jwks_endpoint: discovered[:jwks_endpoint]
+          ).compact
+        end
+
+        def select_token_endpoint_auth_method(document_or_config = {}, existing_method = nil)
+          return existing_method if existing_method
+
+          config = BetterAuth::Plugins.normalize_hash(document_or_config || {})
+          return config[:token_endpoint_authentication] if config[:token_endpoint_authentication]
+
+          methods = config[:token_endpoint_auth_methods_supported] || config[:methods] || []
+          return "client_secret_post" if Array(methods).include?("client_secret_post") && !Array(methods).include?("client_secret_basic")
+
+          "client_secret_basic"
+        end
+
+        def parse_http_url!(url, name, details: {})
+          uri = URI.parse(url.to_s)
+          raise URI::InvalidURIError if uri.scheme.to_s.empty? || uri.host.to_s.empty?
+          unless %w[http https].include?(uri.scheme)
+            raise DiscoveryError.new(
+              "discovery_invalid_url",
+              "The url \"#{name}\" must use the http or https supported protocols",
+              details: details.merge(protocol: "#{uri.scheme}:")
+            )
+          end
+
+          uri
+        rescue URI::InvalidURIError
+          raise DiscoveryError.new(
+            "discovery_invalid_url",
+            "The url \"#{name}\" must be valid",
+            details: details
+          )
+        end
+
+        def normalize_endpoint_url(name, endpoint, issuer)
+          raw = endpoint.to_s
+          if raw.match?(%r{\Ahttps?://}i)
+            uri = parse_http_url!(raw, name, details: {endpoint: name, url: raw})
+            return uri.to_s
+          end
+
+          issuer_uri = parse_http_url!(issuer, name, details: {endpoint: name, url: raw})
+          issuer_base = issuer_uri.to_s.sub(%r{/+\z}, "")
+          endpoint_path = raw.sub(%r{\A/+}, "")
+          normalized = "#{issuer_base}/#{endpoint_path}"
+          parse_http_url!(normalized, name, details: {endpoint: name, url: normalized}).to_s
+        end
+
+        def parse_discovery_fetch_response(response)
+          if response.respond_to?(:code) && response.respond_to?(:body)
+            status = response.code.to_i
+            body = response.body
+            return parse_discovery_body(body) if status.between?(200, 299)
+
+            raise_discovery_http_error(status, response.message.to_s)
+          end
+
+          normalized = response.is_a?(Hash) ? BetterAuth::Plugins.normalize_hash(response) : {data: response}
+          error = normalized[:error]
+          if error
+            error_hash = BetterAuth::Plugins.normalize_hash(error)
+            raise_discovery_http_error(error_hash[:status].to_i, error_hash[:message].to_s)
+          end
+
+          data = normalized.key?(:data) ? normalized[:data] : normalized
+          parse_discovery_body(data)
+        end
+
+        def parse_discovery_body(data)
+          raise DiscoveryError.new("discovery_invalid_json", "OIDC discovery response was empty") if data.nil?
+          return BetterAuth::Plugins.normalize_hash(data) if data.is_a?(Hash)
+
+          parsed = JSON.parse(data.to_s)
+          raise JSON::ParserError if !parsed.is_a?(Hash)
+
+          BetterAuth::Plugins.normalize_hash(parsed)
+        rescue JSON::ParserError
+          raise DiscoveryError.new(
+            "discovery_invalid_json",
+            "OIDC discovery response was not valid JSON",
+            details: {bodyPreview: data.to_s[0, 200]}
+          )
+        end
+
+        def raise_discovery_http_error(status, message)
+          case status
+          when 404
+            raise DiscoveryError.new("discovery_not_found", "OIDC discovery endpoint was not found", details: {status: status, message: message})
+          when 408
+            raise DiscoveryError.new("discovery_timeout", "OIDC discovery request timed out", details: {status: status, message: message})
+          else
+            raise DiscoveryError.new("discovery_unexpected_error", "OIDC discovery request failed", details: {status: status, message: message})
+          end
+        end
+      end
+    end
+  end
+end

data/lib/better_auth/sso/oidc/errors.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module SSO
+    module OIDC
+      class DiscoveryError < StandardError
+        attr_reader :code, :details
+
+        def initialize(code, message, details: {})
+          @code = code
+          @details = details
+          super(message)
+        end
+      end
+
+      module Errors
+        module_function
+
+        def api_error(error)
+          return error if error.is_a?(APIError)
+
+          APIError.new("BAD_REQUEST", message: error.message)
+        end
+      end
+    end
+  end
+end

data/lib/better_auth/sso/oidc/types.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module SSO
+    module OIDC
+      module Types
+        DISCOVERY_ERROR_CODES = %w[
+          discovery_timeout
+          discovery_not_found
+          discovery_invalid_json
+          discovery_invalid_url
+          discovery_untrusted_origin
+          issuer_mismatch
+          discovery_incomplete
+          unsupported_token_auth_method
+          discovery_unexpected_error
+        ].freeze
+
+        REQUIRED_DISCOVERY_FIELDS = Discovery::REQUIRED_DISCOVERY_FIELDS
+
+        module_function
+
+        def discovery_error_code?(value)
+          DISCOVERY_ERROR_CODES.include?(value.to_s)
+        end
+      end
+    end
+  end
+end

data/lib/better_auth/sso/oidc.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "oidc/discovery"
+require_relative "oidc/errors"
+
+module BetterAuth
+  module SSO
+    module OIDC
+      module_function
+
+      def discover_config(**kwargs)
+        Discovery.discover_oidc_config(**kwargs)
+      end
+
+      def needs_runtime_discovery?(oidc_config)
+        Discovery.needs_runtime_discovery?(oidc_config)
+      end
+    end
+  end
+end

data/lib/better_auth/sso/plugin/oidc_core.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module Plugins
+    SSO_DEFAULT_OIDC_HTTP_TIMEOUT = 10
+    SSO_DEFAULT_OIDC_HTTP_MAX_BODY_SIZE = 1024 * 1024
+    SSO_OIDC_PKCE_VERIFIER_KEY_PREFIX = "oidc-pkce-verifier:"
+  end
+end

data/lib/better_auth/sso/plugin/oidc_discovery.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module Plugins
+    module_function
+
+    def sso_discover_oidc_config(issuer:, fetch: nil, existing_config: nil, discovery_endpoint: nil, trusted_origin: nil, timeout: nil)
+      wrapped_fetch = sso_oidc_discovery_fetcher(fetch)
+      BetterAuth::SSO::OIDC::Discovery.discover_oidc_config(
+        issuer: issuer,
+        fetch: wrapped_fetch,
+        existing_config: existing_config,
+        discovery_endpoint: discovery_endpoint,
+        trusted_origin: trusted_origin,
+        timeout: timeout || SSO_DEFAULT_OIDC_HTTP_TIMEOUT
+      )
+    rescue BetterAuth::SSO::OIDC::DiscoveryError => error
+      raise BetterAuth::SSO::OIDC::Errors.api_error(error)
+    end
+
+    def sso_oidc_discovery_fetcher(fetch)
+      return nil unless fetch
+
+      ->(url, timeout: nil) do
+        accepts_keywords = fetch.parameters.any? { |kind, name| kind == :keyrest || (kind == :key && name == :timeout) }
+        accepts_keywords ? fetch.call(url, timeout: timeout) : fetch.call(url)
+      end
+    end
+
+    def sso_normalize_discovery_url(value, issuer, trusted_origin)
+      BetterAuth::SSO::OIDC::Discovery.normalize_url("url", value, issuer, trusted_origin)
+    rescue BetterAuth::SSO::OIDC::DiscoveryError => error
+      raise BetterAuth::SSO::OIDC::Errors.api_error(error)
+    end
+  end
+end

data/lib/better_auth/sso/plugin/oidc_runtime.rb

@@ -0,0 +1,502 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module Plugins
+    module_function
+
+    def sso_verify_state(value, secret)
+      BetterAuth::Crypto.verify_jwt(value.to_s, secret)
+    rescue
+      nil
+    end
+
+    def sso_oidc_authorization_url(provider, ctx, state, plugin_config = {}, body = {})
+      config = sso_provider_config_hash(provider["oidcConfig"])
+      endpoint = config[:authorization_endpoint] || config[:authorization_url]
+      raise APIError.new("BAD_REQUEST", message: "Invalid OIDC configuration. Authorization URL not found.") if endpoint.to_s.empty?
+
+      scopes = Array(body[:scopes] || config[:scopes] || config[:scope] || ["openid", "email", "profile", "offline_access"])
+      query = {
+        client_id: config[:client_id],
+        response_type: "code",
+        redirect_uri: sso_oidc_redirect_uri(ctx.context, provider.fetch("providerId")),
+        scope: scopes.join(" "),
+        state: state
+      }.compact
+      decoded_state = sso_decode_state(state, ctx.context.secret)
+      nonce = decoded_state&.fetch("nonce", nil)
+      query[:nonce] = nonce if nonce && !nonce.to_s.empty?
+      login_hint = body[:login_hint] || body[:email]
+      query[:login_hint] = login_hint if login_hint
+      code_challenge = decoded_state&.fetch("codeChallenge", nil)
+      if code_challenge
+        query[:code_challenge] = code_challenge
+        query[:code_challenge_method] = "S256"
+      end
+      "#{endpoint}?#{URI.encode_www_form(query)}"
+    end
+
+    def sso_saml_authorization_url(provider, relay_state, ctx = nil, config = {})
+      auth_request_url = config.dig(:saml, :auth_request_url)
+      if auth_request_url.respond_to?(:call)
+        return auth_request_url.call(provider: provider, relay_state: relay_state, context: ctx)
+      end
+
+      config = sso_provider_config_hash(provider["samlConfig"])
+      metadata = sso_saml_idp_metadata(config)
+      entry_point = config[:entry_point] || normalize_hash(sso_saml_preferred_service(metadata[:single_sign_on_service]) || {})[:location]
+      query = {
+        SAMLRequest: Base64.strict_encode64(JSON.generate({providerId: provider.fetch("providerId")})),
+        RelayState: relay_state
+      }
+      "#{entry_point}?#{URI.encode_www_form(query)}"
+    end
+
+    def sso_store_saml_authn_request(ctx, provider, url, config)
+      return if config.dig(:saml, :enable_in_response_to_validation) == false
+
+      request_id = sso_extract_saml_request_id(url)
+      return if request_id.to_s.empty?
+
+      ttl_ms = (config.dig(:saml, :request_ttl) || SSO_DEFAULT_AUTHN_REQUEST_TTL_MS).to_i
+      now_ms = (Time.now.to_f * 1000).to_i
+      expires_at_ms = now_ms + ttl_ms
+      record = {
+        id: request_id,
+        providerId: provider.fetch("providerId"),
+        createdAt: now_ms,
+        expiresAt: expires_at_ms
+      }
+      ctx.context.internal_adapter.create_verification_value(
+        identifier: "#{SSO_SAML_AUTHN_REQUEST_KEY_PREFIX}#{request_id}",
+        value: JSON.generate(record),
+        expiresAt: Time.at(expires_at_ms / 1000.0)
+      )
+    end
+
+    def sso_extract_saml_request_id(url)
+      query = URI.decode_www_form(URI.parse(url.to_s).query.to_s).to_h
+      encoded = query["SAMLRequest"]
+      return nil if encoded.to_s.empty?
+
+      xml = Zlib::Inflate.new(-Zlib::MAX_WBITS).inflate(Base64.decode64(encoded))
+      xml[/\bID=['"]([^'"]+)['"]/, 1]
+    rescue
+      nil
+    end
+
+    def sso_validate_saml_in_response_to(ctx, config, provider, raw_response, state)
+      return nil if config.dig(:saml, :enable_in_response_to_validation) == false
+
+      in_response_to = sso_extract_saml_in_response_to(raw_response)
+      if in_response_to && !in_response_to.empty?
+        identifier = "#{SSO_SAML_AUTHN_REQUEST_KEY_PREFIX}#{in_response_to}"
+        verification = ctx.context.internal_adapter.find_verification_value(identifier)
+        record = sso_parse_saml_authn_request_record(verification&.fetch("value", nil))
+        if !record || record["expiresAt"].to_i < (Time.now.to_f * 1000).to_i
+          return sso_redirect(ctx, sso_append_error(state["callbackURL"] || "/", "invalid_saml_response", "Unknown or expired request ID"))
+        end
+
+        if record["providerId"] != provider.fetch("providerId")
+          ctx.context.internal_adapter.delete_verification_by_identifier(identifier)
+          return sso_redirect(ctx, sso_append_error(state["callbackURL"] || "/", "invalid_saml_response", "Provider mismatch"))
+        end
+
+        return {identifier: identifier}
+      elsif config.dig(:saml, :allow_idp_initiated) == false
+        return sso_redirect(ctx, sso_append_error(state["callbackURL"] || "/", "unsolicited_response", "IdP-initiated SSO not allowed"))
+      end
+
+      nil
+    end
+
+    def sso_consume_saml_in_response_to(ctx, result)
+      identifier = result.is_a?(Hash) ? result[:identifier] : nil
+      ctx.context.internal_adapter.delete_verification_by_identifier(identifier) unless identifier.to_s.empty?
+    end
+
+    def sso_parse_saml_authn_request_record(value)
+      JSON.parse(value.to_s)
+    rescue
+      nil
+    end
+
+    def sso_saml_assertion_replay_expires_at(assertion, config = {})
+      timestamp = sso_saml_timestamp_conditions(assertion)[:not_on_or_after]
+      parsed = Time.parse(timestamp.to_s) if timestamp
+      clock_skew_seconds = ((config.dig(:saml, :clock_skew) || SSO_DEFAULT_CLOCK_SKEW_MS).to_f / 1000.0)
+      return parsed + clock_skew_seconds if parsed && parsed + clock_skew_seconds > Time.now
+
+      ttl_ms = (config.dig(:saml, :assertion_ttl) || SSO_DEFAULT_ASSERTION_TTL_MS).to_i
+      Time.now + (ttl_ms / 1000.0)
+    rescue
+      Time.now + (SSO_DEFAULT_ASSERTION_TTL_MS / 1000.0)
+    end
+
+    def sso_extract_saml_in_response_to(raw_response)
+      xml = Base64.decode64(raw_response.to_s.gsub(/\s+/, ""))
+      xml[/\bInResponseTo=['"]([^'"]+)['"]/, 1]
+    rescue
+      nil
+    end
+
+    def sso_select_provider(ctx, body, config = {})
+      provider_id = body[:provider_id].to_s
+      issuer = body[:issuer].to_s
+      organization_slug = body[:organization_slug].to_s
+      domain = (body[:domain] || body[:email].to_s.split("@").last).to_s.downcase
+      if config[:default_sso]
+        provider = sso_default_provider(config, provider_id: provider_id, domain: domain)
+        return provider if provider
+      end
+
+      providers = ctx.context.adapter.find_many(model: "ssoProvider")
+      provider = if !provider_id.empty?
+        providers.find { |entry| entry["providerId"] == provider_id }
+      elsif !issuer.empty?
+        providers.find { |entry| entry["issuer"] == issuer }
+      elsif !organization_slug.empty?
+        organization = ctx.context.adapter.find_one(model: "organization", where: [{field: "slug", value: organization_slug}])
+        providers.find { |entry| entry["organizationId"] == organization&.fetch("id", nil) }
+      elsif !domain.empty?
+        providers.find { |entry| entry["domain"].to_s.downcase == domain } ||
+          providers.find { |entry| sso_email_domain_matches?(domain, entry["domain"]) }
+      end
+      raise APIError.new("NOT_FOUND", message: SSO_ERROR_CODES.fetch("PROVIDER_NOT_FOUND")) unless provider
+
+      provider
+    end
+
+    def sso_callback_provider(ctx, config, provider_id)
+      if config[:default_sso]
+        provider = sso_default_provider(config, provider_id: provider_id.to_s, domain: "")
+        return provider if provider
+      end
+
+      ctx.context.adapter.find_one(model: "ssoProvider", where: [{field: "providerId", value: provider_id.to_s}])
+    end
+
+    def sso_oidc_tokens(ctx, provider, oidc_config, state, plugin_config, raw_state: nil)
+      code_verifier = sso_oidc_code_verifier(ctx, raw_state || state["state"] || state[:state])
+      token_callback = oidc_config[:get_token]
+      if token_callback.respond_to?(:call)
+        return normalize_hash(token_callback.call(
+          code: ctx.query[:code] || ctx.query["code"],
+          codeVerifier: code_verifier,
+          redirectURI: sso_oidc_redirect_uri(ctx.context, provider.fetch("providerId")),
+          provider: provider,
+          context: ctx
+        ))
+      end
+
+      token_endpoint = oidc_config[:token_endpoint]
+      return nil if token_endpoint.to_s.empty?
+
+      sso_exchange_oidc_code(
+        token_endpoint: token_endpoint,
+        code: ctx.query[:code] || ctx.query["code"],
+        code_verifier: code_verifier,
+        redirect_uri: sso_oidc_redirect_uri(ctx.context, provider.fetch("providerId")),
+        client_id: oidc_config[:client_id],
+        client_secret: oidc_config[:client_secret],
+        authentication: oidc_config[:token_endpoint_authentication],
+        timeout: plugin_config[:oidc_http_timeout],
+        max_body_size: plugin_config[:oidc_http_max_body_size]
+      )
+    rescue
+      nil
+    end
+
+    def sso_exchange_oidc_code(token_endpoint:, code:, code_verifier:, redirect_uri:, client_id:, client_secret:, authentication:, timeout: nil, max_body_size: nil)
+      uri = URI(token_endpoint.to_s)
+      request = Net::HTTP::Post.new(uri)
+      form = {
+        grant_type: "authorization_code",
+        code: code,
+        redirect_uri: redirect_uri,
+        client_id: client_id,
+        code_verifier: code_verifier
+      }.compact
+      if authentication.to_s == "client_secret_post"
+        form[:client_secret] = client_secret
+      elsif client_secret.to_s != ""
+        request.basic_auth(client_id.to_s, client_secret.to_s)
+      end
+      request.set_form_data(form)
+      response = Net::HTTP.start(
+        uri.hostname,
+        uri.port,
+        use_ssl: uri.scheme == "https",
+        open_timeout: sso_oidc_http_timeout(timeout),
+        read_timeout: sso_oidc_http_timeout(timeout)
+      ) { |http| http.request(request) }
+      return nil unless response.is_a?(Net::HTTPSuccess)
+      return nil if response.body.to_s.bytesize > sso_oidc_http_max_body_size(max_body_size)
+
+      normalize_hash(JSON.parse(response.body))
+    end
+
+    def sso_oidc_user_info(ctx, oidc_config, tokens, plugin_config, expected_nonce: nil)
+      user_callback = oidc_config[:get_user_info]
+      raw = if user_callback.respond_to?(:call)
+        user_callback.call(tokens)
+      elsif oidc_config[:user_info_endpoint]
+        sso_fetch_oidc_user_info(oidc_config[:user_info_endpoint], tokens[:access_token], timeout: plugin_config[:oidc_http_timeout], max_body_size: plugin_config[:oidc_http_max_body_size])
+      elsif tokens[:id_token]
+        return {_sso_error: "jwks_endpoint_not_found"} if oidc_config[:jwks_endpoint].to_s.empty?
+
+        sso_validate_oidc_id_token(
+          tokens[:id_token],
+          jwks_endpoint: oidc_config[:jwks_endpoint],
+          audience: oidc_config[:client_id],
+          issuer: oidc_config[:issuer],
+          fetch: plugin_config[:oidc_jwks_fetch],
+          expected_nonce: expected_nonce
+        ) || {_sso_error: "token_not_verified"}
+      else
+        {}
+      end
+      raw = normalize_hash(raw || {})
+      return raw if raw[:_sso_error]
+
+      mapping = normalize_hash(oidc_config[:mapping] || {})
+      extra_fields = normalize_hash(mapping[:extra_fields] || {}).each_with_object({}) do |(target, source), result|
+        result[target] = raw[normalize_key(source)] || raw[source.to_s]
+      end
+      extra_fields.merge(
+        id: raw[normalize_key(mapping[:id] || "sub")] || raw[:id],
+        email: raw[normalize_key(mapping[:email] || "email")],
+        email_verified: plugin_config[:trust_email_verified] ? raw[normalize_key(mapping[:email_verified] || "email_verified")] : false,
+        name: raw[normalize_key(mapping[:name] || "name")],
+        image: raw[normalize_key(mapping[:image] || "picture")]
+      )
+    end
+
+    def sso_fetch_oidc_user_info(endpoint, access_token, timeout: nil, max_body_size: nil)
+      uri = URI(endpoint.to_s)
+      request = Net::HTTP::Get.new(uri)
+      request["authorization"] = "Bearer #{access_token}"
+      response = Net::HTTP.start(
+        uri.hostname,
+        uri.port,
+        use_ssl: uri.scheme == "https",
+        open_timeout: sso_oidc_http_timeout(timeout),
+        read_timeout: sso_oidc_http_timeout(timeout)
+      ) { |http| http.request(request) }
+      return {} unless response.is_a?(Net::HTTPSuccess)
+      return {} if response.body.to_s.bytesize > sso_oidc_http_max_body_size(max_body_size)
+
+      JSON.parse(response.body)
+    rescue
+      {}
+    end
+
+    def sso_validate_oidc_id_token(token, jwks_endpoint:, audience:, issuer:, fetch: nil, expected_nonce: nil)
+      jwks = sso_fetch_oidc_jwks(jwks_endpoint, fetch: fetch)
+      payload, = ::JWT.decode(
+        token.to_s,
+        nil,
+        true,
+        algorithms: %w[RS256 RS384 RS512 ES256 ES384 ES512],
+        jwks: jwks,
+        aud: audience,
+        verify_aud: true,
+        iss: issuer,
+        verify_iss: true
+      )
+      if expected_nonce && !expected_nonce.to_s.empty?
+        token_nonce = payload["nonce"] || payload[:nonce]
+        return nil if token_nonce.to_s.empty?
+        return nil unless BetterAuth::Crypto.constant_time_compare(token_nonce.to_s, expected_nonce.to_s)
+      end
+      payload
+    rescue
+      nil
+    end
+
+    def sso_fetch_oidc_jwks(jwks_endpoint, fetch: nil)
+      if fetch.respond_to?(:call)
+        return normalize_hash(fetch.call(jwks_endpoint))
+      end
+
+      uri = URI(jwks_endpoint.to_s)
+      response = Net::HTTP.start(
+        uri.hostname,
+        uri.port,
+        use_ssl: uri.scheme == "https",
+        open_timeout: SSO_DEFAULT_OIDC_HTTP_TIMEOUT,
+        read_timeout: SSO_DEFAULT_OIDC_HTTP_TIMEOUT
+      ) { |http| http.get(uri.request_uri) }
+      return {} unless response.is_a?(Net::HTTPSuccess)
+      return {} if response.body.to_s.bytesize > SSO_DEFAULT_OIDC_HTTP_MAX_BODY_SIZE
+
+      normalize_hash(JSON.parse(response.body))
+    rescue
+      {}
+    end
+
+    def sso_decode_jwt_payload(token)
+      payload = token.to_s.split(".")[1]
+      return {} unless payload
+
+      JSON.parse(Base64.urlsafe_decode64(payload.ljust((payload.length + 3) & ~3, "=")))
+    rescue
+      {}
+    end
+
+    def sso_append_error(url, error, description = nil)
+      separator = url.to_s.include?("?") ? "&" : "?"
+      query = {error: error, error_description: description}.compact
+      "#{url}#{separator}#{URI.encode_www_form(query)}"
+    end
+
+    def sso_default_provider(config, provider_id:, domain:)
+      Array(config[:default_sso]).each do |raw_provider|
+        default_provider = normalize_hash(raw_provider)
+        next if !provider_id.empty? && default_provider[:provider_id].to_s != provider_id
+        next if provider_id.empty? && default_provider[:domain].to_s.downcase != domain
+
+        oidc_config = default_provider[:oidc_config] ? sso_storage_config(default_provider[:oidc_config]) : nil
+        saml_config = default_provider[:saml_config] ? sso_storage_config(default_provider[:saml_config]) : nil
+        return {
+          "issuer" => default_provider[:issuer] || default_provider.dig(:oidc_config, :issuer) || default_provider.dig(:saml_config, :issuer) || "",
+          "providerId" => default_provider.fetch(:provider_id),
+          "userId" => "default",
+          "domain" => default_provider[:domain],
+          "domainVerified" => true,
+          "oidcConfig" => oidc_config,
+          "samlConfig" => saml_config
+        }.compact
+      end
+      nil
+    end
+
+    def sso_oidc_pkce_state(provider)
+      return {} unless sso_provider_config_hash(provider["oidcConfig"])[:pkce]
+
+      verifier = BetterAuth::Crypto.random_string(128)
+      {
+        codeVerifier: verifier,
+        codeChallenge: sso_base64_urlsafe(OpenSSL::Digest::SHA256.digest(verifier))
+      }
+    end
+
+    def sso_store_oidc_pkce_verifier(ctx, state, verifier)
+      ctx.context.internal_adapter.create_verification_value(
+        identifier: "#{SSO_OIDC_PKCE_VERIFIER_KEY_PREFIX}#{state}",
+        value: verifier,
+        expiresAt: Time.now + 600
+      )
+    end
+
+    def sso_oidc_code_verifier(ctx, state)
+      return nil if state.to_s.empty?
+
+      identifier = "#{SSO_OIDC_PKCE_VERIFIER_KEY_PREFIX}#{state}"
+      verification = ctx.context.internal_adapter.find_verification_value(identifier)
+      ctx.context.internal_adapter.delete_verification_by_identifier(identifier) if verification
+      verification&.fetch("value", nil)
+    end
+
+    def sso_oidc_http_timeout(value)
+      timeout = value || SSO_DEFAULT_OIDC_HTTP_TIMEOUT
+      timeout.to_f.positive? ? timeout.to_f : SSO_DEFAULT_OIDC_HTTP_TIMEOUT
+    end
+
+    def sso_oidc_http_max_body_size(value)
+      size = value || SSO_DEFAULT_OIDC_HTTP_MAX_BODY_SIZE
+      size.to_i.positive? ? size.to_i : SSO_DEFAULT_OIDC_HTTP_MAX_BODY_SIZE
+    end
+
+    def sso_decode_state(state, secret)
+      BetterAuth::Crypto.verify_jwt(state.to_s, secret)
+    rescue
+      nil
+    end
+
+    def sso_base64_urlsafe(value)
+      Base64.strict_encode64(value).tr("+/", "-_").delete("=")
+    end
+
+    def sso_storage_config(config)
+      normalize_hash(config || {}).each_with_object({}) do |(key, value), result|
+        result[Schema.storage_key(key)] = value unless value.respond_to?(:call)
+      end
+    end
+
+    def sso_provider_limit(user, config)
+      limit = config[:providers_limit]
+      limit = 10 if limit.nil?
+      limit.respond_to?(:call) ? limit.call(user) : limit
+    end
+
+    def sso_validate_url!(value, message)
+      uri = URI(value.to_s)
+      unless uri.is_a?(URI::HTTP) && !uri.host.to_s.empty?
+        raise APIError.new("BAD_REQUEST", message: message)
+      end
+    rescue URI::InvalidURIError
+      raise APIError.new("BAD_REQUEST", message: message)
+    end
+
+    def sso_validate_organization_membership!(ctx, user_id, organization_id)
+      member = ctx.context.adapter.find_one(
+        model: "member",
+        where: [{field: "userId", value: user_id}, {field: "organizationId", value: organization_id}]
+      )
+      raise APIError.new("BAD_REQUEST", message: "You are not a member of the organization") unless member
+    end
+
+    def sso_hydrate_oidc_config(issuer, oidc_config, ctx)
+      existing = oidc_config.merge(issuer: issuer)
+      discovered = sso_discover_oidc_config(
+        issuer: issuer,
+        existing_config: existing,
+        fetch: ctx.context.options.plugins.find { |plugin| plugin.id == "sso" }&.options&.fetch(:oidc_discovery_fetch, nil),
+        trusted_origin: ->(url) { ctx.context.trusted_origin?(url, allow_relative_paths: false) },
+        timeout: ctx.context.options.plugins.find { |plugin| plugin.id == "sso" }&.options&.fetch(:oidc_http_timeout, nil)
+      )
+      existing.merge(discovered)
+    end
+
+    def sso_oidc_needs_runtime_discovery?(oidc_config)
+      config = normalize_hash(oidc_config || {})
+      config[:authorization_endpoint].to_s.empty? ||
+        config[:token_endpoint].to_s.empty?
+    end
+
+    def sso_ensure_runtime_oidc_provider(ctx, provider, plugin_config, require_jwks: false)
+      oidc_config = sso_provider_config_hash(provider["oidcConfig"])
+      needs_discovery = sso_oidc_needs_runtime_discovery?(oidc_config) || (require_jwks && oidc_config[:jwks_endpoint].to_s.empty?)
+      return provider if !needs_discovery
+
+      discovered = sso_discover_oidc_config(
+        issuer: provider.fetch("issuer"),
+        existing_config: oidc_config.merge(issuer: provider.fetch("issuer")),
+        fetch: plugin_config[:oidc_discovery_fetch],
+        trusted_origin: ->(url) { ctx.context.trusted_origin?(url, allow_relative_paths: false) },
+        timeout: plugin_config[:oidc_http_timeout]
+      )
+      provider.merge("oidcConfig" => oidc_config.merge(discovered))
+    end
+
+    def sso_validate_oidc_endpoint_origins!(ctx, oidc_config)
+      return unless sso_oidc_trusted_origin_enforced?(ctx)
+
+      config = normalize_hash(oidc_config || {})
+      %i[authorization_endpoint token_endpoint jwks_endpoint user_info_endpoint discovery_endpoint].each do |field|
+        url = config[field]
+        next if url.to_s.empty?
+
+        sso_validate_url!(url, "OIDC #{Schema.storage_key(field)} must be a valid URL")
+        next if ctx.context.trusted_origin?(url.to_s, allow_relative_paths: false)
+
+        raise APIError.new("BAD_REQUEST", message: "OIDC #{Schema.storage_key(field)} is not trusted")
+      end
+    end
+
+    def sso_oidc_trusted_origin_enforced?(ctx)
+      Array(ctx.context.trusted_origins).map(&:to_s).uniq.length > 1
+    end
+  end
+end

metadata

@@ -0,0 +1,182 @@
+--- !ruby/object:Gem::Specification
+name: better_auth-oidc
+version: !ruby/object:Gem::Version
+  version: 0.10.0
+platform: ruby
+authors:
+- Sebastian Sala
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: better_auth
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: jwt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.6'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.6'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.5'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.2'
+- !ruby/object:Gem::Dependency
+  name: standardrb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: OpenID Connect relying party primitives and plugin extensions for Better
+  Auth Ruby enterprise SSO. Pair with better_auth-sso for provider management or require
+  directly for OIDC-only integrations.
+email:
+- sebastian.sala.tech@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- README.md
+- lib/better_auth/oidc.rb
+- lib/better_auth/oidc/version.rb
+- lib/better_auth/plugins/oidc.rb
+- lib/better_auth/sso/oidc.rb
+- lib/better_auth/sso/oidc/discovery.rb
+- lib/better_auth/sso/oidc/errors.rb
+- lib/better_auth/sso/oidc/types.rb
+- lib/better_auth/sso/plugin/oidc_core.rb
+- lib/better_auth/sso/plugin/oidc_discovery.rb
+- lib/better_auth/sso/plugin/oidc_runtime.rb
+homepage: https://github.com/sebasxsala/better-auth-rb
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/sebasxsala/better-auth-rb
+  source_code_uri: https://github.com/sebasxsala/better-auth-rb
+  changelog_uri: https://github.com/sebasxsala/better-auth-rb/blob/main/packages/better_auth-oidc/CHANGELOG.md
+  bug_tracker_uri: https://github.com/sebasxsala/better-auth-rb/issues
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Enterprise OIDC RP support for Better Auth Ruby SSO
+test_files: []