g5_authenticatable 0.4.2 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d7098ea50ca9cdaa0ffefa42a0fe47d45fb087b1
-  data.tar.gz: ff8f79d3caa16d549db587bd9b01db5038e701a1
+  metadata.gz: 636e93c7a2f6114bba1839103deb438f1d713098
+  data.tar.gz: b5d0f845a01f7a80521650e1604254940ca35992
 SHA512:
-  metadata.gz: 437258a28abe7308db839bf6c2c64257b45bcf7f74fae81d5502dc46fb414ba9dd1ca81c2f240b753f87a496c833523e405db27d589944072585b79b8c913869
-  data.tar.gz: f9747b13d67c6559d8df0e74498a62fc2cd3722d59e6eeb55ecfba1bde51a36601930b30885f6f0baddd5bbbf892bcbfc62ba9e65632f97e97fc380f27b19013
+  metadata.gz: d934f79a4045ecc1b3ca42a81e36582ef0ede8d1c23250783d7c128683c4da1b4c76aab81c19ef890b78d4a321326d0cfba1735dbd86243f32e62b05a3f78ad0
+  data.tar.gz: 465efb38e1da5eb37bec731666840d1b36245dd168f63299a1f297024a6a4cab6d88c367f2e7966b9096eed6c48f07dcacf5c66d0558428036161c590cf825b0

data/.travis.yml

@@ -0,0 +1,12 @@
+language: ruby
+rvm:
+  - 2.1.2
+script:
+  - RAILS_ENV=test bundle exec rake app:db:setup
+  - bundle exec rspec spec
+before_script:
+  - cp spec/dummy/config/database.yml.ci spec/dummy/config/database.yml
+  - psql -c 'create database g5_authenticatable_test;' -U postgres
+env:
+  global:
+    - DEVISE_SECRET_KEY=foo

data/CHANGELOG.md

@@ -1,3 +1,14 @@
+## v0.5.0 (2015-05-21)
+
+* Added user roles. Requires running `rails g5 g5_authenticatable:install` and
+  `rake db:migrate`
+  ([#33](https://github.com/G5/g5_authenticatable/pull/33))
+* Added user attributes. Requires running `rails g g5_authenticatable:install`
+  and `rake db:migrate`
+  ([#32](https://github.com/G5/g5_authenticatable/pull/32))
+* Updated documentation around test helper dependencies and incompatibilities
+  ([#30](https://github.com/G5/g5_authenticatable/pull/30))
+
 ## v0.4.2 (2015-02-10)
 
 * Override `Devise::FailureApp` with fix for compatibility with Rails 4.2

data/Gemfile

@@ -12,8 +12,8 @@ gem 'pg'
 gem 'grape'
 
 group :test, :development do
-  gem 'rspec-rails', '~> 2.99'
-  gem 'pry'
+  gem 'rspec-rails', '~> 3.1'
+  gem 'pry-byebug'
   gem 'dotenv-rails'
   gem 'web-console', '~> 2.0'
 end

data/README.md

@@ -18,7 +18,7 @@ library in isolation.
 
 ## Current Version
 
-0.4.2
+0.5.0
 
 ## Requirements
 
@@ -258,12 +258,197 @@ Authorization header, or in a request parameter named `access_token`.
 For more details, see the documentation for
 [g5_authenticatable_api](https://github.com/G5/g5_authenticatable_api).
 
+### Authorization ###
+
+#### User Roles ####
+
+User roles are defined on the auth server and automatically populated in the local
+model layer when a user logs in:
+
+```ruby
+current_user.roles
+# => #<ActiveRecord::Associations::CollectionProxy [#<G5Authenticatable::Role id: 1, name: "viewer", ...>]>
+```
+
+We use [rolify](https://github.com/RolifyCommunity/rolify) for role management,
+which provides an interface for querying role assignments:
+
+```ruby
+current_user.has_role?(:editor)
+```
+
+G5 currently supports four different roles: `:super_admin`, `:admin`,
+`:editor`, and `:viewer` (the default role).
+
+#### Policies and Scopes ####
+
+G5 Authenticatable uses [pundit](https://github.com/elabs/pundit) to encapsulate
+the authorization logic in policy objects. The pundit documentation contains a much
+more thorough explanation of how to define and use policies, but a quick overview
+is provided here.
+
+The G5 Authenticatable generator created an `app/policies/application_policy.rb`
+file in your project:
+
+```ruby
+class ApplicationPolicy < G5Authenticatable::BasePolicy
+  class Scope < BaseScope
+  end
+end
+```
+
+The `G5Authenticatable::BasePolicy` and `G5Authenticatable::BasePolicy::BaseScope`
+implement a set of default authorization rules that essentially forbids access
+to all actions on all model instances unless the user has the `:super_admin`
+role. It also provides a set of helper methods for checking user roles:
+`super_admin?`, `admin?`, `editor?`, or `viewer?`.
+
+In order to implement a custom policy for one of your application's models, you
+can create a new policy in the `app/policies` directory. For instance, if you
+have a `Widget` model, and you want to also grant permissions to update that
+model to users with `:admin` or `:editor` roles:
+
+```ruby
+# app/policies/widget_policy.rb
+
+class WidgetPolicy < ApplicationPolicy
+  def update?
+    super_admin? || admin? || editor?
+  end
+end
+```
+
+You also have access to the record being authorized, and can define rules based
+on that. For instance, if you want to restrict `Widget` deletion based on both
+user role and some flag on the `Widget` instance to be deleted:
+
+```ruby
+# app/policies/widget_policy.rb
+
+class WidgetPolicy < ApplicationPolicy
+  def destroy?
+    (super_admin? || admin?) && !record.published?
+  end
+end
+```
+
+In order to implement data-level authorization, you can define a custom scope
+within your policy. The scope `resolve` method should only return the records
+to which the current user has access. You have access to the current `user` and
+also the `scope` object (defaults to the record class). For instance, if a user
+must be the owner of a widget in order to access it, but super admins are allowed
+to access all widgets:
+
+```ruby
+# app/policies/widget_policy.rb
+
+class WidgetPolicy < ApplicationPolicy
+  class Scope < Scope
+    def resolve
+      if user.has_role?(:super_admin?)
+        scope.all
+      else
+        scope.where(owner_id: user.id)
+      end
+    end
+  end
+end
+```
+
+If you want to apply the same authorization logic across all models in your
+application, you can define them in `ApplicationPolicy` or
+`ApplicationPolicy::Scope`.
+
+#### Using Policies in Controllers ####
+
+You can use the `authorize` method in your controller to ensure that the
+current user has access to the current action on a particular model instance.
+For instance, in your controller:
+
+```ruby
+class WidgetsController < ApplicationController
+  # ...
+
+  def update
+    @widget = Widget.find(params[:id])
+    authorize(@widget)
+
+    if @widget.update_attributes(widget_params)
+      flash[:notice] = "Widget successfully updated."
+    end
+
+    respond_with(@widget)
+  end
+end
+```
+
+In this example, the `authorize` method will automatically lookup the correct policy
+and populate it with the `current_user` and the model argument, and then call the
+`update?` method on it, based on the current action name.
+
+You can directly access the policy scope to look up the records to which the
+current user has access by using the `policy_scope` method:
+
+```ruby
+class WidgetsController < ApplicationController
+  # ...
+
+  def index
+    @widgets = policy_scope(Widget)
+  end
+```
+
+In this example, the `policy_scope` method will automatically look up the
+`WidgetPolicy::Scope`, populate it with the current user and `Widget` record
+class, and call the scope `resolve` method to retrieve the results.
+
+#### Using Policies in Views ####
+
+Sometimes, you want to be able to access authorization logic inside Rails views.
+For instance, you may want to hide the link to edit a record if the user does
+not have access to update that record. In these cases, you can use the `policy`
+method to lookup the instance of the policy directly:
+
+```erb
+<% if policy(@widget).update? %>
+  <%= link_to 'Edit', edit_widget_path(@widget) %>
+<% end %>
+```
+
+You can also call the `policy_scope` method inside views.
+
+If you are not rendering your views within your Rails application (for
+instance, if you are using an Ember front-end), then you will have to build
+your own API for querying policy information in order to access this
+functionality directly in your view.
+
 ### Test Helpers ###
 
 G5 Authenticatable currently only supports [rspec-rails](https://github.com/rspec/rspec-rails).
 Helpers and shared contexts are provided for integration testing secure pages
 and API methods.
 
+#### Prerequisites ####
+
+Because the test helpers are optional, bundler will not automatically install
+these dependencies. You will have to add the following gems to your own Gemfile:
+
+* [rspec-rails](https://github.com/rspec/rspec-rails)
+* [factory_girl_rails](https://github.com/thoughtbot/factory_girl_rails)
+* [webmock](https://github.com/bblimke/webmock)
+
+#### Incompatibilities ####
+
+There are [known issues](https://github.com/G5/g5_authenticatable/issues/27) using the
+auth test helpers with [selenium-webdriver](http://docs.seleniumhq.org/projects/webdriver/)
+and the Firefox browser. As such, selenium-webdriver is not officially supported by
+the G5 Authenticatable library.
+
+If you are using [capybara](https://github.com/jnicklas/capybara) to run your
+integration tests, we highly recommend using
+[poltergeist](https://github.com/teampoltergeist/poltergeist) for PhantomJS as
+your javascript driver instead.
+
 #### Installation ####
 
 To automatically mix in helpers to your feature and request specs, include the

data/app/controllers/concerns/g5_authenticatable/authorization.rb

@@ -0,0 +1,21 @@
+module G5Authenticatable
+  module Authorization
+    extend ActiveSupport::Concern
+
+    included do
+      include Pundit
+      rescue_from Pundit::NotAuthorizedError, with: :user_not_authorized
+    end
+
+    def user_not_authorized
+      respond_to do |format|
+        format.json do
+          render status: :forbidden, json: {error: 'Access forbidden'}
+        end
+        format.html do
+          render status: :forbidden, file: "#{Rails.root}/public/403"
+        end
+      end
+    end
+  end
+end

data/app/models/g5_authenticatable/role.rb

@@ -0,0 +1,8 @@
+module G5Authenticatable
+  class Role < ActiveRecord::Base
+    has_and_belongs_to_many :users, :join_table => :g5_authenticatable_users_roles
+    belongs_to :resource, :polymorphic => true
+
+    scopify
+  end
+end

data/app/models/g5_authenticatable/user.rb

@@ -1,8 +1,49 @@
 module G5Authenticatable
   class User < ActiveRecord::Base
     devise :g5_authenticatable, :trackable, :timeoutable
+    rolify role_cname: 'G5Authenticatable::Role',
+           role_join_table_name: :g5_authenticatable_users_roles
 
     validates :email, presence: true, uniqueness: true
     validates_uniqueness_of :uid, scope: :provider
+
+    def self.new_with_session(params, session)
+      user = super(params, session)
+      auth_data = session['omniauth.auth']
+
+      if auth_data
+        user.assign_attributes(extended_auth_attributes(auth_data))
+        user.update_roles_from_auth(auth_data)
+      end
+
+      user
+    end
+
+    def self.find_and_update_for_g5_oauth(auth_data)
+      user = super(auth_data)
+
+      if user
+        user.update_attributes(extended_auth_attributes(auth_data))
+        user.update_roles_from_auth(auth_data)
+      end
+
+      user
+    end
+
+    def update_roles_from_auth(auth_data)
+      roles.clear
+      auth_data.extra.roles.each { |role| add_role(role.name) }
+    end
+
+    private
+    def self.extended_auth_attributes(auth_data)
+      {
+        first_name: auth_data.info.first_name,
+        last_name: auth_data.info.last_name,
+        phone_number: auth_data.info.phone,
+        title: auth_data.extra.title,
+        organization_name: auth_data.extra.organization_name
+      }
+    end
   end
 end

data/app/policies/g5_authenticatable/base_policy.rb

@@ -0,0 +1,73 @@
+class G5Authenticatable::BasePolicy
+  attr_reader :user, :record
+
+  def initialize(user, record)
+    @user = user
+    @record = record
+  end
+
+  def index?
+    super_admin?
+  end
+
+  def show?
+    scope.where(:id => record.id).exists?
+  end
+
+  def create?
+    super_admin?
+  end
+
+  def new?
+    create?
+  end
+
+  def update?
+    super_admin?
+  end
+
+  def edit?
+    update?
+  end
+
+  def destroy?
+    super_admin?
+  end
+
+  def scope
+    Pundit.policy_scope!(user, record.class)
+  end
+
+  class BaseScope
+    attr_reader :user, :scope
+
+    def initialize(user, scope)
+      @user = user
+      @scope = scope
+    end
+
+    def resolve
+      if user.has_role?(:super_admin)
+        scope.all
+      else
+        scope.none
+      end
+    end
+  end
+
+  def super_admin?
+    user.present? && user.has_role?(:super_admin)
+  end
+
+  def admin?
+    user.present? && user.has_role?(:admin)
+  end
+
+  def editor?
+    user.present? && user.has_role?(:editor)
+  end
+
+  def viewer?
+    user.present? && user.has_role?(:viewer)
+  end
+end

data/config/initializers/rolify.rb

@@ -0,0 +1,8 @@
+Rolify.configure('G5Authenticatable::Role') do |config|
+  # By default ORM adapter is ActiveRecord. uncomment to use mongoid
+  # config.use_mongoid
+
+  # Dynamic shortcuts for User class (user.is_admin? like methods). Default is: false
+  # Enable this feature _after_ running rake db:migrate as it relies on the roles table
+  # config.use_dynamic_shortcuts
+end

data/g5_authenticatable.gemspec

@@ -21,5 +21,8 @@ Gem::Specification.new do |spec|
   spec.require_paths = ['lib']
 
   spec.add_dependency 'devise_g5_authenticatable', '~> 0.2'
+  spec.add_dependency 'omniauth-g5', '~> 0.2'
   spec.add_dependency 'g5_authenticatable_api', '~> 0.3.1'
+  spec.add_dependency 'rolify', '~> 4.0'
+  spec.add_dependency 'pundit', '~> 1.0'
 end

data/lib/g5_authenticatable/engine.rb

@@ -1,3 +1,6 @@
+require 'rolify'
+require 'pundit'
+
 module G5Authenticatable
   class Engine < ::Rails::Engine
     isolate_namespace G5Authenticatable

data/lib/g5_authenticatable/rspec.rb

@@ -4,3 +4,4 @@ require 'g5_authenticatable/test/token_validation_helpers'
 require 'g5_authenticatable/test/feature_helpers'
 require 'g5_authenticatable/test/request_helpers'
 require 'g5_authenticatable/test/controller_helpers'
+require 'pundit/rspec'

data/lib/g5_authenticatable/test/factory.rb

@@ -1,10 +1,60 @@
 require 'factory_girl_rails'
 
 FactoryGirl.define do
-  factory :g5_authenticatable_user, :class => 'G5Authenticatable::User' do
+  factory :g5_authenticatable_user, class: 'G5Authenticatable::User' do
     sequence(:email) { |n| "test.user#{n}@test.host" }
     provider 'g5'
     sequence(:uid) { |n| "abc123-#{n}" }
     sequence(:g5_access_token) { |n| "secret_token_#{n}" }
+    first_name 'Jane'
+    last_name 'Doe'
+    phone_number '(555) 867-5309'
+    title 'Minister of Funny Walks'
+    organization_name 'Department of Redundancy Department'
+
+    after(:build) do |user|
+      user.roles << FactoryGirl.build(:g5_authenticatable_viewer_role)
+    end
+  end
+
+  factory :g5_authenticatable_super_admin, parent: :g5_authenticatable_user do
+    after(:build) do |user|
+      user.roles.clear
+      user.roles << FactoryGirl.build(:g5_authenticatable_super_admin_role)
+    end
+  end
+
+  factory :g5_authenticatable_admin, parent: :g5_authenticatable_user do
+    after(:build) do |user|
+      user.roles.clear
+      user.roles << FactoryGirl.build(:g5_authenticatable_admin_role)
+    end
+  end
+
+  factory :g5_authenticatable_editor, parent: :g5_authenticatable_user do
+    after(:build) do |user|
+      user.roles.clear
+      user.roles << FactoryGirl.build(:g5_authenticatable_editor_role)
+    end
+  end
+
+  factory :g5_authenticatable_role, class: 'G5Authenticatable::Role' do
+    sequence(:name) { |n| "role_#{n}" }
+  end
+
+  factory :g5_authenticatable_super_admin_role, parent: :g5_authenticatable_role do
+    name 'super_admin'
+  end
+
+  factory :g5_authenticatable_admin_role, parent: :g5_authenticatable_role do
+    name 'admin'
+  end
+
+  factory :g5_authenticatable_editor_role, parent: :g5_authenticatable_role do
+    name 'editor'
+  end
+
+  factory :g5_authenticatable_viewer_role, parent: :g5_authenticatable_role do
+    name 'viewer'
   end
 end

data/lib/g5_authenticatable/test/feature_helpers.rb

@@ -5,8 +5,21 @@ module G5Authenticatable
         OmniAuth.config.mock_auth[:g5] = OmniAuth::AuthHash.new({
           uid: user.uid,
           provider: 'g5',
-          info: {email: user.email},
-          credentials: {token: user.g5_access_token}
+          info: {
+            email: user.email,
+            first_name: user.first_name,
+            last_name: user.last_name,
+            phone: user.phone_number
+          },
+          credentials: {token: user.g5_access_token},
+          extra: {
+            title: user.title,
+            organization_name: user.organization_name,
+            roles: user.roles.collect do |role|
+              {name: role.name}
+            end,
+            raw_info: {}
+          }
         }.merge(options))
       end
 

data/lib/g5_authenticatable/version.rb

@@ -1,3 +1,3 @@
 module G5Authenticatable
-  VERSION = '0.4.2'
+  VERSION = '0.5.0'
 end

data/lib/generators/g5_authenticatable/install/USAGE

@@ -1,11 +1,17 @@
 Description:
-    Installs the g5_authenticatable engine
+    Installs/updates the g5_authenticatable engine
 
 Example:
     rails generate g5_authenticatable:install
 
     This will create:
+        app/policies/application_policy.rb
+        config/initializers/g5_authenticatable.rb
         db/migrate/create_g5_authenticatable_users.rb
+        db/migrate/add_g5_authenticatable_users_contact_info.rb
+        db/migrate/create_g5_authenticatable_roles.rb
+        public/403.html
 
     This will modify:
+        app/controllers/application_controller.rb
         config/routes.rb

data/lib/generators/g5_authenticatable/install/install_generator.rb

@@ -9,16 +9,43 @@ class G5Authenticatable::InstallGenerator < Rails::Generators::Base
     ActiveRecord::Migration.next_migration_number(next_migration_number)
   end
 
-  def create_users_migration
-    filename = 'create_g5_authenticatable_users.rb'
-    migration_template filename, "db/migrate/#{filename}"
-  end
-
   def mount_engine
     route "mount G5Authenticatable::Engine => '/g5_auth'"
   end
 
   def create_initializer
-    template 'g5_authenticatable.rb', 'config/initializers/g5_authenticatable.rb'
+    template 'initializer.rb', 'config/initializers/g5_authenticatable.rb'
+  end
+
+  def create_users_migration
+    copy_migration('create_g5_authenticatable_users')
+  end
+
+  def users_contact_info_migration
+    copy_migration('add_g5_authenticatable_users_contact_info')
+  end
+
+  def create_roles_migration
+    copy_migration('create_g5_authenticatable_roles')
+  end
+
+  def include_authorization
+    inject_into_file 'app/controllers/application_controller.rb',
+      after: "class ApplicationController < ActionController::Base\n" do
+      "  include G5Authenticatable::Authorization\n"
+    end
+  end
+
+  def create_application_policy
+    template 'application_policy.rb', 'app/policies/application_policy.rb'
+  end
+
+  def create_403_error_page
+    template '403.html', 'public/403.html'
+  end
+
+  private
+  def copy_migration(name)
+    migration_template "migrate/#{name}.rb", "db/migrate/#{name}.rb"
   end
 end

data/lib/generators/g5_authenticatable/install/templates/403.html

@@ -0,0 +1,26 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Access forbidden (403)</title>
+  <style type="text/css">
+    body { background-color: #fff; color: #666; text-align: center; font-family: arial, sans-serif; }
+    div.dialog {
+      width: 25em;
+      padding: 0 4em;
+      margin: 4em auto 0 auto;
+      border: 1px solid #ccc;
+      border-right-color: #999;
+      border-bottom-color: #999;
+    }
+    h1 { font-size: 100%; color: #f00; line-height: 1.5em; }
+  </style>
+</head>
+
+<body>
+  <!-- This file lives in public/403.html -->
+  <div class="dialog">
+    <h1>Access forbidden</h1>
+    <p>You do not have permission to access this page.</p>
+  </div>
+</body>
+</html>

data/lib/generators/g5_authenticatable/install/templates/application_policy.rb

@@ -0,0 +1,4 @@
+class ApplicationPolicy < G5Authenticatable::BasePolicy
+  class Scope < BaseScope
+  end
+end

data/lib/generators/g5_authenticatable/install/templates/migrate/add_g5_authenticatable_users_contact_info.rb

@@ -0,0 +1,11 @@
+class AddG5AuthenticatableUsersContactInfo < ActiveRecord::Migration
+  def change
+    change_table(:g5_authenticatable_users) do |t|
+      t.string :first_name
+      t.string :last_name
+      t.string :phone_number
+      t.string :title
+      t.string :organization_name
+    end
+  end
+end

data/lib/generators/g5_authenticatable/install/templates/migrate/create_g5_authenticatable_roles.rb

@@ -0,0 +1,20 @@
+class CreateG5AuthenticatableRoles < ActiveRecord::Migration
+  def change
+    create_table(:g5_authenticatable_roles) do |t|
+      t.string :name
+      t.references :resource, :polymorphic => true
+
+      t.timestamps
+    end
+
+    create_table(:g5_authenticatable_users_roles, :id => false) do |t|
+      t.references :user
+      t.references :role
+    end
+
+    add_index(:g5_authenticatable_roles, :name)
+    add_index(:g5_authenticatable_roles, [ :name, :resource_type, :resource_id ],
+              name: 'index_g5_authenticatable_roles_on_name_and_resource')
+    add_index(:g5_authenticatable_users_roles, [ :user_id, :role_id ])
+  end
+end