feat: Support for configurable IdP SLO session destruction

Author: brennana

README.md

@@ -89,6 +89,10 @@ The service provider metadata used to ease configuration of the SAML SP in the I
 * `:idp_slo_target_url` - The URL to which the single logout request and response should
   be sent. This would be on the identity provider. Optional.
 
+* `:idp_slo_session_destroy` - A proc that accepts up to two parameters (the rack environment, and the session),
+  and performs whatever tasks are necessary to log out the current user from your application.
+  See the example listed under "Single Logout." Defaults to calling `#clear` on the session. Optional.
+
 * `:slo_default_relay_state` - The value to use as default `RelayState` for single log outs. The
   value can be a string, or a `Proc` (or other object responding to `call`). The `request`
   instance will be passed to this callable if it has an arity of 1. If the value is a string,
@@ -184,6 +188,18 @@ class SessionsController < Devise::SessionsController
 end
 ```
 
+By default, omniauth-saml attempts to log the current user out of your application by clearing the session.
+This may not be enough for some authentication solutions (e.g. [Clearance](https://github.com/thoughtbot/clearance/)).
+Instead, you may set the `:idp_slo_session_destroy` option to a proc that performs the necessary logout tasks.
+
+Example `:idp_slo_session_destroy` setting for Clearance compatibility:
+
+```ruby
+Rails.application.config.middleware.use OmniAuth::Builder do
+  provider :saml, idp_slo_session_destroy: proc { |env, _session| env[:clearance].sign_out }, ...
+end
+```
+
 ## Authors
 
 Authored by [Rajiv Aaron Manglani](http://www.rajivmanglani.com/), Raecoo Cao, Todd W Saxton, Ryan Wilcox, Steven Anderson, Nikos Dimitrakopoulos, Rudolf Vriend and [Bruno Pedro](http://brunopedro.com/).

lib/omniauth/strategies/saml.rb

@@ -29,6 +29,7 @@ def self.inherited(subclass)
       }
       option :slo_default_relay_state
       option :uid_attribute
+      option :idp_slo_session_destroy, proc { |_env, session| session.clear }
 
       def request_phase
         options[:assertion_consumer_service_url] ||= callback_url
@@ -230,7 +231,7 @@ def handle_logout_request(raw_request, settings)
           logout_request.name_id == session["saml_uid"]
 
           # Actually log out this session
-          session.clear
+          options[:idp_slo_session_destroy].call @env, session
 
           # Generate a response to the IdP.
           logout_request_id = logout_request.id