shibbolite 0.0.1

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2014 David Bassett
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,108 @@
+= Shibbolite
+
+Are you running Rails apps in a Shibboleth environment? Do you want to use all those sweet Shibboleth provided attributes for super simple access control? Shibbolite is the gem for you.
+
+== Caveats
+So far Shibbolite has been tested in one environment (mine). That is:
+
+* Apache 2.2
+* Shibboleth NativeSP 2.5 (older versions will not work due to URL redirect options not existing before this)
+* Phusion Passenger
+* Rails 4.0.* (older won't work)
+
+Shibbolite should work fine in any environment that provides the NativeSP attributes as environment variables. As of this writing that includes all versions of Apache by default, and that's pretty much it. Some quick googling tells me that Nginx support can be enabled with FastCGI, and possibly Mongrel as well, but it looks like this will provide the attributes as request headers, which will not work out of the box.
+ 
+== Install
+=== Before you start...
+Shibbolite expects that you already
+1. Have root set to something
+2. Created a User model at some point
+
+=== OK let's go
+In your Gemfile
+  gem 'shibbolite'
+Then run bundle to install it. Now run the handy generator
+  rails generate shibbolite:install
+...which will copy shibbolite_config.rb to your app's initializer folder. Take a look over the various options. You'll have to add your SP's attributes to the configuration, as well as specify the name of your user class if it isn't "User". You can also configure the list of valid group types you can assign to your users.
+
+If your SP handler locations are configured differently from the common defaults you'll have to specify those as well. See your SP's /Status handler more information, as well as the {Shibboleth documentation}[https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPSessions].
+
+Now generate the migration
+  rails generate shibbolite:migration
+This will create a migration for your User model that adds all of the Shibbolith attributes. Take a look at it then run
+  rake db:migrate
+
+Go to your User model and add
+  include Shibbolite::User
+
+Go to your ApplicationController and add
+  include Shibbolite::Filters
+
+Restart your application
+
+== Usage
+Shibbolite::User adds some validations as well as .find_user, which returns the user that has the supplied :primary_user_id
+
+Shibbolite::Filters gives you a gaggle of before filters to enable access control and a handful of helpers for views. Below are some examples, see the source for a complete list.
+
+=== Filters
+  before_action :require_login
+
+In your ApplicationController will require that users have a valid Shibboleth session before they can launch any action
+
+  before_action { |c| c.require_group :admin }
+
+will require that the user belong to the admin group
+
+  before_action { |c| c.require_group :admin, :user }
+
+will allow anyone who has the admin or the user group
+
+  before_action { |c| c.require_group_or_id :admin, some_user.id }
+
+is useful for things like profile pages that are accessible to both an owner and anyone in the admin group
+
+  before_action :use_attributes_if_available, only: :public
+
+will attempt to load a Shibboleth session if one is available but do nothing otherwise. Use this if you have a public page but still want to make use of attributes for users that have logged in.
+
+=== Helpers
+These helpers will be available to views of any controllers that include Shibbolite::Filters. See the source for a complete list.
+
+  current_user
+
+will return the User object of the Shibboleth authenticated user or nil if no one is authenticated, or the user isn't registered in the database. NOTE: current_user can still return nil after the user authenticates if one of the above filters isn't used before the controller action.
+
+Since current_user relies on a database lookup, you'll have to register (ie persist) your users before they can interact with most of the features of Shibbolite. How you want to handle user registration is left up to you.
+
+  logged_in?
+
+checks to see that a username is set in the session
+
+  user_in_group? (:admin)
+
+will return true if the current user has the admin group
+
+  
+
+=== Actions
+A couple of actions are available from Shibbolite::ShibbolethController
+
+  shibbolite.login_path #=> '/shibbolite/login'
+
+will attempt to load a Shibboleth session, or redirect to the Shibbolite.session_initiator for authentication if there is none. After authentication the user is brought back to the root_path.
+
+  shibbolite.logout_path #=> 'shibbolite/logout
+
+likewise redirects the client to the Shibbolite.logout_initiator
+ 
+== Contribute
+1. Fork the repository
+2. Make sure the tests pass
+3. Write a test for your change and make it pass
+4. Push the changes to your Fork
+5. Submit a pull request
+
+== License
+
+Shibbolite is released under the MIT License

data/Rakefile

@@ -0,0 +1,21 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+APP_RAKEFILE = File.expand_path("../spec/dummy/Rakefile", __FILE__)
+load 'rails/tasks/engine.rake'
+
+Bundler::GemHelper.install_tasks
+
+Dir[File.join(File.dirname(__FILE__), 'tasks/**/*.rake')].each {|f| load f }
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+
+desc "Run all specs in spec directory (excluding plugin specs)"
+RSpec::Core::RakeTask.new(:spec => 'app:db:test:prepare')
+
+task :default => :spec
+

data/app/concerns/shibbolite/filters.rb

@@ -0,0 +1,44 @@
+# controller filters for access control
+module Shibbolite
+  module Filters
+    extend ActiveSupport::Concern
+
+    include Shibbolite::Helpers
+
+    def require_login
+      redirect_to login_or_access_denied unless logged_in?
+    end
+
+    def require_registered
+      redirect_to login_or_access_denied unless registered_user?
+    end
+
+    def require_group(*groups)
+      in_group = false
+      groups.flatten.each { |group| in_group ||= user_in_group?(group) }
+      redirect_to login_or_access_denied unless in_group
+    end
+
+    def require_id(id)
+      redirect_to login_or_access_denied unless user_has_id?(id)
+    end
+
+    def require_group_or_id(*groups, id)
+      unless user_has_id?(id)
+        require_group(groups)
+      end
+    end
+
+    def use_attributes_if_available
+      if request.env[Shibbolite.pid.to_s] and not logged_in?
+        redirect_to login_or_access_denied
+      end
+    end
+
+    # a handy redirect target
+    def login_or_access_denied
+      session[:requested_url] = request.fullpath
+      logged_in? ? shibbolite.access_denied_url : shibbolite.login_url
+    end
+  end
+end

data/app/concerns/shibbolite/helpers.rb

@@ -0,0 +1,48 @@
+module Shibbolite
+  module Helpers
+    extend ActiveSupport::Concern
+
+    included do
+      helper_method :logged_in?, :current_user, :anonymous_user?, :guest_user?,
+                    :registered_user?, :user_in_group?, :user_has_id?
+    end
+
+    # true when the primary_user_id has been saved in session
+    def logged_in?
+      session[Shibbolite.pid]
+    end
+
+    # sets current user from the session user id
+    def current_user
+      logged_in? ? @current_user ||= Shibbolite.user_class.find_user(session[Shibbolite.pid]) : nil
+    end
+
+    # true when user hasn't signed in to SSO
+    def anonymous_user?
+      not logged_in?
+    end
+
+    # true when the user signed in to the SSO
+    # but they haven't been registered with the app
+    def guest_user?
+      current_user.nil? and logged_in?
+    end
+
+    # true when the user exists in the database
+    def registered_user?
+      current_user
+    end
+
+    def user_in_group?(group, user = nil)
+      user ||= current_user
+      return false unless user
+      user.group == group.to_s
+    end
+
+    def user_has_id?(id, user = nil)
+      user ||= current_user
+      return false unless user
+      user.id == id
+    end
+  end
+end

data/app/concerns/shibbolite/user.rb

@@ -0,0 +1,21 @@
+module Shibbolite
+  module User
+    extend ActiveSupport::Concern
+
+    included do
+      unless Shibbolite.skip_validations
+        validates Shibbolite.primary_user_id, :group, presence: true
+        validates Shibbolite.primary_user_id, uniqueness: true
+        validates :group, inclusion: { in: Shibbolite.groups.map(&:to_s),
+                  message: "%{value} is not included in Shibbolite.groups" }
+      end
+    end
+
+    module ClassMethods
+      # gets the user who matches the shibboleth primary key
+      def find_user(pid)
+        find_by(Shibbolite.primary_user_id => pid)
+      end
+    end
+  end
+end

data/app/controllers/shibbolite/shibboleth_controller.rb

@@ -0,0 +1,53 @@
+module Shibbolite
+  class ShibbolethController < ActionController::Base
+
+    include Shibbolite::Helpers
+
+    def access_denied
+      @requested_url = session.delete(:requested_url)
+    end
+
+    def login
+      session[:requested_url] ||= main_app.root_path
+      load_session
+      redirect_to logged_in? ? session.delete(:requested_url) : sp_login_url
+    end
+
+    def logout
+      session.delete(Shibbolite.pid)
+      redirect_to sp_logout_url
+    end
+
+    # required to prevent displaying default shibboleth logout message
+    def logout_message ; end
+
+    private
+
+    # loads the session data created by shibboleth
+    # ensures that the user's id is set in session
+    # and updates the user's shibboleth attributes
+    def load_session
+      unless logged_in?
+        session[Shibbolite.pid] = request.env[Shibbolite.pid.to_s]
+        current_user.update(get_attributes) if registered_user?
+      end
+    end
+
+    # reads shibboleth attributes from environment
+    def get_attributes
+      request.env.with_indifferent_access.slice(*Shibbolite.attributes)
+    end
+
+    def sp_login_url
+      request.protocol + request.host +
+          Shibbolite.handler_url + Shibbolite.session_initiator +
+          '?' + URI.encode_www_form(target: login_url)
+    end
+
+    def sp_logout_url
+      request.protocol + request.host +
+          Shibbolite.handler_url + Shibbolite.logout_initiator +
+          '?' + URI.encode_www_form(return: logout_message_url)
+    end
+  end
+end

data/app/views/layouts/shibbolite/shibboleth.html.erb

@@ -0,0 +1,32 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Shibbolite</title>
+  <style>
+    body {
+      background-color: white;
+      color: #474747;
+      text-align: left;
+      font-family: arial, sans-serif;
+    }
+
+    div.message {
+      width: 20em;
+      margin: 2em 0 0 2em;
+      border: 20px solid #D8000F;
+      border-radius: 70px;
+      padding: 7px 3em 1em 3em;
+    }
+
+    h1 {
+      font-size: 25px;
+      color: #D8000F;
+      line-height: 2em;
+    }
+
+  </style>
+</head>
+
+<body>
+  <%= yield %>
+</body>

data/app/views/shibbolite/shibboleth/access_denied.html.erb

@@ -0,0 +1,7 @@
+<div class="message">
+  <h1>(Shibbolite) Access Denied</h1>
+  <p>
+    You don't the credentials required to access <%= @requested_url %>.
+  </p>
+  <%= link_to 'Back', :back %>
+</div>

data/app/views/shibbolite/shibboleth/logout_message.html.erb

@@ -0,0 +1,7 @@
+<div class="message">
+  <h1>(Shibbolite) Logged out</h1>
+  <p>
+    You MUST close your browser to
+    complete the logout process.
+  </p>
+</div>

data/config/routes.rb

@@ -0,0 +1,6 @@
+Shibbolite::Engine.routes.draw do
+  get 'login',          to: 'shibboleth#login'
+  get 'logout',         to: 'shibboleth#logout'
+  get 'logout_message', to: 'shibboleth#logout_message'
+  get 'access_denied',  to: 'shibboleth#access_denied'
+end

data/lib/generators/shibbolite/install_generator.rb

@@ -0,0 +1,17 @@
+module Shibbolite
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("../../templates", __FILE__)
+
+      desc 'Creates the shibbolite_config.rb initializer and mounts the Shibbolite engine'
+
+      def create_initializer
+        copy_file 'shibbolite_config.rb', 'config/initializers/shibbolite_config.rb'
+      end
+
+      def mount_engine
+        route "mount Shibbolite::Engine => '/shibbolite'"
+      end
+    end
+  end
+end

data/lib/generators/shibbolite/migration_generator.rb

@@ -0,0 +1,14 @@
+module Shibbolite
+  module Generators
+    class MigrationGenerator < Rails::Generators::Base
+      source_root File.expand_path("../../templates", __FILE__)
+
+      desc "Creates the migration to add shibboleth attributes to the main app's User class"
+
+      def creat_migration
+        generate "migration AddShibbolethAttributesTo#{Shibbolite.user_table_name} group:string" <<
+                     Shibbolite.attributes.collect { |attr| " #{attr}:string" }.join
+      end
+    end
+  end
+end

data/lib/generators/templates/shibbolite_config.rb

@@ -0,0 +1,51 @@
+# These configuration options must be set before Shibbolite
+# can be loaded. Mandatory settings are :attributes, :user_class,
+# and :primary_user_id. Depending on your environment you may
+# also have to change :handler_url, :session_initiator, or :logout_initiator
+# if they are different from the default values. Check with your SP's
+# shibboleth.xml configuration for the correct settings.
+Shibbolite.config do |c|
+
+  # any shibboleth attributes available in your environment that you want
+  # passed to your application.
+  c.attributes = [:eppn, :some_other_attribute]
+
+  # SP attribute used as a unique username
+  # typically this should be the same attribute that
+  # your SP uses to set the REMOTE_USER environment variable
+  # Use the getter alias Shibbolite.pid of you want to be concise
+  c.primary_user_id = :eppn
+
+  # The defaults for these options will work for most installations
+  # all options are listed with their default values, only uncomment
+  # if you need to change them
+
+  # friendly display name for views
+  # concise alias Shibbolite.pid_display is available too
+  #c.primary_user_id_display = 'Username'
+
+  # name of your application's User model
+  #c.user_class = 'User'
+
+  # used with the generated migration.
+  # Only override if your table doesn't follow
+  # normal pluralization or name conventions
+  #c.user_table_name = c.user_class.pluralize
+
+  # NativeSP base location
+  # used to construct urls to interact with SP
+  #c.handler_url = '/Shibboleth.sso'
+
+  # NativeSP handler location for starting sessions
+  #c.session_initiator = '/Login'
+
+  # NativeSP handler location for logging out
+  #c.logout_initiator = '/Logout'
+
+  # the types of groups to assign users
+  #c.groups = [:user, :admin]
+
+  # setting to true will skip including validations
+  # from the Shibbolite::User class
+  #c.skip_validations = false
+end

data/lib/shibbolite/engine.rb

@@ -0,0 +1,13 @@
+module Shibbolite
+  class Engine < ::Rails::Engine
+    isolate_namespace Shibbolite
+
+    config.generators do |g|
+      g.test_framework      :rspec,        :fixture => false
+      g.fixture_replacement :factory_girl, :dir => 'spec/factories'
+      g.assets false
+      g.helper false
+    end
+
+  end
+end

data/lib/shibbolite/version.rb

@@ -0,0 +1,3 @@
+module Shibbolite
+  VERSION = "0.0.1"
+end

data/lib/shibbolite.rb

@@ -0,0 +1,58 @@
+require "shibbolite/engine"
+
+module Shibbolite
+
+  # shibboleth attributes available in the environment
+  mattr_accessor :attributes
+
+  # shibboleth primary key
+  mattr_accessor :primary_user_id
+
+  mattr_accessor :primary_user_id_display
+  @@primary_user_id_display = 'Username'
+
+  # groups available to assign to users
+  mattr_accessor :groups
+  @@groups = [:user, :admin]
+
+  # the parent application's User model
+  mattr_accessor :user_class
+  @@user_class = 'User'
+
+  def self.user_class
+    @@user_class.constantize
+  end
+
+  mattr_accessor :user_table_name
+  @@user_table_name = @@user_class.pluralize
+
+  mattr_accessor :skip_validations
+  @@skip_validations = false
+
+  # NativeSP base location
+  mattr_accessor :handler_url
+  @@handler_url = '/Shibboleth.sso'
+
+  # NativeSP handler location for starting sessions
+  mattr_accessor :session_initiator
+  @@session_initiator = '/Login'
+
+  # NativeSP handler location for logging out
+  mattr_accessor :logout_initiator
+  @@logout_initiator = '/Logout'
+
+  # shortened/alternate accessors
+
+  def self.pid
+    primary_user_id
+  end
+
+  def self.pid_display
+    primary_user_id_display
+  end
+
+  # friendly config
+  def self.config
+    yield self
+  end
+end

data/spec/controllers/filters_test_controller_spec.rb

@@ -0,0 +1,146 @@
+require 'spec_helper'
+
+# a dummy controller used to test the Shibbolite::Filters concern
+
+describe FiltersTestController do
+
+  # presume the session has been loaded
+  before { allow(subject).to receive(:load_session) }
+
+  describe '#require_login' do
+
+    context 'when logged in' do
+      it 'allows the action to continue' do
+        allow(subject).to receive(:logged_in?).and_return(true)
+        get :_require_login
+        expect(response).to render_template(:dummy)
+      end
+
+    end
+
+    context 'when not logged in' do
+      it 'redirects' do
+        allow(subject).to receive(:logged_in?).and_return(false)
+        get :_require_login
+        expect(response).to redirect_to('/shibbolite/login')
+      end
+    end
+  end
+
+  describe '#require_registered' do
+
+    context 'when user is registered' do
+      it 'allows the action to continue' do
+        allow(subject).to receive(:registered_user?).and_return(true)
+        get :_require_registered
+        expect(response).to render_template(:dummy)
+      end
+    end
+
+    context 'when the user is not registered' do
+      it 'redirects' do
+        allow(subject).to receive(:registered_user?).and_return(false)
+        get :_require_registered
+        expect(response).to redirect_to('/shibbolite/login')
+      end
+    end
+  end
+
+  describe '#use_attributes_if_available' do
+
+    context 'when the user authenticated but login isn\'t required' do
+      it 'redirects to login to load the session' do
+        allow(subject).to receive(:logged_in?).and_return(false)
+        request.env[Shibbolite.pid.to_s] = 'not nil'
+        get :_use_attributes_if_available
+        expect(response).to redirect_to('/shibbolite/login')
+      end
+    end
+
+    context 'when the user did not authenticate' do
+      it 'allows the action' do
+        get :_use_attributes_if_available
+        expect(response).to render_template(:dummy)
+      end
+    end
+  end
+
+  context 'filters that require a user object' do
+
+    let!(:user_id)  { 17 }
+    let!(:admin_id) { 1 }
+    let(:guest) { double('guest', id: nil,      group: nil )}
+    let(:user)  { double('user' , id: user_id,  group: 'user')}
+    let(:admin) { double('admin', id: admin_id, group: 'admin' )}
+
+    describe '#require_group' do
+
+      context 'when the user has a group listed' do
+        it 'allows the action to continue' do
+          allow(subject).to receive(:current_user).and_return(user)
+          get :_require_group, groups: ['user', 'admin']
+          expect(response).to render_template(:dummy)
+        end
+      end
+
+      context 'when the user is not a member' do
+        it 'redirects' do
+          allow(subject).to receive(:current_user).and_return(guest)
+          get :_require_group, groups: ['user', 'admin']
+          expect(response).to redirect_to('/shibbolite/login')
+        end
+      end
+    end
+
+    describe '#require_id' do
+
+      context 'when the user has the id listed' do
+        it 'allows the action to continue' do
+          allow(subject).to receive(:current_user).and_return(admin)
+          get :_require_id, id: admin_id
+          expect(response).to render_template(:dummy)
+        end
+      end
+
+      context 'when the user does not have the id' do
+        it 'redirects' do
+          allow(subject).to receive(:current_user).and_return(guest)
+          get :_require_id, id: user_id
+          expect(response).to redirect_to('/shibbolite/login')
+        end
+      end
+    end
+
+    describe '#require_group_or_id' do
+
+      context 'happy paths' do
+
+        it 'allows action with matching id' do
+          allow(subject).to receive(:current_user).and_return(user)
+          get :_require_group_or_id, groups: 'admin', id: user_id
+          expect(response).to render_template(:dummy)
+        end
+
+        it 'allows action with matching group' do
+          allow(subject).to receive(:current_user).and_return(user)
+          get :_require_group_or_id, groups: 'user', id: admin_id
+          expect(response).to render_template(:dummy)
+        end
+
+        it 'allows action with both id and group matching' do
+          allow(subject).to receive(:current_user).and_return(admin)
+          get :_require_group_or_id, groups: 'admin', id: admin_id
+          expect(response).to render_template(:dummy)
+        end
+      end
+
+      context 'with no matching criteria' do
+        it 'redirects' do
+          allow(subject).to receive(:current_user).and_return(guest)
+          get :_require_group_or_id, groups: 'user', id: user_id
+          expect(response).to redirect_to('/shibbolite/login')
+        end
+      end
+    end
+  end
+end