feat: Support for Single Logout

Appraisals

@@ -1,5 +1,6 @@
 appraise 'rack-1' do
  gem 'rack', '~> 1.x'
+ gem 'term-ansicolor', '1.3.2'
 end
 
 appraise 'rack-2' do

README.md

@@ -86,6 +86,14 @@ The service provider metadata used to ease configuration of the SAML SP in the I
 * `:idp_sso_target_url` - The URL to which the authentication request should be sent.
  This would be on the identity provider. **Required**.
 
+* `: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.
+
+* `: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,
+ the string will be returned, when the `RelayState` is called. Optional.
+
 * `:idp_sso_target_url_runtime_params` - A dynamic mapping of request params that exist
  during the request phase of OmniAuth that should to be sent to the IdP after a specific
  mapping. So for example, a param `original_request_param` with value `original_param_value`,
@@ -145,6 +153,35 @@ end
 
 Then follow Devise's general [OmniAuth tutorial](https://github.com/plataformatec/devise/wiki/OmniAuth:-Overview), replacing references to `facebook` with `saml`.
 
+## Single Logout
+
+Single Logout can be Service Provider initiated or Identity Provider initiated.
+When using Devise as an authentication solution, the SP initiated flow can be integrated
+in the `SessionsController#destroy` action.
+
+For this to work it is important to preserve the `saml_uid` value before Devise
+clears the session and redirect to the `/spslo` sub-path to initiate the single logout.
+
+Example `destroy` action in `sessions_controller.rb`:
+
+```ruby
+class SessionsController < Devise::SessionsController
+ # ...
+
+ def destroy
+ # Preserve the saml_uid in the session
+ saml_uid = session["saml_uid"]
+ super do
+ session["saml_uid"] = saml_uid
+ if SAML_SETTINGS.idp_slo_target_url
+ spslo_url = user_omniauth_authorize_url(:saml) + "/spslo"
+ redirect_to(spslo_url)
+ end
+ end
+ end
+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/).

gemfiles/rack_1.gemfile

@@ -4,6 +4,7 @@ source "https://rubygems.org"
 
 gem "appraisal"
 gem "rack", "~> 1.x"
+gem "term-ansicolor", "1.3.2"
 
 group :test do
  gem "coveralls", "~> 0.8", ">= 0.8.13", :require => false

lib/omniauth/strategies/saml.rb

@@ -27,15 +27,19 @@ def self.inherited(subclass)
  first_name: ["first_name", "firstname", "firstName"],
  last_name: ["last_name", "lastname", "lastName"]
  }
+ option :slo_default_relay_state
 
  def request_phase
  options[:assertion_consumer_service_url] ||= callback_url
  runtime_request_parameters = options.delete(:idp_sso_target_url_runtime_params)
 
  additional_params = {}
- runtime_request_parameters.each_pair do |request_param_key, mapped_param_key|
- additional_params[mapped_param_key] = request.params[request_param_key.to_s] if request.params.has_key?(request_param_key.to_s)
- end if runtime_request_parameters
+
+ if runtime_request_parameters
+ runtime_request_parameters.each_pair do |request_param_key, mapped_param_key|
+ additional_params[mapped_param_key] = request.params[request_param_key.to_s] if request.params.has_key?(request_param_key.to_s)
+ end
+ end
 
  authn_request = OneLogin::RubySaml::Authrequest.new
  settings = OneLogin::RubySaml::Settings.new(options)
@@ -44,9 +48,7 @@ def request_phase
  end
 
  def callback_phase
- unless request.params['SAMLResponse']
- raise OmniAuth::Strategies::SAML::ValidationError.new("SAML response missing")
- end
+ raise OmniAuth::Strategies::SAML::ValidationError.new("SAML response missing") unless request.params["SAMLResponse"]
 
  # Call a fingerprint validation method if there's one
  if options.idp_cert_fingerprint_validator
@@ -59,30 +61,21 @@ def callback_phase
  end
 
  settings = OneLogin::RubySaml::Settings.new(options)
+
  # filter options to select only extra parameters
  opts = options.select {|k,_| OTHER_REQUEST_OPTIONS.include?(k.to_sym)}
+
  # symbolize keys without activeSupport/symbolize_keys (ruby-saml use symbols)
  opts =
  opts.inject({}) do |new_hash, (key, value)|
  new_hash[key.to_sym] = value
  new_hash
  end
- response = OneLogin::RubySaml::Response.new(request.params['SAMLResponse'], opts.merge(settings: settings))
- response.attributes['fingerprint'] = options.idp_cert_fingerprint
-
- # will raise an error since we are not in soft mode
- response.soft = false
- response.is_valid?
-
- @name_id = response.name_id
- @attributes = response.attributes
- @response_object = response
 
- if @name_id.nil? || @name_id.empty?
- raise OmniAuth::Strategies::SAML::ValidationError.new("SAML response missing 'name_id'")
+ handle_response(request.params["SAMLResponse"], opts, settings) do
+ super
  end
 
- super
  rescue OmniAuth::Strategies::SAML::ValidationError
  fail!(:invalid_ticket, $!)
  rescue OneLogin::RubySaml::ValidationError
@@ -91,7 +84,7 @@ def callback_phase
 
  # Obtain an idp certificate fingerprint from the response.
  def response_fingerprint
- response = request.params['SAMLResponse']
+ response = request.params["SAMLResponse"]
  response = (response =~ /^</) ? response : Base64.decode64(response)
  document = XMLSecurity::SignedDocument::new(response)
  cert_element = REXML::XPath.first(document, "//ds:X509Certificate", { "ds"=> 'http://www.w3.org/2000/09/xmldsig#' })
@@ -101,26 +94,43 @@ def response_fingerprint
  Digest::SHA1.hexdigest(cert.to_der).upcase.scan(/../).join(':')
  end
 
- def on_metadata_path?
- on_path?("#{request_path}/metadata")
- end
-
  def other_phase
- if on_metadata_path?
- # omniauth does not set the strategy on the other_phase
+ if current_path.start_with?(request_path)
  @env['omniauth.strategy'] ||= self
  setup_phase
-
- response = OneLogin::RubySaml::Metadata.new
  settings = OneLogin::RubySaml::Settings.new(options)
- if options.request_attributes.length > 0
- settings.attribute_consuming_service.service_name options.attribute_service_name
- settings.issuer = options.issuer
- options.request_attributes.each do |attribute|
- settings.attribute_consuming_service.add_attribute attribute
+
+ if on_subpath?(:metadata)
+ # omniauth does not set the strategy on the other_phase
+ response = OneLogin::RubySaml::Metadata.new
+
+ if options.request_attributes.length > 0
+ settings.attribute_consuming_service.service_name options.attribute_service_name
+ settings.issuer = options.issuer
+
+ options.request_attributes.each do |attribute|
+ settings.attribute_consuming_service.add_attribute attribute
+ end
+ end
+
+ Rack::Response.new(response.generate(settings), 200, { "Content-Type" => "application/xml" }).finish
+ elsif on_subpath?(:slo)
+ if request.params["SAMLResponse"]
+ handle_logout_response(request.params["SAMLResponse"], settings)
+ elsif request.params["SAMLRequest"]
+ handle_logout_request(request.params["SAMLRequest"], settings)
+ else
+ raise OmniAuth::Strategies::SAML::ValidationError.new("SAML logout response/request missing")
+ end
+ elsif on_subpath?(:spslo)
+ if options.idp_slo_target_url
+ redirect(generate_logout_request(settings))
+ else
+ Rack::Response.new("Not Implemented", 501, { "Content-Type" => "text/html" }).finish
  end
+ else
+ call_app!
  end
- Rack::Response.new(response.generate(settings), 200, { "Content-Type" => "application/xml" }).finish
  else
  call_app!
  end
@@ -146,6 +156,94 @@ def find_attribute_by(keys)
 
  nil
  end
+
+ private
+
+ def on_subpath?(subpath)
+ on_path?("#{request_path}/#{subpath}")
+ end
+
+ def handle_response(raw_response, opts, settings)
+ response = OneLogin::RubySaml::Response.new(raw_response, opts.merge(settings: settings))
+ response.attributes["fingerprint"] = options.idp_cert_fingerprint
+ response.soft = false
+
+ response.is_valid?
+ @name_id = response.name_id
+ @attributes = response.attributes
+ @response_object = response
+
+ if @name_id.nil? || @name_id.empty?
+ raise OmniAuth::Strategies::SAML::ValidationError.new("SAML response missing 'name_id'")
+ end
+
+ session["saml_uid"] = @name_id
+ yield
+ end
+
+ def slo_relay_state
+ if request.params.has_key?("RelayState") && request.params["RelayState"] != ""
+ request.params["RelayState"]
+ else
+ slo_default_relay_state = options.slo_default_relay_state
+ if slo_default_relay_state.respond_to?(:call)
+ if slo_default_relay_state.arity == 1
+ slo_default_relay_state.call(request)
+ else
+ slo_default_relay_state.call
+ end
+ else
+ slo_default_relay_state
+ end
+ end
+ end
+
+ def handle_logout_response(raw_response, settings)
+ # After sending an SP initiated LogoutRequest to the IdP, we need to accept
+ # the LogoutResponse, verify it, then actually delete our session.
+
+ logout_response = OneLogin::RubySaml::Logoutresponse.new(raw_response, settings, :matches_request_id => session["saml_transaction_id"])
+ logout_response.soft = false
+ logout_response.validate
+
+ session.delete("saml_uid")
+ session.delete("saml_transaction_id")
+
+ redirect(slo_relay_state)
+ end
+
+ def handle_logout_request(raw_request, settings)
+ logout_request = OneLogin::RubySaml::SloLogoutrequest.new(raw_request)
+
+ if logout_request.is_valid? &&
+ logout_request.name_id == session["saml_uid"]
+
+ # Actually log out this session
+ session.clear
+
+ # Generate a response to the IdP.
+ logout_request_id = logout_request.id
+ logout_response = OneLogin::RubySaml::SloLogoutresponse.new.create(settings, logout_request_id, nil, RelayState: slo_relay_state)
+ redirect(logout_response)
+ else
+ raise OmniAuth::Strategies::SAML::ValidationError.new("SAML failed to process LogoutRequest")
+ end
+ end
+
+ # Create a SP initiated SLO: https://github.com/onelogin/ruby-saml#single-log-out
+ def generate_logout_request(settings)
+ logout_request = OneLogin::RubySaml::Logoutrequest.new()
+
+ # Since we created a new SAML request, save the transaction_id
+ # to compare it with the response we get back
+ session["saml_transaction_id"] = logout_request.uuid
+
+ if settings.name_identifier_value.nil?
+ settings.name_identifier_value = session["saml_uid"]
+ end
+
+ logout_request.create(settings, RelayState: slo_relay_state)
+ end
  end
  end
 end