Module: HubSsoLib::Core

Defined in:
lib/hub_sso_lib.rb

Overview

Module: Core #

Various authors                                            #
                                                           #

Purpose: The barely recognisable core of acts_as_authenticated’s #

AuthenticatedSystem module, modified to work with the      #
other parts of HubSsoLib. You should include this module   #
to use its facilities.                                     #
                                                           #

Author: Various; adaptation by A.D.Hodgkinson #

#

History: 20-Oct-2006 (ADH): Integrated into HubSsoLib. #

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.included(base) ⇒ Object

Inclusion hook to make various methods available as ActionView helper methods.



1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
 
# File 'lib/hub_sso_lib.rb', line 1040

def self.included(base)
  base.send :helper_method,
            :hubssolib_current_user,
            :hubssolib_unique_name,
            :hubssolib_logged_in?,
            :hubssolib_account_link,
            :hubssolib_authorized?,
            :hubssolib_privileged?,
            :hubssolib_flash_data
rescue
  # We're not always included in controllers...
  nil
end

Instance Method Details

Returns markup for a link that leads to Hub’s conditional login endpoint, inline-styled as a red “Log in” or green “Account” button. This can be used in page templates to avoid needing any additional images or other such resources and using pure HTML + CSS for the login indication.

JavaScript is used so that e.g. “back” button fully-cached displays by a browser will get updated with the correct login state, where needed (so long as the ‘pageshow’ event is supported). NOSCRIPT browsers use the old no-cache image fallback, which is much less efficient, but works.



551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
 
# File 'lib/hub_sso_lib.rb', line 551

def 
  logged_in        = self.hubssolib_logged_in?()

  ui_href          = "#{HUB_PATH_PREFIX}/account/login_conditional"
  noscript_img_src = "#{HUB_PATH_PREFIX}/account/login_indication.png"
  noscript_img_tag = helpers.image_tag(noscript_img_src, size: '90x22', border: '0', alt: 'Log in or out')

  logged_in_link   = helpers.link_to('Account',        ui_href, id: 'hubssolib_logged_in_link')
  logged_out_link  = helpers.link_to('Log in',         ui_href, id: 'hubssolib_logged_out_link')
  noscript_link    = helpers.link_to(noscript_img_tag, ui_href, id: 'hubssolib_login_noscript')

  # Yes, it's ugly, but yes, it works and it's a lot better for the server
  # to avoid the repeated image fetches. It probably works out as overall
  # more efficient for clients too - despite all the JS etc. work, there's
  # no network fetch overhead or image rendering. On mobile in particular,
  # the JS solution is likely to use less battery power.
  #
  safe_markup = <<~HTML
    <div id="hubssolib_login_indication">
      <noscript>
        #{noscript_link}
      </noscript>
    </div>
    <script type="text/javascript">
      const logged_in_html  = "#{helpers.j(logged_in_link)}";
      const logged_out_html = "#{helpers.j(logged_out_link)}";
      const container       = document.getElementById('hubssolib_login_indication')

      #{
        # No '?.' support in NetSurf's JS engine, so can't do the match
        # and pop in a single line via "?.pop() || ''".
      }
      function hubSsoLibLoginStateWriteLink() {
        const regexp = '#{helpers.j(HUB_LOGIN_INDICATOR_COOKIE)}\\s*=\\s*([^;]+)';
        const match  = document.cookie.match(regexp);
        const flag   = (match ? match.pop() : null) || '';

        if (flag === '#{HUB_LOGIN_INDICATOR_COOKIE_VALUE}') {
          container.innerHTML = logged_in_html;
        } else {
          container.innerHTML = logged_out_html;
        }
      }
      #{
        # Immediate update, plus on-load update - including fully cached
        # loads in the browser when the "Back" button is used. No stale
        # login indications should thus arise from cached data.
      }
      hubSsoLibLoginStateWriteLink();
      window.addEventListener('load',     hubSsoLibLoginStateWriteLink);
      window.addEventListener('pageshow', hubSsoLibLoginStateWriteLink);
    </script>
  HTML

  return safe_markup.html_safe()
end

#hubssolib_afterwards ⇒ Object

Mandatory controller “after_action” callback method to tidy up after Hub actions during a request. Usually invoked in ApplicationController.



901
902
903
904
905
906
907
908
 
# File 'lib/hub_sso_lib.rb', line 901

def hubssolib_afterwards
  begin
    DRb.current_server
    DRb.stop_service()
  rescue DRb::DRbServerNotFound
    # Nothing to do; no service is running.
  end
end

#hubssolib_authorized?(action = action_name, classname = self.class) ⇒ Boolean

Check if the user is authorized to perform the current action. If calling from a helper, pass the action name and class name; otherwise by default, the current action name and ‘self.class’ will be used.

Override this method in your controllers if you want to restrict access to a different set of actions. Presently, the current user’s roles are compared against the caller’s permissions hash and the action name.

Returns:

  • (Boolean) 


616
617
618
619
620
621
622
623
624
625
626
 
# File 'lib/hub_sso_lib.rb', line 616

def hubssolib_authorized?(action = action_name, classname = self.class)

  # Classes with no permissions object always authorise everything.
  # Otherwise, ask the permissions object for its opinion.

  if (classname.respond_to? :hubssolib_permissions)
    return classname.hubssolib_permissions.permitted?(hubssolib_get_user_roles, action)
  else
    return true
  end
end

#hubssolib_beforehand ⇒ Object

Mandatory controller “before_action” callback method which activates HubSsoLib permissions management, session expiry and so-on. Usually invoked in ApplicationController.



818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
 
# File 'lib/hub_sso_lib.rb', line 818

def hubssolib_beforehand

  # Does this action require a logged in user?
  #
  if (self.class.respond_to? :hubssolib_permissions)
     = !self.class.hubssolib_permissions.permitted?('', action_name)
  else
     = false
  end

  # If we require login but we're logged out, redirect to Hub login.
  # NOTE EARLY EXIT
  #
  logged_in = hubssolib_logged_in?

  if logged_in == false
    cookies.delete(HUB_LOGIN_INDICATOR_COOKIE, domain: :all, path: '/')

    if 
      hubssolib_store_location
      return 
    else
      return true
    end
  end

  # Definitely logged in.
  #
  cookies[HUB_LOGIN_INDICATOR_COOKIE] = {
    value:    HUB_LOGIN_INDICATOR_COOKIE_VALUE,
    path:     '/',
    domain:   :all,
    expires:  1.year, # I.e. *not* session-scope
    secure:   ! hub_bypass_ssl?,
    httponly: false
  }

  # So we reach here knowing we're logged in, but the action may or
  # may not require authorisation.

  if ()

    # Login *is* required for this action. If the session expires,
    # redirect to Hub's login page via its expiry action. Otherwise
    # check authorisation and allow action processing to continue
    # if OK, else indicate that access is denied.

    if (hubssolib_session_expired?)
      hubssolib_store_location
      hubssolib_log_out
      hubssolib_set_flash(:attention, 'Sorry, your session timed out; you need to log in again to continue.')

      # We mean this: redirect_to :controller => 'account', :action => 'login'
      # ...except for the Hub, rather than the current application (whatever
      # it may be).
      redirect_to HUB_PATH_PREFIX + '/account/login'
    else
      hubssolib_set_last_used(Time.now.utc)
      return hubssolib_authorized? ? true : hubssolib_access_denied
    end

  else

    # We have to update session expiry even for actions that don't
    # need us to be logged in, since we *are* logged in and need to
    # maintain that state. If, though, the session expires, we just
    # quietly log out and let action processing carry on.

    if (hubssolib_session_expired?)
      hubssolib_log_out
      hubssolib_set_flash(:attention, 'Your session timed out, so you are no longer logged in.')
    else
      hubssolib_set_last_used(Time.now.utc)
    end

    return true # true -> let action processing continue

  end
end

#hubssolib_clear_flash ⇒ Object 



978
979
980
981
 
# File 'lib/hub_sso_lib.rb', line 978

def hubssolib_clear_flash
  return unless self.hubssolib_current_session
  self.hubssolib_current_session.session_flash = {}
end

#hubssolib_current_session ⇒ Object

Accesses the current session from the cookie. Creates a new session object if need be, but can return nil if e.g. attempting to access session cookie data without SSL.



655
656
657
 
# File 'lib/hub_sso_lib.rb', line 655

def hubssolib_current_session
  @hubssolib_current_session_proxy ||= hubssolib_get_session_proxy()
end

#hubssolib_current_user ⇒ Object

Accesses the current user, via the DRb server if necessary.



661
662
663
664
665
666
667
668
669
670
 
# File 'lib/hub_sso_lib.rb', line 661

def hubssolib_current_user
  hub_session = self.hubssolib_current_session
  user        = hub_session.nil? ? nil : hub_session.session_user

  if (user && user.user_id)
    return user
  else
    return nil
  end
end

#hubssolib_current_user=(user) ⇒ Object

Store the given user data in the cookie



674
675
676
677
 
# File 'lib/hub_sso_lib.rb', line 674

def hubssolib_current_user=(user)
  hub_session = self.hubssolib_current_session
  hub_session.session_user = user unless hub_session.nil?
end

#hubssolib_ensure_https ⇒ Object

Ensure the current request is carried out over HTTPS by redirecting back to the current URL with the HTTPS protocol if it isn’t. Returns ‘true’ if not redirected (already HTTPS), else ‘false’.



951
952
953
954
955
956
957
958
959
 
# File 'lib/hub_sso_lib.rb', line 951

def hubssolib_ensure_https
  if request.ssl? || hub_bypass_ssl?
    return true
  else
    # This isn't reliable: redirect_to({ :protocol => 'https://' })
    redirect_to( hubssolib_promote_uri_to_ssl( request.request_uri, request.host ) )
    return false
  end
end

#hubssolib_flash_data ⇒ Object

Return flash data for known keys, then all remaining keys, from both the cross-application and standard standard flash hashes. The returned Hash is of the form:

{ 'hub' => ...data..., 'standard' => ...data... }

…where “…data…” is itself a Hash of flash keys yielding flash values. This allows both the Hub and standard flashes to have values inside them under the same key. All keys are strings.



993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
 
# File 'lib/hub_sso_lib.rb', line 993

def hubssolib_flash_data

  # These known key values are used to guarantee an order in the output
  # for cases where multiple messages are defined.
  #
  compiled_data = { 'hub' => {}, 'standard' => {} }
  ordered_keys  = [
    'notice',
    'attention',
    'alert'
  ]

  # Get an array of keys for the Hub flash with the ordered key items
  # first and store data from that flash; same again for standard.

  hash = hubssolib_get_flash()
  keys = ordered_keys | hash.keys

  keys.each do | key |
    compiled_data['hub'][key] = hash[key] if hash.key?(key)
  end

  if defined?( flash )
    hash = flash.to_h()
    keys = ordered_keys | hash.keys

    keys.each do | key |
      compiled_data['standard'][key] = hash[key] if hash.key?(key)
    end
  end

  hubssolib_clear_flash()
  flash.discard()

  return compiled_data
end

#hubssolib_get_exception_message(id_data) ⇒ Object

Retrieve the message of an exception stored as an object in the given string.



1033
1034
1035
 
# File 'lib/hub_sso_lib.rb', line 1033

def hubssolib_get_exception_message(id_data)
  hubssolib_get_exception_data(CGI::unescape(id_data))
end

#hubssolib_get_flash ⇒ Object

Public methods to set some data that would normally go in @session, but can’t because it needs to be accessed across applications. It is put in an insecure support cookie instead. There are some related private methods for things like session expiry too.



966
967
968
969
 
# File 'lib/hub_sso_lib.rb', line 966

def hubssolib_get_flash()
  f = self.hubssolib_current_session ? self.hubssolib_current_session.session_flash : nil
  return f || {}
end

#hubssolib_get_user_address ⇒ Object

Public read-only accessor methods for common user activities: return the current user’s e-mail address, or nil if there’s no user.



710
711
712
713
 
# File 'lib/hub_sso_lib.rb', line 710

def hubssolib_get_user_address
  user = self.hubssolib_current_user
  user ? user.user_email : nil
end

#hubssolib_get_user_id ⇒ Object

Public read-only accessor methods for common user activities: return the Hub database ID of the current user account, or nil if there’s no user. See also hubssolib_unique_name.



701
702
703
704
 
# File 'lib/hub_sso_lib.rb', line 701

def hubssolib_get_user_id
  user = self.hubssolib_current_user
  user ? user.user_id : nil
end

#hubssolib_get_user_name ⇒ Object

Public read-only accessor methods for common user activities: return the current user’s name as a string, or nil if there’s no user. See also hubssolib_unique_name.



692
693
694
695
 
# File 'lib/hub_sso_lib.rb', line 692

def hubssolib_get_user_name
  user = self.hubssolib_current_user
  user ? user.user_real_name : nil
end

#hubssolib_get_user_roles ⇒ Object

Public read-only accessor methods for common user activities: return the current user’s roles as a Roles object, or nil if there’s no user.



683
684
685
686
 
# File 'lib/hub_sso_lib.rb', line 683

def hubssolib_get_user_roles
  user = self.hubssolib_current_user
  user ? user.user_roles.to_authenticated_roles : nil
end

#hubssolib_log_out ⇒ Object

Log out the user. Very few applications should ever need to call this, though Hub certainly does and it gets used internally too.



644
645
646
647
648
649
 
# File 'lib/hub_sso_lib.rb', line 644

def hubssolib_log_out
  # Causes the "hubssolib_current_[foo]=" methods to run, which
  # deal with everything else.
  self.hubssolib_current_user = nil
  @hubssolib_current_session_proxy = nil
end

#hubssolib_logged_in? ⇒ Boolean

Returns true or false if the user is logged in.

Preloads @hubssolib_current_user with user data if logged in.

Returns:

  • (Boolean) 


537
538
539
 
# File 'lib/hub_sso_lib.rb', line 537

def hubssolib_logged_in?
  !!self.hubssolib_current_user
end

#hubssolib_privileged? ⇒ Boolean

Is the current user privileged? Anything other than normal user privileges will suffice. Can be called if not logged in. Returns ‘false’ for logged out or normal user privileges only, else ‘true’.

Returns:

  • (Boolean) 


632
633
634
635
636
637
638
639
 
# File 'lib/hub_sso_lib.rb', line 632

def hubssolib_privileged?
  return false unless hubssolib_logged_in?

  pnormal = HubSsoLib::Roles.new(false).to_s
  puser   = hubssolib_get_user_roles().to_s

  return (puser && !puser.empty? && puser != pnormal)
end

#hubssolib_promote_uri_to_ssl(uri_str, host = nil) ⇒ Object

Take a URI and pass an optional host parameter. Decomposes the URI, sets the host you provide (or leaves it alone if you omit the parameter), then forces the scheme to ‘https’. Returns the result as a flat string.



940
941
942
943
944
945
 
# File 'lib/hub_sso_lib.rb', line 940

def hubssolib_promote_uri_to_ssl(uri_str, host = nil)
  uri = URI.parse(uri_str)
  uri.host = host if host
  uri.scheme = hub_bypass_ssl? ? 'http' : 'https'
  return uri.to_s
end

#hubssolib_redirect_back_or_default(default) ⇒ Object

Redirect to the URI stored by the most recent store_location call or to the passed default.



928
929
930
931
932
933
 
# File 'lib/hub_sso_lib.rb', line 928

def hubssolib_redirect_back_or_default(default)
  url = hubssolib_get_return_to
  hubssolib_set_return_to(nil)

  redirect_to(url || default)
end

#hubssolib_register_user_change_handler(app_name:, app_root:, task_name:) ⇒ Object

If an application needs to know about changes of a user e-mail address or display name (e.g. because of sync to a local relational store of users related to other application-managed resources, with therefore a desire to keep that store up to date), it can register a task to run on-change here. When a user edits their information, Hub runs through all such commands, allowing external applications to manage their own state with no need for coupled configuration or other duplication.

The registered name must be a Rake task and the application must specify its location in the filesystem so that the PWD can be changed there, in order to execute the Rake task via “bundle exec”. The task is passed the following parameters, in the specified order:

  • User’s old e-mail address

  • User’s old unique display name (as returned by #hubssolib_unique_name)

  • User’s new e-mail address (which might be the same as the old)

  • User’s old unique display name (which might be unchanged too)

This is a newer Hub interface which uses named parameters rather than positional:

app_name

Application name, e.g. “beast”; make sure this is unique.

app_root

Application’s Rails root, e.g. “/home/fred/rails/beast”.

task_name

Rake task name, e.g. “hub:update_user”.

An example invocation in “config/application.rb” might look like this:

module Foo
  class Application < Rails::Application

  require HubSsoLib::Core

    hubssolib_register_user_change_handler(
      app_name:  Rails.application.name,
      app_root:  Rails.root,
      task_name: 'hub:update_user'
    )

    config.load_defaults 8.0 # ...etc...
  end
end



768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
 
# File 'lib/hub_sso_lib.rb', line 768

def hubssolib_register_user_change_handler(app_name:, app_root:, task_name:)
  File.open(HUB_COMMAND_REGISTRY, File::RDWR | File::CREAT) do |file|
    file.flock(File::LOCK_EX)

    commands_json   = file.read()
    commands_hash   = (JSON.parse(commands_json) rescue nil) if commands_json.present?
    commands_hash ||= {}

    file.rewind()

    commands_hash[app_name] = {
      root: app_root,
      task: task_name
    }

    file.write(JSON.fast_generate(commands_hash))
    file.truncate(file.pos)
  end
end

#hubssolib_registered_user_change_handlers ⇒ Object

Returns all change handlers registered by prior calls made to #hubssolib_register_user_change_handler. Returns a Hash, keyed by Rails application name, with values of another Hash:

  • root => Rails application root

  • task => Name of Rake task to be run

All keys are Strings.

This is usually called by the Hub application only, when it is processing a user’s request to change their information.



800
801
802
803
804
805
806
807
808
809
810
811
812
 
# File 'lib/hub_sso_lib.rb', line 800

def hubssolib_registered_user_change_handlers
  commands_hash = {}

  File.open(HUB_COMMAND_REGISTRY, File::RDWR | File::CREAT) do |file|
    file.flock(File::LOCK_EX)

    commands_json   = file.read()
    commands_hash   = (JSON.parse(commands_json) rescue nil) if commands_json.present?
    commands_hash ||= {}
  end

  return commands_hash
end

#hubssolib_set_flash(symbol, message) ⇒ Object 



971
972
973
974
975
976
 
# File 'lib/hub_sso_lib.rb', line 971

def hubssolib_set_flash(symbol, message)
  return unless self.hubssolib_current_session
  f = hubssolib_get_flash
  f[symbol.to_s] = message
  self.hubssolib_current_session.session_flash = f
end

#hubssolib_store_location(uri_str = request.url) ⇒ Object

Store the URI of the current request in the session, or store the optional supplied specific URI.

We can return to this location by calling #redirect_back_or_default.



915
916
917
918
919
920
921
922
923
924
 
# File 'lib/hub_sso_lib.rb', line 915

def hubssolib_store_location(uri_str = request.url)

  if (uri_str && !uri_str.empty?)
    uri_str = hubssolib_promote_uri_to_ssl(uri_str, request.host) unless request.ssl?
    hubssolib_set_return_to(uri_str)
  else
    hubssolib_set_return_to(nil)
  end

end

#hubssolib_unique_name ⇒ Object

Return a human-readable unique ID for a user. We don’t want to have e-mail addresses all over the place, but don’t want to rely on real names as unique - they aren’t. Instead, produce a composite of the user’s account database ID (which must be unique by definition) and their real name. See also hubssolib_get_name.



722
723
724
725
 
# File 'lib/hub_sso_lib.rb', line 722

def hubssolib_unique_name
  user = hubssolib_current_user
  user ? "#{user.user_real_name} (#{user.user_id})" : 'Anonymous'
end