better_auth-saml 0.10.0

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

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module Plugins
+    module_function
+
+    def sso_handle_saml_response(ctx, config = {})
+      provider = sso_find_saml_provider!(ctx, sso_fetch(ctx.params, :provider_id), config)
+      relay_state = sso_fetch(ctx.body, :relay_state) || sso_fetch(ctx.query, :relay_state)
+      state = sso_parse_saml_relay_state(ctx, relay_state) || {}
+      raw_response = sso_fetch(ctx.body, :saml_response) || sso_fetch(ctx.query, :saml_response)
+      if ctx.method == "GET" && raw_response.to_s.empty?
+        session = Routes.current_session(ctx, allow_nil: true)
+        unless session
+          return sso_redirect(ctx, sso_append_error("#{ctx.context.base_url}/error", "invalid_request"))
+        end
+
+        return sso_redirect(ctx, sso_safe_saml_callback_url(ctx, relay_state || sso_saml_callback_url(provider) || "/", provider.fetch("providerId")))
+      end
+      max_response_size = config.dig(:saml, :max_response_size) || SSO_DEFAULT_MAX_SAML_RESPONSE_SIZE
+      if raw_response.to_s.bytesize > max_response_size
+        raise APIError.new("BAD_REQUEST", message: "SAML response exceeds maximum allowed size (#{max_response_size} bytes)")
+      end
+      in_response_to_result = sso_validate_saml_in_response_to(ctx, config, provider, raw_response, state)
+      return in_response_to_result if in_response_to_result.is_a?(Array)
+
+      assertion = sso_parse_saml_response(raw_response, config, provider, ctx)
+      assertion[:email_verified] = false unless config[:trust_email_verified]
+      sso_validate_saml_timestamp!(sso_saml_timestamp_conditions(assertion), config)
+      sso_validate_saml_response!(config, assertion, provider, ctx)
+      sso_consume_saml_in_response_to(ctx, in_response_to_result)
+      assertion_id = assertion[:id] || assertion["id"]
+      unless assertion_id.to_s.empty?
+        replay_key = "#{SSO_SAML_USED_ASSERTION_KEY_PREFIX}#{assertion_id}"
+        if ctx.context.internal_adapter.find_verification_value(replay_key)
+          callback_url = sso_safe_saml_callback_url(ctx, state["callbackURL"] || sso_saml_callback_url(provider) || "/", provider.fetch("providerId"))
+          return sso_redirect(ctx, sso_append_error(callback_url, "replay_detected", "SAML assertion has already been used"))
+        end
+        ctx.context.internal_adapter.create_verification_value(identifier: replay_key, value: "used", expiresAt: sso_saml_assertion_replay_expires_at(assertion, config))
+      end
+
+      callback_url = sso_safe_saml_callback_url(ctx, state["callbackURL"] || sso_saml_callback_url(provider) || "/", provider.fetch("providerId"))
+      email = (assertion[:email] || assertion["email"]).to_s.downcase
+      if config[:disable_implicit_sign_up] && !state["requestSignUp"] && !ctx.context.internal_adapter.find_user_by_email(email)
+        return sso_redirect(ctx, sso_append_error(callback_url, "signup disabled"))
+      end
+
+      result = sso_find_or_create_user_result(ctx, provider, assertion, config)
+      return sso_redirect(ctx, sso_append_error(callback_url, result.fetch(:error))) if result[:error]
+
+      user = result.fetch(:user)
+      if config[:provision_user].respond_to?(:call) && (result.fetch(:created) || config[:provision_user_on_every_login])
+        config[:provision_user].call(user: user, userInfo: assertion, provider: provider)
+      end
+      session = ctx.context.internal_adapter.create_session(user.fetch("id"))
+      sso_store_saml_session(ctx, provider, assertion, session) if config.dig(:saml, :enable_single_logout)
+      Cookies.set_session_cookie(ctx, {session: session, user: user})
+      sso_redirect(ctx, callback_url)
+    end
+
+    def sso_find_or_create_user(ctx, provider, user_info, config = {})
+      sso_find_or_create_user_result(ctx, provider, user_info, config).fetch(:user)
+    end
+
+    def sso_find_or_create_user_result(ctx, provider, user_info, config = {})
+      user_info = normalize_hash(user_info)
+      email = user_info[:email].to_s.downcase
+      account_id = (user_info[:id] || user_info["id"]).to_s
+      provider_id = provider.fetch("providerId")
+      storage_provider_id = provider["samlConfig"] ? provider_id : "sso:#{provider_id}"
+      existing_account = account_id.empty? ? nil : (
+        ctx.context.internal_adapter.find_account_by_provider_id(account_id, provider_id) ||
+          ctx.context.internal_adapter.find_account_by_provider_id(account_id, "sso:#{provider_id}")
+      )
+      if existing_account
+        user = ctx.context.internal_adapter.find_user_by_id(existing_account.fetch("userId"))
+        created = false
+      elsif (found = ctx.context.internal_adapter.find_user_by_email(email, include_accounts: true))
+        already_linked_provider = Array(found[:accounts]).any? do |account|
+          [provider_id, "sso:#{provider_id}"].include?(account["providerId"])
+        end
+        if provider["samlConfig"]
+          return {error: "account_not_linked"} unless already_linked_provider || sso_saml_trusted_provider?(ctx, provider, email)
+        elsif !already_linked_provider && !sso_oidc_trusted_provider?(ctx, provider, email)
+          return {error: "account_not_linked"}
+        end
+
+        user = found[:user]
+        unless account_id.empty?
+          ctx.context.internal_adapter.create_account(
+            accountId: account_id,
+            providerId: storage_provider_id,
+            userId: user.fetch("id")
+          )
+        end
+        oidc_config = sso_provider_config_hash(provider["oidcConfig"])
+        if oidc_config[:override_user_info] || config[:default_override_user_info]
+          update = {}
+          update[:name] = user_info[:name] if user_info.key?(:name)
+          update[:image] = user_info[:image] if user_info.key?(:image)
+          update[:emailVerified] = !!user_info[:email_verified] if user_info.key?(:email_verified)
+          user = ctx.context.internal_adapter.update_user(user.fetch("id"), update) if update.any?
+        end
+        created = false
+      else
+        created = ctx.context.internal_adapter.create_user(
+          email: email,
+          name: user_info[:name] || email,
+          emailVerified: user_info.key?(:email_verified) ? user_info[:email_verified] : false,
+          image: user_info[:image]
+        )
+        ctx.context.internal_adapter.create_account(
+          accountId: account_id.empty? ? created.fetch("id") : account_id,
+          providerId: storage_provider_id,
+          userId: created.fetch("id")
+        )
+        user = created
+        created = true
+      end
+      sso_assign_organization_membership(ctx, provider, user, config)
+      {user: user, created: created}
+    end
+
+    def sso_saml_trusted_provider?(ctx, provider, email)
+      provider_id = provider.fetch("providerId")
+      linking = ctx.context.options.account[:account_linking] || {}
+      return false if linking[:enabled] == false
+
+      trusted = Array(linking[:trusted_providers]).map(&:to_s).include?(provider_id.to_s)
+      trusted || (provider["domainVerified"] && sso_email_domain_matches?(email, provider["domain"]))
+    end
+
+    def sso_oidc_trusted_provider?(ctx, provider, email)
+      provider_id = provider.fetch("providerId")
+      linking = ctx.context.options.account[:account_linking] || {}
+      return false if linking[:enabled] == false
+
+      trusted_providers = Array(linking[:trusted_providers]).map(&:to_s)
+      trusted_providers.include?(provider_id.to_s) ||
+        trusted_providers.include?("sso:#{provider_id}") ||
+        (provider["domainVerified"] && sso_email_domain_matches?(email, provider["domain"]))
+    end
+
+    def sso_assign_organization_membership(ctx, provider, user, config)
+      organization_id = provider["organizationId"]
+      return if organization_id.to_s.empty?
+      return if config.dig(:organization_provisioning, :disabled)
+      return unless ctx.context.options.plugins.any? { |plugin| plugin.id == "organization" }
+      return if ctx.context.adapter.find_one(model: "member", where: [{field: "organizationId", value: organization_id}, {field: "userId", value: user.fetch("id")}])
+
+      role = if config.dig(:organization_provisioning, :get_role).respond_to?(:call)
+        config.dig(:organization_provisioning, :get_role).call(user: user, userInfo: {}, provider: provider)
+      else
+        config.dig(:organization_provisioning, :default_role) || config.dig(:organization_provisioning, :role) || "member"
+      end
+      ctx.context.adapter.create(model: "member", data: {organizationId: organization_id, userId: user.fetch("id"), role: role, createdAt: Time.now})
+    end
+
+    def sso_validate_saml_response!(config, assertion, provider, ctx)
+      validator = config.dig(:saml, :validate_response)
+      return unless validator.respond_to?(:call)
+      return if validator.call(response: assertion, provider: provider, context: ctx)
+
+      raise APIError.new("BAD_REQUEST", message: "Invalid SAML response")
+    end
+  end
+end

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

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module Plugins
+    module_function
+
+    def sso_parse_saml_response(value, config = {}, provider = nil, ctx = nil)
+      parser = config.dig(:saml, :parse_response)
+      if parser.respond_to?(:call)
+        sso_validate_single_saml_assertion!(value) if sso_base64_xml?(value)
+        parsed = parser.call(raw_response: value.to_s, provider: provider, context: ctx)
+        return normalize_hash(parsed)
+      end
+
+      JSON.parse(Base64.decode64(value.to_s), symbolize_names: true)
+    rescue APIError
+      raise APIError.new("BAD_REQUEST", message: "Invalid SAML response")
+    rescue
+      raise APIError.new("BAD_REQUEST", message: "Invalid SAML response")
+    end
+
+    def sso_validate_single_saml_assertion!(saml_response)
+      xml = Base64.decode64(saml_response.to_s)
+      raise APIError.new("BAD_REQUEST", message: "Invalid base64-encoded SAML response") unless xml.include?("<")
+
+      assertions = xml.scan(/<(?:\w+:)?Assertion(?:\s|>|\/)/).length
+      encrypted_assertions = xml.scan(/<(?:\w+:)?EncryptedAssertion(?:\s|>|\/)/).length
+      total = assertions + encrypted_assertions
+      raise APIError.new("BAD_REQUEST", message: "SAML response contains no assertions") if total.zero?
+      if total > 1
+        raise APIError.new("BAD_REQUEST", message: "SAML response contains #{total} assertions, expected exactly 1")
+      end
+
+      true
+    rescue APIError
+      raise
+    rescue
+      raise APIError.new("BAD_REQUEST", message: "Invalid base64-encoded SAML response")
+    end
+
+    def sso_validate_saml_timestamp!(conditions, config = {}, now: Time.now.utc)
+      conditions = normalize_hash(conditions || {})
+      not_before = conditions[:not_before] || conditions[:notBefore]
+      not_on_or_after = conditions[:not_on_or_after] || conditions[:notOnOrAfter]
+      if not_before.to_s.empty? && not_on_or_after.to_s.empty?
+        raise APIError.new("BAD_REQUEST", message: "SAML assertion missing required timestamp conditions") if config.dig(:saml, :require_timestamps)
+
+        return true
+      end
+
+      clock_skew_seconds = ((config.dig(:saml, :clock_skew) || SSO_DEFAULT_CLOCK_SKEW_MS).to_f / 1000.0)
+      parsed_not_before = sso_parse_saml_timestamp(not_before, "SAML assertion has invalid NotBefore timestamp") unless not_before.to_s.empty?
+      parsed_not_on_or_after = sso_parse_saml_timestamp(not_on_or_after, "SAML assertion has invalid NotOnOrAfter timestamp") unless not_on_or_after.to_s.empty?
+
+      raise APIError.new("BAD_REQUEST", message: "SAML assertion is not yet valid") if parsed_not_before && now < (parsed_not_before - clock_skew_seconds)
+      raise APIError.new("BAD_REQUEST", message: "SAML assertion has expired") if parsed_not_on_or_after && now > (parsed_not_on_or_after + clock_skew_seconds)
+
+      true
+    end
+
+    def sso_parse_saml_timestamp(value, error_message)
+      Time.parse(value.to_s).utc
+    rescue
+      raise APIError.new("BAD_REQUEST", message: error_message)
+    end
+
+    def sso_saml_timestamp_conditions(assertion)
+      assertion = normalize_hash(assertion || {})
+      conditions = normalize_hash(assertion[:conditions] || {})
+      conditions[:not_before] ||= assertion[:not_before] || assertion[:notBefore]
+      conditions[:not_on_or_after] ||= assertion[:not_on_or_after] || assertion[:notOnOrAfter]
+      conditions
+    end
+
+    def sso_base64_xml?(value)
+      Base64.decode64(value.to_s).lstrip.start_with?("<")
+    rescue
+      false
+    end
+
+    def sso_validate_saml_algorithms!(xml, options = {})
+      on_deprecated = (options[:on_deprecated] || "warn").to_s
+      signature_algorithms = xml.to_s.scan(/SignatureMethod[^>]+Algorithm=["']([^"']+)["']/).flatten.map { |algorithm| sso_normalize_saml_signature_algorithm(algorithm) }
+      digest_algorithms = xml.to_s.scan(/DigestMethod[^>]+Algorithm=["']([^"']+)["']/).flatten.map { |algorithm| sso_normalize_saml_digest_algorithm(algorithm) }
+      key_encryption_algorithms = xml.to_s.scan(/<[^\/>]*EncryptedKey\b[\s\S]*?EncryptionMethod[^>]+Algorithm=["']([^"']+)["']/).flatten
+      data_encryption_algorithms = xml.to_s.scan(/<[^\/>]*EncryptedData\b[\s\S]*?EncryptionMethod[^>]+Algorithm=["']([^"']+)["']/).flatten
+
+      sso_validate_saml_algorithm_group!(
+        signature_algorithms,
+        allowed: options[:allowed_signature_algorithms]&.map { |algorithm| sso_normalize_saml_signature_algorithm(algorithm) },
+        secure: SSO_SAML_SECURE_SIGNATURE_ALGORITHMS,
+        deprecated: ["http://www.w3.org/2000/09/xmldsig#rsa-sha1"],
+        on_deprecated: on_deprecated,
+        label: "signature"
+      )
+      sso_validate_saml_algorithm_group!(
+        digest_algorithms,
+        allowed: options[:allowed_digest_algorithms]&.map { |algorithm| sso_normalize_saml_digest_algorithm(algorithm) },
+        secure: SSO_SAML_SECURE_DIGEST_ALGORITHMS,
+        deprecated: ["http://www.w3.org/2000/09/xmldsig#sha1"],
+        on_deprecated: on_deprecated,
+        label: "digest"
+      )
+      sso_validate_saml_algorithm_group!(
+        key_encryption_algorithms,
+        allowed: options[:allowed_key_encryption_algorithms],
+        secure: SSO_SAML_SECURE_KEY_ENCRYPTION_ALGORITHMS,
+        deprecated: ["http://www.w3.org/2001/04/xmlenc#rsa-1_5"],
+        on_deprecated: on_deprecated,
+        label: "key encryption"
+      )
+      sso_validate_saml_algorithm_group!(
+        data_encryption_algorithms,
+        allowed: options[:allowed_data_encryption_algorithms],
+        secure: SSO_SAML_SECURE_DATA_ENCRYPTION_ALGORITHMS,
+        deprecated: ["http://www.w3.org/2001/04/xmlenc#tripledes-cbc"],
+        on_deprecated: on_deprecated,
+        label: "data encryption"
+      )
+
+      true
+    end
+
+    def sso_normalize_saml_signature_algorithm(algorithm)
+      SSO_SAML_SIGNATURE_ALGORITHMS.fetch(algorithm.to_s.downcase, algorithm.to_s)
+    end
+
+    def sso_normalize_saml_digest_algorithm(algorithm)
+      SSO_SAML_DIGEST_ALGORITHMS.fetch(algorithm.to_s.downcase, algorithm.to_s)
+    end
+
+    def sso_validate_saml_algorithm_group!(algorithms, allowed:, secure:, deprecated:, on_deprecated:, label:)
+      algorithms.each do |algorithm|
+        if allowed
+          next if allowed.include?(algorithm)
+
+          raise APIError.new("BAD_REQUEST", message: "SAML #{label} algorithm not in allow-list: #{algorithm}")
+        end
+
+        if deprecated.include?(algorithm)
+          raise APIError.new("BAD_REQUEST", message: "SAML response uses deprecated #{label} algorithm: #{algorithm}") if on_deprecated == "reject"
+          next
+        end
+        next if secure.include?(algorithm)
+
+        raise APIError.new("BAD_REQUEST", message: "SAML #{label} algorithm not recognized: #{algorithm}")
+      end
+    end
+
+    def sso_generate_saml_relay_state(ctx, state_data)
+      ttl_ms = 10 * 60 * 1000
+      relay_state = BetterAuth::Crypto.random_string(32)
+      now_ms = (Time.now.to_f * 1000).to_i
+      stored = state_data.each_with_object({}) { |(key, value), result| result[key.to_s] = value }.merge(
+        "codeVerifier" => BetterAuth::Crypto.random_string(128),
+        "expiresAt" => now_ms + ttl_ms
+      )
+      ctx.context.internal_adapter.create_verification_value(
+        identifier: "#{SSO_SAML_RELAY_STATE_KEY_PREFIX}#{relay_state}",
+        value: JSON.generate(stored),
+        expiresAt: Time.at((now_ms + ttl_ms) / 1000.0)
+      )
+      ctx.set_signed_cookie("relay_state", relay_state, ctx.context.secret, path: "/", max_age: ttl_ms / 1000, http_only: true, same_site: "lax")
+      relay_state
+    end
+
+    def sso_parse_saml_relay_state(ctx, relay_state)
+      state = sso_verify_state(relay_state, ctx.context.secret)
+      return state if state
+
+      verification = ctx.context.internal_adapter.find_verification_value("#{SSO_SAML_RELAY_STATE_KEY_PREFIX}#{relay_state}")
+      return nil unless verification
+      return nil unless sso_future_time?(verification.fetch("expiresAt"))
+
+      parsed = JSON.parse(verification.fetch("value"))
+      return nil if parsed["expiresAt"].to_i <= (Time.now.to_f * 1000).to_i
+
+      parsed
+    rescue
+      nil
+    end
+  end
+end

data/lib/better_auth/sso/routes/saml_pipeline.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module SSO
+    module Routes
+      module SAMLPipeline
+        module_function
+
+        def process_response(ctx, config = {})
+          BetterAuth::Plugins.sso_handle_saml_response(ctx, config)
+        end
+
+        def safe_redirect_url(ctx, url, provider_id)
+          BetterAuth::Plugins.sso_safe_slo_redirect_url(ctx, url, provider_id)
+        end
+      end
+    end
+  end
+end

data/lib/better_auth/sso/saml/algorithms.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module SSO
+    module SAML
+      module Algorithms
+        module_function
+
+        SignatureAlgorithm = BetterAuth::Plugins::SSO_SAML_SIGNATURE_ALGORITHMS.merge(
+          RSA_SHA1: "http://www.w3.org/2000/09/xmldsig#rsa-sha1",
+          RSA_SHA256: "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256",
+          RSA_SHA384: "http://www.w3.org/2001/04/xmldsig-more#rsa-sha384",
+          RSA_SHA512: "http://www.w3.org/2001/04/xmldsig-more#rsa-sha512",
+          ECDSA_SHA256: "http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha256",
+          ECDSA_SHA384: "http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha384",
+          ECDSA_SHA512: "http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha512"
+        ).freeze
+        DigestAlgorithm = BetterAuth::Plugins::SSO_SAML_DIGEST_ALGORITHMS.merge(
+          SHA1: "http://www.w3.org/2000/09/xmldsig#sha1",
+          SHA256: "http://www.w3.org/2001/04/xmlenc#sha256",
+          SHA384: "http://www.w3.org/2001/04/xmldsig-more#sha384",
+          SHA512: "http://www.w3.org/2001/04/xmlenc#sha512"
+        ).freeze
+        KEY_ENCRYPTION_ALGORITHM = {
+          RSA_1_5: "http://www.w3.org/2001/04/xmlenc#rsa-1_5",
+          RSA_OAEP: "http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p",
+          RSA_OAEP_SHA256: "http://www.w3.org/2009/xmlenc11#rsa-oaep"
+        }.freeze
+        DATA_ENCRYPTION_ALGORITHM = {
+          TRIPLEDES_CBC: "http://www.w3.org/2001/04/xmlenc#tripledes-cbc",
+          AES_128_CBC: "http://www.w3.org/2001/04/xmlenc#aes128-cbc",
+          AES_192_CBC: "http://www.w3.org/2001/04/xmlenc#aes192-cbc",
+          AES_256_CBC: "http://www.w3.org/2001/04/xmlenc#aes256-cbc",
+          AES_128_GCM: "http://www.w3.org/2009/xmlenc11#aes128-gcm",
+          AES_192_GCM: "http://www.w3.org/2009/xmlenc11#aes192-gcm",
+          AES_256_GCM: "http://www.w3.org/2009/xmlenc11#aes256-gcm"
+        }.freeze
+        SecureSignatureAlgorithms = BetterAuth::Plugins::SSO_SAML_SECURE_SIGNATURE_ALGORITHMS
+        SecureDigestAlgorithms = BetterAuth::Plugins::SSO_SAML_SECURE_DIGEST_ALGORITHMS
+
+        def validate(xml, **options)
+          if xml.is_a?(Hash)
+            return validate_response(
+              sig_alg: xml[:sig_alg] || xml[:sigAlg] || xml["sig_alg"] || xml["sigAlg"],
+              saml_content: xml[:saml_content] || xml[:samlContent] || xml["saml_content"] || xml["samlContent"],
+              **options
+            )
+          end
+
+          BetterAuth::Plugins.sso_validate_saml_algorithms!(xml, normalize_options(options))
+        end
+
+        def validate_response(sig_alg: nil, saml_content: "", **options)
+          xml = +""
+          xml << "<ds:SignatureMethod Algorithm=\"#{sig_alg}\"/>" unless sig_alg.to_s.empty?
+          xml << saml_content.to_s
+          BetterAuth::Plugins.sso_validate_saml_algorithms!(xml, normalize_options(options))
+        end
+
+        def validate_config(config = {}, **options)
+          config_keys = %i[signature_algorithm signatureAlgorithm digest_algorithm digestAlgorithm]
+          inline_config = options.slice(*config_keys)
+          normalized = BetterAuth::Plugins.normalize_hash((config || {}).merge(inline_config))
+          options = options.except(*config_keys)
+          xml = +""
+          unless normalized[:signature_algorithm].to_s.empty?
+            xml << "<ds:SignatureMethod Algorithm=\"#{normalized[:signature_algorithm]}\"/>"
+          end
+          unless normalized[:digest_algorithm].to_s.empty?
+            xml << "<ds:DigestMethod Algorithm=\"#{normalized[:digest_algorithm]}\"/>"
+          end
+          BetterAuth::Plugins.sso_validate_saml_algorithms!(xml, normalize_options(options))
+        end
+
+        def normalize_signature(algorithm)
+          BetterAuth::Plugins.sso_normalize_saml_signature_algorithm(algorithm)
+        end
+
+        def normalize_digest(algorithm)
+          BetterAuth::Plugins.sso_normalize_saml_digest_algorithm(algorithm)
+        end
+
+        def normalize_options(options)
+          normalized = BetterAuth::Plugins.normalize_hash(options || {})
+          {
+            on_deprecated: normalized[:on_deprecated],
+            allowed_signature_algorithms: normalized[:allowed_signature_algorithms],
+            allowed_digest_algorithms: normalized[:allowed_digest_algorithms],
+            allowed_key_encryption_algorithms: normalized[:allowed_key_encryption_algorithms],
+            allowed_data_encryption_algorithms: normalized[:allowed_data_encryption_algorithms]
+          }.compact
+        end
+      end
+    end
+  end
+end

data/lib/better_auth/sso/saml/assertions.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module SSO
+    module SAML
+      module Assertions
+        module_function
+
+        def validate_single_assertion!(saml_response)
+          BetterAuth::Plugins.sso_validate_single_saml_assertion!(saml_response)
+        end
+
+        def count(xml)
+          assertions = xml.to_s.scan(/<(?:\w+:)?Assertion(?:\s|>|\/)/).length
+          encrypted_assertions = xml.to_s.scan(/<(?:\w+:)?EncryptedAssertion(?:\s|>|\/)/).length
+          {assertions: assertions, encrypted_assertions: encrypted_assertions, total: assertions + encrypted_assertions}
+        end
+      end
+    end
+  end
+end

data/lib/better_auth/sso/saml/error_codes.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module SSO
+    module SAML
+      module ErrorCodes
+        SAML_ERROR_CODES = {
+          single_logout_not_enabled: "Single Logout is not enabled",
+          invalid_logout_response: "Invalid LogoutResponse",
+          invalid_logout_request: "Invalid LogoutRequest",
+          logout_failed_at_idp: "Logout failed at IdP",
+          idp_slo_not_supported: "IdP does not support Single Logout Service",
+          saml_provider_not_found: "SAML provider not found"
+        }.freeze
+
+        module_function
+
+        def message(code)
+          SAML_ERROR_CODES[BetterAuth::Plugins.normalize_key(code)]
+        end
+      end
+    end
+  end
+end

data/lib/better_auth/sso/saml/parser.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module SSO
+    module SAML
+      module Parser
+        module_function
+
+        def parse_response(value, config = {}, provider = nil, ctx = nil)
+          BetterAuth::Plugins.sso_parse_saml_response(value, config, provider, ctx)
+        end
+
+        def base64_xml?(value)
+          BetterAuth::Plugins.sso_base64_xml?(value)
+        end
+      end
+    end
+  end
+end

data/lib/better_auth/sso/saml/timestamp.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module SSO
+    module SAML
+      module Timestamp
+        module_function
+
+        def validate!(conditions, config = {}, now: Time.now.utc)
+          BetterAuth::Plugins.sso_validate_saml_timestamp!(conditions, config, now: now)
+        end
+
+        def conditions(assertion)
+          BetterAuth::Plugins.sso_saml_timestamp_conditions(assertion)
+        end
+      end
+    end
+  end
+end