Project

wobauth

0.0
The project is in a healthy, maintained state
Rails engine providing MVCs for User, Group, Role, Membership and Authority
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
 Project Readme

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 & Requirements

Rails >= 6.1; needs @hotwired/turbo-rails; no support for rails-ujs

version rails ruby bootstrap icons wobapphelpers
master (v7) >=6.1 >= 2.7 v5 fontawesome 5.x master (v6)

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

version rails ruby bootstrap icons wobapphelpers
6-stable >=6.1 >= 2.7 v5 fontawesome 5.x 5-stable
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', '~> 6.0.0'
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. You need a stimulus datatables controller like something used in https://swobspace.github.io/rails-playground/playbook/datatables/datatables-js.html

Applications using wobauth

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

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

Licence

wobauth Copyright (C) 2014-2022 Wolfgang Barth

MIT license, see LICENSE