balrog 1.1.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 232b0520af207a4da00798bba32874e5ef4ee33c55419793c7ec23e8312c5712
-  data.tar.gz: 4fc0f719261215f6b2c657f4d2a1964df096d92b67cf2b94f1585ec99a609b94
+  metadata.gz: ed08c9a6aa5d68fc2c81f784ea2bd330353c64a1e8ee8729acc6dc65fa4e0da2
+  data.tar.gz: 826d7ab7ed00637b9ac8642b44b93909b727bd2ae0971a872fab695d96d9f677
 SHA512:
-  metadata.gz: 4521321149b2a0636694f064e43cb20e8416c8eb2f93fd90668195d82a68dfd17bca183618664049139428dec095e7a74f1754b0b66a650d71d3d78610a91806
-  data.tar.gz: 4d7fbda793ea374006246abae4c9f1aa62b9369972e33f94aa090a152c799a2800d0081b29ec65a1a8d9a1b2a351f11bfe7ce9a85a47ff0637b54b769a707e69
+  metadata.gz: 0c0577f269883d820021d35af147e6746868c1dd20581d25919e9f3938657bc780571ae5978f13d8c7caea91baf63c39539271b2cffbbf3f2d306eef7b911120
+  data.tar.gz: 884d62c762f25c50c562d190d93452438680b33607cd53d4dd50921a2c9fa13419e1aae2ccd5cfeb8b34f9f2582ab4348e87b53961f853c441f2607df3d04fd7

data/CHANGELOG.md

@@ -1,5 +1,16 @@
+# 2.0.0
+
+- Enhancements
+  - added support for single sign-on.
+
+- BREAKING
+  - Balrog can no longer be initialized via `Rails.application.config.middleware.use Balrog::Middleware`. Instead, you need to configure Balrog with `Balrog::Middleware.setup`. See the [README](https://github.com/pixielabs/balrog#Upgrading-from-1.1-to-2.0) for more info.
+  - The instance method `Balrog::Middleware#password_hash` has been converted into a class method `Balrog::Middleware.set_password_hash`. See the [README](https://github.com/pixielabs/balrog#Upgrading-from-1.1-to-2.0) for more info.
+  - The instance method `Balrog::Middleware#set_session_expiry` has been converted into a class method `Balrog::Middleware.set_session_expiry`. See the [README](https://github.com/pixielabs/balrog#Upgrading-from-1.1-to-2.0) for more info.
+
 # 1.1.0
-- added `Balrog::Middleware#session_expires_after`, which would force end users to login again after a certain period of time.
+
+- added `Balrog::Middleware#set_session_expiry`, which would force end users to login again after a certain period of time.
 - added `balrog:view` generator, enabling users to modify their Balrog gate view.
 
 # 1.0.0

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    balrog (1.1.0)
+    balrog (2.0.0)
       bcrypt (~> 3.0)
       rails (>= 5)
 

data/README.md

@@ -6,17 +6,31 @@
 [![CircleCI](https://circleci.com/gh/pixielabs/balrog.svg?style=svg)](https://circleci.com/gh/pixielabs/balrog)
 
 Balrog is a lightweight authorization library for Ruby on Rails >= 5 written by
-[Pixie Labs](https://pixielabs.io) that can protect your routes with a single
-username & password combination.
-
-Balrog is an alternative to `http_basic_authentication_with` that provides some
-advantages:
-
-* Uses a password hash instead of a plaintext password.
-* Provides a lightweight HTML form instead of inconsistent basic
-  authentication.
-* Better support for password managers (which often don't support basic
-  authentication dialog boxes).
+[Pixie Labs](https://pixielabs.io) that can protect your routes. Balrog can be 
+configured to authorize users using a simple password or single sign-on or both.
+
+- If you choose to protect your routes with a password, the password will be 
+ stored as a password hash, not plain text, and Balrog provides a lightweight 
+ HTML form that can be styled and used with password managers.
+- If you choose to configure Balrog to use SSO, you can whitelist multiple email 
+domains, allowing groups of users access parts of your app, without circulating
+a password.
+- Balrog's authentication can and should be configured to expire, requiring 
+users to sign-in again in accordance with [OWASP](https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html#session-expiration) best practices.
+- Balrog can also be used to restrict access to [mounted Rack applications](#Restricting-access-to-mounted-Rack-applications-within-config/routes.rb) like Sidekiq.
+
+## Table of Contents
+
+- [Installation](#Installation)
+- [Regenerating a password hash](#Regenerating-a-password-hash)
+- [Restricting access in a controller](#Restricting-access-in-a-controller)
+- [Restricting access to mounted Rack applications](#Restricting-access-to-mounted-Rack-applications-within-config/routes.rb)
+- [Logout button](#Logout-button)
+- [Changing session expiry length](#Changing-session-expiry-length)
+- [Configuring the Balrog gate view](#Configuring-the-Balrog-gate-view)
+- [Single Sign On](#Single-Sign-On)
+- [Upgrading from 1.1 to 2.0](#Upgrading-from-1.1-to-2.0)
+- [Contributing](#Contributing)
 
 ## Installation
 
@@ -120,11 +134,12 @@ If you don't want sessions to expire, remove `set_session_expiry`
 from the initializer completely.
 
 ```ruby
-Rails.application.config.middleware.use Balrog::Middleware do
-  password_hash '$2a$12$BLz7XCFdG9YfwL64KlTgY.T3FY55aQk8SZEzHfpHfw15F2uN1kuSi'
-  set_session_expiry 30.minutes
+Balrog::Middleware.setup do |config|
+  config.password_hash '$2a$12$BLz7XCFdG9YfwL64KlTgY.T3FY55aQk8SZEzHfpHfw15F2uN1kuSi'
+  config.set_session_expiry 30.minutes
 end
 ```
+
 ## Configuring the Balrog gate view
 
 We built Balrog to have a default view and stylesheet so that you can drop 
@@ -145,6 +160,62 @@ After running the generator, you can now add elements and classes to the
 `app/views/layouts/balrog.html.erb`. For an example, see the 
 [dummy-rails-app](https://github.com/pixielabs/balrog/tree/master/spec/dummy-rails-app) in the spec folder.
 
+## Single Sign On
+
+To add single sign on you will need to add the [omniauth gem](https://github.com/omniauth/omniauth)
+to your gem file, along with the omniauth gem for your chosen
+[provider](https://github.com/omniauth/omniauth/wiki/List-of-Strategies).
+
+In `config/initializers/balrog.rb`, call `config.set_omniauth` in the setup block.
+`.set_omniauth` takes the same arguments as the `OmniAuth::Builder#provider`
+[method](https://github.com/omniauth/omniauth#getting-started),
+a provider and any required keys.
+
+To whitelist any email addresses with a specific domain, call
+`config.set_domain_whitelist`in the setup block and pass in the domain.
+If you want to whitelist multiple domains, you can pass multiple domains
+to the `.set_domain_whitelist`.
+
+Balrog does not require a password to be set if you wish to use single sign-on only. 
+
+```ruby
+Balrog::Middleware.setup do |config|
+  credentials = Rails.application.credentials
+  config.set_omniauth :google_oauth2, credentials.google_client_id, credentials.google_client_secret
+  config.set_domain_whitelist 'pixielabs.io', 'the_fellowship.com'
+end
+```
+**Please note:** there is currently a CSRF vulnerability which affects OmniAuth 
+(designated [CVE-2015-9284](https://nvd.nist.gov/vuln/detail/CVE-2015-9284)) 
+that requires mitigation at the application level. More details on how to do 
+this can be found on the [Omniauth Wiki](https://github.com/omniauth/omniauth/wiki/Resolving-CVE-2015-9284).
+
+## Upgrading from 1.1 to 2.0
+
+To upgrade, you will need to change your Balrog initializer. 
+
+1. Instead of calling `Rails.application.config.middleware.use Balrog::Middleware`, you will now need to call `Balrog::Middleware.setup`. 
+
+2. Change the block you pass into these methods. `#password_hash` and `#set_session_expiry` now need to called on a block parameter, e.g `set_session_expiry 30.minutes` needs to be changed to `config.set_session_expiry 30.minutes`.
+
+See below for code examples.
+
+```ruby
+# Balrog 1.1
+Rails.application.config.middleware.use Balrog::Middleware do
+  password_hash '$2a$12$I8Fp3e2GfSdM7KFyoMx56.BVdHeeyk9DQWKkdsxw7USvU/mC8a8.q'
+  set_session_expiry 30.minutes
+end
+```
+
+```ruby
+# Balrog 2.0
+Balrog::Middleware.setup do |config|
+  config.set_password_hash '$2a$12$9lquJW6mVYYS1pD1xYMGzulyC6sEDuLIUfkA/Y7F3RQ8psLNYyLeO'
+  config.set_session_expiry 30.minutes
+end
+```
+
 ## Contributing
 
 ### Running the tests
@@ -169,7 +240,6 @@ Before contributing, please read the [code of conduct](CODE_OF_CONDUCT.md).
   want to have your own version, or is otherwise necessary, that is fine, but
   please isolate to its own commit so we can cherry-pick around it.
 
-
 ## TODO
 
  * Restricting access via `routes.rb`

data/app/assets/stylesheets/balrog/gate.css

@@ -27,8 +27,7 @@ footer {
   align-self: center;
 }
 
-button {
-  -webkit-appearance: button;
+.button_background {
   overflow: visible;
   text-transform: none;
   -webkit-transition-duration: 0.4s;
@@ -39,13 +38,25 @@ button {
   font-size: 20px;
   font-family: 'Helvetica Neue', 'Helvetica', Calibri, 'Trebuchet MS', sans-serif;
   cursor: pointer;
-  padding: 8px 10px;
   border: 0;
   font-weight: 100;
   letter-spacing: 1px;
+  margin: 5px 0px;
+}
+
+button {
+  -webkit-appearance: button;
+  padding: 8px 10px;
+}
+
+.sso_button {
+  display: inline-block;
+  text-decoration: none;
+  padding: 8px 0px;
+  width: 305.438px;
 }
 
-button:hover {
+button:hover, .sso_button:hover {
   background-color: rgb(201, 41, 41);
 }
 

data/app/views/balrog/gate.html.erb

@@ -1,6 +1,17 @@
 <section>
-  <form action='/balrog/signin' method='POST'>
-    <input autofocus type='password' name='password' placeholder='Password'>
-    <button type='submit'>Login</button>
-  </form>
+  <div>
+    <% if show_balrog_password_prompt? %>
+      <form action='/balrog/signin' method='POST'>
+        <input autofocus type='password' name='password' placeholder='Password'>
+        <button type='submit' class="button_background">Login</button>
+      </form>
+    <% end %>
+    <% if balrog_omniauth_configured? %>
+      <%= button_to(
+        "Sign in with SSO",
+        "/auth/#{Balrog::Middleware.omniauth_config[:provider]}",
+        class: 'button_background sso_button'
+      ) %>
+    <% end %>
+  </div>
 </section>

data/lib/balrog/engine.rb

@@ -22,4 +22,16 @@ class Balrog::Engine < Rails::Engine
       balrog/logo.png
     )
   end
+
+  # Insert Balrog into middleware stack.
+  initializer "Balrog.middleware", after: :load_config_initializers, before: :build_middleware_stack do |app|
+    # If OmniAuth configured, insert OmniAuth into middleware stack.
+    omniauth_config = Balrog::Middleware.omniauth_config
+    if omniauth_config
+      app.middleware.use OmniAuth::Builder do
+        provider omniauth_config[:provider], *omniauth_config[:args]
+      end
+    end
+    app.middleware.use Balrog::Middleware
+  end
 end

data/lib/balrog/generators/install_generator.rb

@@ -6,9 +6,9 @@ class Balrog::InstallGenerator < Rails::Generators::Base
   def create_initializer_file
     password_hash = PasswordHasher.encrypt_password
     contents = <<~EOF
-      Rails.application.config.middleware.use Balrog::Middleware do
-        password_hash '#{password_hash}'
-        set_session_expiry 30.minutes
+      Balrog::Middleware.setup do |config|
+        config.set_password_hash '#{password_hash}'
+        config.set_session_expiry 30.minutes
       end
     EOF
     create_file "config/initializers/balrog.rb", contents

data/lib/balrog/middleware.rb

@@ -1,4 +1,5 @@
 require 'bcrypt'
+require_relative 'middleware/controller'
 
 # Public: Balrog middleware that handles form submissions, checking the
 # password against the configured hash, and setting a session variable if
@@ -7,80 +8,73 @@ require 'bcrypt'
 # This is typically set up in an initialize when you run
 # `rails g balrog:install`, and looks a bit like this:
 #
-#    Rails.application.config.middleware.use Balrog::Middleware do
-#      password_hash '<bcrypt hash>'
-#    end
+#  Balrog::Middleware.setup do |config|
+#    config.set_password_hash '<bcrypt hash>'
+#  end
+
 class Balrog::Middleware
-  def initialize(app, &block)
+  include Controller
+
+  mattr_reader :password_hash
+  mattr_reader :session_length
+  mattr_reader :omniauth_config
+  mattr_reader :domain_whitelist
+
+  def initialize(app)
     @app = app
-    instance_eval(&block) if block_given?
   end
 
   def call(env)
     path = env["PATH_INFO"]
     method = env["REQUEST_METHOD"]
-    if method == 'POST' && path == '/balrog/signin'
-      handle_login(env)
-    elsif method == "DELETE" && path == '/balrog/logout'
-      handle_logout(env)
+    if login_request?(path, method)
+      password_login(env)
+    elsif omniauth_request?(path, method)
+      omniauthentication(env)
+    elsif logout_request?(path, method)
+      logout(env)
     else
       @app.call(env)
     end
   end
 
+  def self.setup
+    yield self
+  end
+
   private
 
-  def password_hash(input)
-    @password_hash = BCrypt::Password.new(input)
+  def self.set_password_hash(input)
+    @@password_hash = BCrypt::Password.new(input)
   end
 
-  def set_session_expiry(time_period)
-    @session_length = time_period
+  def self.set_omniauth(provider, *args)
+    @@omniauth_config = {
+      provider: provider,
+      args: args
+    }
   end
 
-  def handle_login(env)
-    if env['rack.request.form_hash']
-      submitted_password = env['rack.request.form_hash']['password']
-    end
-
-    unless submitted_password
-      return [302, {"Location" => referer}, [""]]
-    end
-
-    unless @password_hash
-      warn <<~EOF
-
-        !! Balrog has not been configured with a password_hash. You shall not
-        !! pass! When adding Balrog::Middleware to your middleware stack, pass
-        !! in a block and call `password_hash` passing in a bcrypt hash.
-        !!
-        !! Check out https://github.com/pixielabs/balrog for more information.
-
-      EOF
-    end
-
-    if @password_hash == submitted_password
-      session_data = { value: 'authenticated' }
-      add_expiry_date!(session_data)
-      env['rack.session'][:balrog] = session_data
-    end
+  def self.set_domain_whitelist(*domains)
+    @@domain_whitelist = domains
+  end
 
-    referer = env["HTTP_REFERER"] || '/'
+  def self.set_session_expiry(time_period)
+    @@session_length = time_period
+  end
 
-    [302, {"Location" => referer}, [""]]
+  def login_request?(path, method)
+    method == 'POST' && path == '/balrog/signin'
   end
 
-  def handle_logout(env)
-    env['rack.session'].delete(:balrog)
-    [302, {"Location" => '/'}, [""]]
+  def omniauth_request?(path, method)
+    omniauth_config &&
+      method == "GET" &&
+      path == "/auth/#{omniauth_config[:provider]}/callback"
   end
 
-  # If the user configured the Balrog session to expire, add the 
-  # expiry_date to the Balrog session.
-  def add_expiry_date!(session_data)
-    if @session_length
-      session_data[:expiry_date] = DateTime.current + @session_length
-    end
+  def logout_request?(path, method)
+    method == "DELETE" && path == '/balrog/logout'
   end
 end
 

data/lib/balrog/middleware/controller.rb

@@ -0,0 +1,106 @@
+# Methods that are called in response to specific application requests.
+class Balrog::Middleware
+  module Controller
+
+    # This method is called if a user attempts to sign in with a password
+    # and will authenticate the user if the password is correct.
+    def password_login(env)
+      # Extract the submitted_password from the rack request hash.
+      if env['rack.request.form_hash']
+        submitted_password = env['rack.request.form_hash']['password']
+      end
+
+      # If there is no submitted_password, redirect the user before authentication.
+      unless submitted_password
+        return [302, {"Location" => referer}, [""]]
+      end
+
+      # If there is no password_hash, alert the developer.
+      unless password_hash
+        warn <<~EOF
+
+          !! Balrog has not been configured with a password_hash. You shall not
+          !! pass! When adding Balrog::Middleware to your middleware stack, pass
+          !! in a block and call `password_hash` passing in a bcrypt hash.
+          !!
+          !! Check out https://github.com/pixielabs/balrog for more information.
+
+        EOF
+      end
+
+      # Authenticate the user if the submitted_password matches the password_hash.
+      if password_hash == submitted_password
+        authenticate_user(env)
+      end
+
+      referer = env["HTTP_REFERER"] || '/'
+
+      [302, {"Location" => referer}, [""]]
+    end
+
+
+    # This method is called if a user attempts to sign in with Single Sign-on
+    # and will authenticate the user if email domain has been whitelisted.
+    def omniauthentication(env)
+      # Extract the email domain from the omniauth hash.
+      if env['omniauth.auth']['info']['email']
+        user_email = env['omniauth.auth']['info']['email']
+        email_domain = user_email.split("@").last
+      end
+      
+      # If there is no email domain, redirect the user before authentication.
+      unless email_domain
+        return [302, {"Location" => referer}, [""]]
+      end
+
+      # If there is no domain_whitelist, alert the developer.
+      unless domain_whitelist
+        warn <<~EOF
+
+          !! Balrog has not been configured with a domain_whitelist. You shall not
+          !! pass! When setting up Balrog::Middleware, pass in a block and
+          !! call `set_domain_whitelist` passing in an omniauth provider and
+          !! required keys.
+          !!
+          !! Check out https://github.com/pixielabs/balrog for more information.
+
+        EOF
+        return [302, {"Location" => referer}, [""]]
+      end
+
+      # Authenticate the user if the user's email domain is whitelisted.
+      if domain_whitelist.include?(email_domain)
+        authenticate_user(env)
+      end
+
+      referer = env["omniauth.origin"] || '/'
+
+      [302, {"Location" => referer}, [""]]
+    end
+
+
+    # This method is called if a user logs out using a balrog logout button.
+    # It will achieve this by removing all balrog data from the session.
+    def logout(env)
+      env['rack.session'].delete(:balrog)
+      [302, {"Location" => '/'}, [""]]
+    end
+
+    private
+
+    # This method marks the user as 'authenicated'.
+    def authenticate_user(env)
+      session_data = { value: 'authenticated' }
+      add_expiry_date!(session_data)
+      env['rack.session'][:balrog] = session_data
+    end
+
+    # If the user configured the Balrog session to expire, add the 
+    # expiry_date to the Balrog session.
+    def add_expiry_date!(session_data)
+      if session_length
+        session_data[:expiry_date] = DateTime.current + session_length
+      end
+    end
+  end
+end

data/lib/balrog/version.rb

@@ -1,3 +1,3 @@
 module Balrog
-  VERSION = "1.1.0"
+  VERSION = "2.0.0"
 end

data/lib/balrog/view_helpers.rb

@@ -1,4 +1,4 @@
-# ViewHelpers methods are made available in all controllers by the code in engine.rb.
+# ViewHelpers methods are made available in all views by the code in engine.rb.
 module Balrog::ViewHelpers
   def balrog_logout_button(options = nil, html_options = nil)
     name = 'Logout'
@@ -13,4 +13,12 @@ module Balrog::ViewHelpers
 
     button_to(name, '/balrog/logout', html_options)
   end
+
+  def show_balrog_password_prompt?
+    !!Balrog::Middleware.password_hash || !Balrog::Middleware.omniauth_config
+  end
+
+  def balrog_omniauth_configured?
+    !!Balrog::Middleware.omniauth_config
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: balrog
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Pixie Labs
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-11-18 00:00:00.000000000 Z
+date: 2019-12-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bcrypt
@@ -114,6 +114,7 @@ files:
 - lib/balrog/guard.rb
 - lib/balrog/helpers.rb
 - lib/balrog/middleware.rb
+- lib/balrog/middleware/controller.rb
 - lib/balrog/password_hasher.rb
 - lib/balrog/rake_tasks.rb
 - lib/balrog/routes_middleware.rb