lobby_boy 0.1.0

data/README.md

@@ -0,0 +1,196 @@
+# lobby_boy
+Rails engine for OpenID Connect Session Management
+
+Assumes the use of OmniAuth and the `omniauth-openid-connect` strategy.
+
+## Dependencies
+
+If not present yet add the following gem:
+
+```ruby
+gem 'omniauth-openid-connect', git: 'https://github.com/jjbohn/omniauth-openid-connect.git', branch: 'master'
+```
+
+## Usage
+
+You have to do 6 steps to enable session management in your application:
+
+1. Mount the engine.
+2. Configure lobby_boy.
+3. Render lobby_boy's iframes partial in your layout.
+4. Call lobby_boy's `SessionHelper#confirm_login!` when the user is logged in.
+5. Call lobby_boy's `SessionHelper#logout_at_op!` when the user logs out.
+6. Implement the end_session_endpoint to be used by lobby_boys Javascript.
+
+The following sections will describe those steps in more detail.
+
+### 1. Mount the engine
+
+To mount the engine into your application add the following to your `config/routes.rb`:
+
+```ruby
+require 'lobby_boy'
+
+Rails.application.routes.draw do
+  mount LobbyBoy::Engine, at: '/'
+end
+```
+
+### 2. Configure lobby_boy
+
+The are two sections to be configured:
+
+*client*
+
+This refers to your application which is an OpenID Connect client.
+All lobby_boy needs to know about it is its `host` and `end_session_endpoint` (i.e. logout URL).
+
+Here are all available client options, the rest of them which are optional:
+
+```ruby
+LobbyBoy.configure_client! host: 'https://myapp.com',
+                           end_session_endpoint: '/logout',
+                           # (optional) Derived from host per default:
+                           cookie_domain: "myapp.com",
+                           # (optional) A block executed in the context of a rails controller
+                           # which returns true if the user is logged into
+                           # the application:
+                           logged_in: ->() { session.include? :user },
+                           # (optional) Seconds before the ID token's expiration at which
+                           # to re-authenticate early:
+                           refresh_offset: 60,
+                           # (optional) Check the session state every 30 seconds and refresh
+                           # if out of sync:
+                           refresh_interval: 30,
+                           # (optional) A .js.erb (app/views/session/_on_login.js.erb) partial
+                           # to be rendered the code of which will be executed if the user is
+                           # logged in automatically:
+                           on_login_js_partial: 'session/on_login',
+                           # (optional) A .js.erb (app/views/session/_on_logout.js.erb) partial
+                           # to be rendered the code of which will be executed if the user is
+                           # logged out automatically:
+                           on_logout_js_partial: 'session/on_logout'
+
+```
+
+*provider*
+
+The OpenIDConnect provider has to support Session Management too. The essential details
+required for the provider are its `name` (its strategy being available under `/auth/$name`)
+and the `identifier` under which your client is registered at the provider.
+
+If the provider supports discovery this is everything. If not you will also have to configure
+the `issuer`, `end_session_endpoint` and `check_session_iframe`.
+
+For instance for **Concierge** which does not support discovery yet:
+
+```ruby
+LobbyBoy.configure_provider! name:                 'concierge',
+                             client_id:            'openproject',
+                             issuer:               'https://concierge.openproject.com',
+                             end_session_endpoint: '/session/end',
+                             check_session_iframe: '/session/check']
+```
+
+### 3. Render lobby_boy's iframes partial in your layout.
+
+Session Management requires two iframes, the relying party iframe and the OpenIDConnect provider iframe,
+to be rendered at all times, on every page.
+In a standard rails application you would do this by inserting the following line into
+`app/views/layouts/application.html.erb`:
+
+```
+<%= render 'lobby_boy/iframes' %>
+```
+
+### 4. Call lobby_boy's `SessionHelper#confirm_login!` when the user is logged in.
+
+The `#confirm_login!` helper stores the logged-in user's ID token in the session
+and sets the `oidc_rp_state` cookie. Which means that this helper has to be called
+in the context of the final action handling the user's login.
+
+Another thing the login must do is to redirect the user to the omniauth origin.
+It should do that already if implemented correctly.
+
+For instance:
+
+```ruby
+class SessionController < ApplicationController
+  include LobbyBoy::SessionHelper
+
+  def login
+    # existing logic:
+    # ...
+
+    confirm_login!
+    redirect_to(request.env['omniauth.origin'] || default_url)
+  end
+end
+```
+
+It is important that your login action redirects to `omniauth.origin` after a
+successful login.
+
+*Optional: reauthentication*
+
+If you have to behave differently when the user is reauthenticated you can
+additionally to the changes above use the reauthentication helpers.
+
+```ruby
+class SessionController < ApplicationController
+  include LobbyBoy::SessionHelper
+
+  def login
+    # existing logic:
+    # ...
+
+    confirm_login!
+
+    if reauthentication?
+      finish_reauthentication!
+    else
+      go_on_to_do_more_stuff_not_necessary_on_reauthentication
+    end
+  end
+end
+
+### Call lobby_boy's `SessionHelper#logout_at_op!` when the user logs out.
+
+When the user logs out of the application they should also be logged out of the
+OpenID Connect provider. To do that call the `#logout_at_op!` helper in your existing logout action.
+The helper will redirect the user to the provider's logout endpoint to log them out globally.
+You can pass a return URL to which the provider will send the user after the logout.
+
+For instance:
+
+```ruby
+class SessionController < ApplicationController
+  def logout
+    # The helper will return false and do nothing the provider's
+    # end_session_endpoint is not configured.
+    unless logout_at_op! root_url
+      redirect_to root_url
+    end
+  end
+end
+```
+
+### 6. Implement the end_session_endpoint to be used by lobby_boys Javascript.
+
+The Javascript of lobby_boy may logout the user when it realizes that
+the user has been logged out at the OpenID Connect provider.
+You have to implement the `end_session_endpoint` and after logging out
+the user you have to call `finish_logout!` from LobbyBoy's `SessionHelper`.
+
+For instance:
+
+```ruby
+class SessionController < ApplicationController
+  include LobbyBoy::SessionHelper
+
+  def lobby_boy_logout
+    logout_user!
+    finish_logout!
+  end
+end
+```

data/Rakefile

@@ -0,0 +1,40 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'LobbyBoy'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+APP_RAKEFILE = File.expand_path("../test/dummy/Rakefile", __FILE__)
+load 'rails/tasks/engine.rake'
+
+
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+
+task :default => :test

data/app/controllers/lobby_boy/session_controller.rb

@@ -0,0 +1,93 @@
+module LobbyBoy
+  class SessionController < ActionController::Base
+    layout false
+
+    before_filter :set_cache_buster
+
+    def check
+      response.headers['X-Frame-Options'] = 'SAMEORIGIN'
+
+      render_check 'init'
+    end
+
+    def state
+      current_state =
+        if params[:state] == 'unauthenticated'
+          'unauthenticated'
+        elsif params[:state] == 'logout'
+          'logout'
+        else
+          self.id_token ? 'authenticated' : 'unauthenticated'
+        end
+
+      render_check current_state
+    end
+
+    def end
+      cookies.delete :oidc_rp_state, domain: LobbyBoy.client.cookie_domain
+
+      redirect_to LobbyBoy.client.end_session_endpoint
+    end
+
+    def refresh
+      provider = LobbyBoy.provider.name
+
+      id_token = self.id_token
+
+      id_token_hint = id_token && id_token.jwt_token
+      origin = '/session/state'
+
+      params = {
+          prompt: 'none',
+          origin: origin,
+          id_token_hint: id_token_hint
+      }
+
+      redirect_to "#{omniauth_prefix}/#{provider}?#{compact_hash(params).to_query}"
+    end
+
+    ##
+    # Defines used functions. All of which are only dependent on
+    # their input parameters and not on some random global state.
+    module Functions
+      module_function
+
+      ##
+      # Returns a new hash only containing entries the values of which are not nil.
+      def compact_hash(hash)
+        hash.reject { |_, v| v.nil? }
+      end
+
+      def omniauth_prefix
+        ::OmniAuth.config.path_prefix
+      end
+
+      ##
+      # Returns true if the user is logged in locally or false
+      # if they aren't or we don't know whether or not they are.
+      def logged_in?
+        instance_exec &LobbyBoy.client.logged_in
+      end
+    end
+
+    module InstanceMethods
+      def id_token
+        token = session['lobby_boy.id_token']
+        ::LobbyBoy::OpenIDConnect::IdToken.new token if token
+      end
+
+      def render_check(state)
+        render 'check', locals: { state: state, logged_in: logged_in? }
+      end
+
+      def set_cache_buster
+        response.headers["Cache-Control"] = "no-cache, no-store, max-age=0, must-revalidate"
+        response.headers["Pragma"] = "no-cache"
+        response.headers["Expires"] = "Fri, 01 Jan 1990 00:00:00 GMT"
+      end
+    end
+
+    include Functions
+    include InstanceMethods
+  end
+end

data/app/helpers/lobby_boy/session_helper.rb

@@ -0,0 +1,52 @@
+module LobbyBoy
+  module SessionHelper
+    ##
+    # Call in host rails controller to confirm that the user was logged in.
+    def confirm_login!
+      if LobbyBoy.configured?
+        session['lobby_boy.id_token'] = env['lobby_boy.id_token'].jwt_token
+        cookies[:oidc_rp_state] = env['lobby_boy.cookie']
+      end
+    end
+
+    def finish_reauthentication!
+      redirect_to(lobby_boy_path + 'session/state')
+    end
+
+    def reauthentication?
+      env['omniauth.origin'] == '/session/state'
+    end
+
+    def finish_logout!
+      redirect_to(lobby_boy_path + 'session/state?state=logout')
+    end
+
+    def id_token_expired?
+      id_token && id_token.expires_in == 0
+    end
+
+    def id_token
+      token = session['lobby_boy.id_token']
+      ::LobbyBoy::OpenIDConnect::IdToken.new token if token
+    end
+
+    def logout_at_op!(return_url = nil)
+      return false unless LobbyBoy.configured?
+
+      id_token_hint = id_token && id_token.jwt_token
+      logout_url = LobbyBoy::Util::URI.add_query_params(
+          LobbyBoy.provider.end_session_endpoint,
+          id_token_hint: id_token_hint,
+          post_logout_redirect_uri: return_url)
+
+      cookies.delete :oidc_rp_state, domain: LobbyBoy.client.cookie_domain
+
+      if logout_url # may be nil if not configured
+        redirect_to logout_url # log out at OpenIDConnect SSO provider too
+        true
+      else
+        false
+      end
+    end
+  end
+end

data/app/views/lobby_boy/_iframes.html.erb

@@ -0,0 +1,7 @@
+<% if LobbyBoy.configured? %>
+  <% op_src = LobbyBoy.provider.check_session_iframe %>
+  <% rp_src = "#{LobbyBoy.client.host}/session/check" %>
+
+  <iframe id="openid_connect_provider" src="<%= op_src %>" style="display: none;"></iframe>
+  <iframe id="openid_connect_relying_party" src="<%= rp_src %>" style="display: none;"></iframe>
+<% end %>

data/app/views/lobby_boy/session/check.html.erb

@@ -0,0 +1,171 @@
+<%= javascript_include_tag 'js.cookie-1.5.1.min' %>
+
+<%#
+    We're defining all this Javascript here as we are using URL helpers in it which
+    won't work in a .js.erb file without cheating.
+ %>
+
+<script type="text/javascript">
+    Cookies.json = true;
+
+    window.parent.OpenIDConnect = new function() {
+        var self = this;
+        var locallyLoggedIn = <%= logged_in %>;
+
+        this.clientId = "<%= LobbyBoy.provider.client_id %>";
+        this.targetOrigin = "<%= LobbyBoy.provider.issuer %>";
+        this.loggedIn = (window.parent.OpenIDConnect && window.parent.OpenIDConnect.loggedIn)
+                          || locallyLoggedIn;
+        this.timerIntervalMs = <%= LobbyBoy.client.refresh_interval %> * 1000;
+
+        this.getIFrame = function(id) {
+            return window.parent.document.getElementById(id).contentWindow;
+        }
+
+        this.checkSession = function() {
+            var provider = self.getIFrame("openid_connect_provider");
+
+            var message = function(state) {
+                return self.clientId + " " + state;
+            };
+
+            /**
+             * Checking the state has two possible outcomes depending on the user's
+             * global login state. Either the user is logged in in which case
+             * their ID token is refreshed, or they aren't in which case they
+             * are logged out of the application and notified about the logout.
+             */
+            var checkState = function(state) {
+                provider.postMessage(message(state), self.targetOrigin);
+            };
+
+            var state = Cookies.get("oidc_rp_state");
+            var time = new Date().getTime() / 1000;
+            var offset = <%= LobbyBoy.client.refresh_offset %>;
+
+            if (state || locallyLoggedIn) {
+                self.loggedIn = true;
+
+                if (state && state.expires_at - time > offset) {
+                    checkState(state.state);
+                } else if (!state && locallyLoggedIn) {
+                    /**
+                     * This branch is executed in two cases:
+                     *
+                     * 1) The state cookie is not set but the user is logged into the application
+                     *
+                     *    This can happen if the previous state cookie expired but the user's normal
+                     *    application session hasn't. At this point we don't know the user's
+                     *    global login status. Hence we force a re-authentication to sync the state.
+                     *
+                     * 2) The state is set but is about to expire.
+                     *
+                     *    We prematurely 'expire' the session state to ensure that the user
+                     *    remains logged in constantly. Otherwise it could happen that the
+                     *    user is logged out briefly between the time the old ID token expired
+                     *    and the time it takes to re-authenticate.
+                     */
+                    checkState("refresh.please");
+                }
+            } else {
+                // not logged in
+            }
+        };
+
+        this.startTimer = function() {
+            if (self.timerID) {
+                self.stopTimer(); // stop previous timer if present
+            }
+
+            self.timerID = setInterval(self.checkSession, self.timerIntervalMs);
+        };
+
+        this.stopTimer = function() {
+            clearInterval(self.timerID)
+        };
+
+        this.reauthenticate = function() {
+            console.log("I ought to re-authenticate");
+
+            var check_session_iframe = self.getIFrame("openid_connect_relying_party");
+
+            check_session_iframe.document.location.href = "<%= session_refresh_url %>";
+        };
+
+        this.onReauthenticationSuccess = function() {
+            console.log("Re-authenticated successfully.");
+
+            /**
+             * The login status will only be updated with the next call of checkSession
+             * which is why it may still be false at this point.
+             *
+             * If it is false it means the user may be seeing a sign-in button in the menu.
+             * So reload the page to have them see that they are now logged in.
+             */
+            if (self.loggedIn === false) {
+                self.onLogin();
+            }
+        };
+
+        this.onReauthenticationFailure = function() {
+            if (self.loggedIn !== false) {
+                self.loggedIn = false;
+                self.logout();
+            }
+        };
+
+        this.onLogin = function() {
+            <% if LobbyBoy.client.on_login_js_partial %>
+                <%= render partial: LobbyBoy.client.on_login_js_partial, formats: [:js] %>
+            <% else %>
+                window.parent.document.location.reload();
+            <% end %>
+        };
+
+        this.onLogout = function() {
+            <% if LobbyBoy.client.on_logout_js_partial %>
+                <%= render partial: LobbyBoy.client.on_logout_js_partial, formats: [:js] %>
+            <% else %>
+                alert("You've been logged out.");
+            <% end %>
+        };
+
+        this.logout = function(callback) {
+            console.log("I ought to log out.");
+
+            var check_session_iframe = self.getIFrame("openid_connect_relying_party");
+
+            check_session_iframe.document.location.href = "<%= session_end_url %>";
+        };
+
+        this.receiveMessage = function(e) {
+            if (e.origin !== self.targetOrigin ) {
+                return;
+            }
+
+            self.state = e.data;
+
+            if (self.state == "changed") {
+                self.reauthenticate();
+            } else if (self.state == "error") {
+                console.log("error checking session state");
+            }
+        };
+
+        window.addEventListener("message", self.receiveMessage, false);
+
+        <% if state == 'authenticated' %>
+            self.onReauthenticationSuccess();
+        <% elsif state == 'unauthenticated' %>
+            self.onReauthenticationFailure();
+        <% elsif state == 'logout' %>
+            self.onLogout();
+        <% else %>
+            document.addEventListener("DOMContentLoaded", function(event) {
+              setTimeout(self.checkSession, 1000);
+            });
+        <% end %>
+
+        self.startTimer();
+    };
+</script>