Rails engine providing MVCs for User, Group, Role, Membership and Authority


License
MIT
Install
gem install wobauth -v 6.0.1

Documentation

wobauth

Rails engine providing MVCs for Users, Roles, Groups, Authorities and Memberships to support authorization of the main application.

The User model is mostly coupled with your application, so Wobauth::User is open classed. You should overwrite it depending on your needs. See test/dummy/app/models/wobauth/user.rb for an example.

You have to build your own concrete authorization logic with cancancan or something similiar. The basic principle is always the same. A subject (user or group) has some rights (the role) on concret objects. The objects may be organizational units, sites, categories or something else whatever your application provides. The object may be nil if your application doesn't need this feature. The role define the rights dependent on your logic, mostly likely read, create, update and destroy.

Roles are intended to be set from migration or seed and not to be edited by an admin, the logic is mostly hardcoded if based on cancan(can). Users can be members of group. Memberships are separate model here (not only an plain many-to-many association) to allow both manual memberships and automatically created memberships during the login process.

Versions

wobauth 1.x is for Rails 4, wobauth 2.x will support Rails 5. wobauth 3.x uses bootstrap v4 and font-awesome, starting with Rails 5.1 (may work with Rails 5.0, but not tested) wobauth 4.x works with sprockets v4. wobauth 5.x works with rails 6.x and is designed for autoloading via zeitwerk. wobauth 6.x works with rails >= 6.1 and uses bootstrap v5.

Requirements

Rails >= 6.0; autoload = :zeitwerk; webpacker; stimulusjs

version rails ruby bootstrap icons wobapphelpers
master(6.x) >=6.1 >= 2.7 v5 fontawesome 5.x master (5.x)
5-1-stable >=6.0 >= 2.6 v4 fontawesome 5.x 4-stable

Rails >= 6.0, autoload = :zeitwerk

version rails ruby bootstrap icons wobapphelpers
5-stable >=6.0 >= 2.6 v4 fontawesome 5.x 4-stable

Rails <= 5.2, autoload = :classic

branch rails ruby bootstrap icons wobapphelpers
4-0-stable >=5.1 >= 2.3 v4 fontawesome 5.x 4-stable
3-0-stable >=5.1 >= 2.3 v4 fontawesome 4.7 3-0-stable
2-0-stable 5.0 >= 2.2 v3 glyphicons 2-0-stable
1-0-stable 4.2 >= 2.0 v3 glyphicons 1-0-stable
  • simple_form >= 3.3

Installation

Add wobauth to your Gemfile:

gem 'wobauth', git: 'https://github.com/swobspace/wobauth.git', branch: 'master'
gem 'wobauth', '~> 5.0.0'
gem 'wobauth', '~> 4.0.0'
gem 'wobauth', '~> 3.4.8'
gem 'wobauth', git: 'https://github.com/swobspace/wobauth.git', branch: '3-0-stable'
gem 'wobauth', git: 'https://github.com/swobspace/wobauth.git', branch: '2-0-stable'
gem 'wobauth', git: 'https://github.com/swobspace/wobauth.git', branch: '1-0-stable'

Starting with v3.4 gems are published to rubygems.org.

Run

rails g wobauth:install

to create an example configuration in ''config/initializers/wobauth.rb''

rake wobauth:install:migrations

copies wobauth migration files wobauth to your application. Do this before you create your own migration files if possible. If you upgrade from an older wobauth version rerun it. There might be new migration files added.

Upgrade

For Upgrade from 3.x to 4.x you have to upgrade wobapphelpers

Configuration

User model

To customize the user model to your needs, create app/models/wobauth/users.rb in your application:

# main_app/app/models/wobauth/user.rb

class Wobauth::User < ActiveRecord::Base
  include Wobauth::Concerns::Models::User

  devise :database_authenticatable, :registerable,
         :recoverable, :rememberable, :trackable

  ... add your associations and methods ...
end

DO NOT USE :validatable, since wobauth uses :username as authentication key (devise default :email, will be required if you use :validatable).

Views

Helpers for bootstrap navbar:

  • navigation_account_links : navigation partial for login/userprofile/logout
  • navigation_admin_links : navigation partial for user/roles/authorities ...

Authorized_for types

If you have objects for which wobauth should provide authority configuration, set your models in the initializer (created by rails g wobauth:install). In this example we will use Category from your main application:

Wobauth.setup do |config|
  #
  # Configuration for Authorization
  # 1. Subject: Authorizable
  # do not change it unless you know exactly what you are doing
  #
  # config.authorizable_types = [ "Wobauth::User", "Wobauth::Group" ]
  #
  # 2. Object: Authorized_for
  # depends on your application ...
  # default: []
   
  config.authorized_for_types = [ "Category" ]
   
end

You can create and delete authority records within wobauth, but you have to build your own authorization with cancan(can) in your main application.

Routes

Mount the rails engine:

# config/routes.rb
Rails.application.routes.draw do
  ...
  mount Wobauth::Engine, at: '/auth'
end

With rails 5.1 there are some problems with engine routing in engines. Add the mount statement at the bottom of Rails.application.routes.draw and use always a suburl for mount like /auth. Don't use /.

Using datatables

Wobauth comes with support for datatables. To select the tables, use the following jQuery selector:

$('table[role="wobauth_datatable"]')

$('dataTable') may be removed in a future release.

Applications using wobauth

If you are looking for examples using wobauth, have a look at boskop.

Another simple example is the test/dummy application included in this rails engine.

Licence

wobauth Copyright (C) 2014-2021 Wolfgang Barth

MIT license, see LICENSE