Cream

This project aims to assist you in setting up a complete user login and role permission system for your Rails 3 app. It targets Devise as the Session system, CanCan as the permission system and Roles as the user Roles system.

The objective of this project is to

  • Integrate all these sub-systems
  • Provide a generator that can auto-configure your Rails 3 app with these sub-systems for a given ORM

Status

This project and the gems it assembles should all mostly work. I am currently going through all the supporting gems, making sure dependencies are updated and that they use the latest APIs of the other gems and all specs pass. Stay tuned! The config generators is currently under construction and needs some fine-tuning to bring all the gems together.

I have now also started a new project called Cream rails 3 app which is to be a template Rails 3 project that demonstrates what a final Rails 3 app using Cream will look like. I plan to use this as a template for the Cream config generator, making sure that given Mongo Mapper as the ORM and default arguments, the generartor should generate a "mirror image" of this template project. You are most welcome to help me in this effort or provide suggestions etc. The README of the template project will contain a recipe with the steps to be taken to produce it ;)

NOTE: I have renamed the old 'auth-assistant' project to this project called 'cream'.

Session systems

Cream targets Devise as the Session system of choice

The project devise links adds more convenience for creating view links to trigger Devise session actions.

Roles

I have developed a flexible Generic Roles strategy system.

Roles for popular ORMs

The Roles Generic API has been implemented for the following ORMs

Role Groups Document DBs such as Mongo and Riak are good for modeling a role-group hierarchical relationship. Role-Group support is planned as a future add-on for the roles strategies integration. (Any assistance appreciated!)

Note: You are most welcome to provide "plugins" for any other role frameworks. Please follow the API conventions of Roles generic.

Permission systems

There is support for the CanCan permission system. I have created a Cancan permits gem that adds the concept of Permits for each role (see below)

I'm considering supporting Canable as well (but only if requested by the community!)

Note: You are most welcome to provide "plugins" for other permission frameworks!

ORMs

In general, it should now finally be pretty easy to set up a Rails 3 app, with a full Session system, Permission system linked to a Role strategy system using any ORM. Devise supports the following ORMS:

  • Active Record
  • Data Mapper
  • Mongo Mapper
  • Mongoid

These ORMs are also supported for the Roles strategy system. The Permission system should not have any ORM dependency. There are plans to create a top-level generator which sets up your project with all these systems for a given ORM.

Installation and configuration

This gem has been designed for Rails 3 only.

Install gems

Insert 

gem 'cream'
in your Rails 3 Gemfile

$ bundle install

Install as plugin

In the near future...

rails plugin install http://github.com/kristianmandrup/cream.git

Role system

Role strategies can be set up using the Roles Generic gem or any of the ORM specific roles gems such as Roles - Active Record. There are currently Roles implementations for the following ORMs:

  • Active Record
  • Data Mapper
  • Mongo Mapper
  • Mongoid

Permission system

The only Permission system currently supported is CanCan.

CanCan

Role based authorization for CanCan is currently done by creating Permits for each role. A Permit lets a user in a given role do certain actions as defined in the Permit.

The config generator will generate a set of Permit files which are placed in '/app/permits'. You can then edit the Permits to suit your needs.

The project CanCan REST links provides a convenient way to handle CanCan REST links, using a flexible API.

Canable

In Canable the permissions are by default defined in the models. I plan to tweak this behavior to enable the same or a similar central permission setup as I use for CanCan. In my (somewhat old and degenerate) fork of Canable, I have generators to setup the models and user with a Canable config.

Note: These generators should be updated to take advantage of my latest generator-spec and other supporting generator assitant gems!

More to follow in the future...

Permits

Currently CanCan is supported as the permission system. I have added the concept of Permits linked to Roles.

Check out Cancan permits for more info for how to use Permits.

Note: In the future I will add the ability for a given role to have multiple Permits in a PermitSet, so that Permits are stand-alone and not linked to a given role, which allows permits to be reused for multiple roles. Stay tuned or join in the effort!

Generators

The following generators are currently available

  • config - Configure Rails 3 application with devise Session strategies, a Role strategy, valid roles, and Permits
  • views - Generate partials to display menu items for Session actions such as logout, login etc.

The config generator should automatically setup up your project with Devise, a Roles strategy of choice a Permission system of choice and all using an ORM of your choice!

Cream will support these ORMs:

  • Active Record
  • Data Mapper
  • Mongo Mapper
  • Mongoid

Status 17 sept, 2010: The latest generator-spec and other supporting generator utils I've created (such as rails3_artifactor) should facilitate finishing this generator...

The goal is to make the generator:

  • Configure the Rails 3 app with appropriate gems for the sub-systems
  • Run various other generators

The result should be a full (or nearly full) integration of all the sub-systems mentioned for a given Rails 3 app with the ORM of choice.

See Cream rails 3 app to get an idea of the end goal.

Config Generator

rails g cream::config --strategy ROLE_STRATEGY [--init-devise] [--admin_user] [--orm] [--roles]

  • --strategy : role strategy to use (see roles_generic gem)
  • --init-devise : run devise generator to create devise Users with session/auth strategies
  • --admin-user : create admin user model with separate devise configuration
  • --orm : orm to be used
  • --roles : list of valid roles to use

Example

rails g cream:config admin_flag --devise --admin --orm AR

Views Generator

Moves 'user menu' partials views into app/views/_user_menu

rails g cream::views [scope] [--haml]

  • scope : The scope folder under views to copy the partials to, fx 'admin'
  • --haml : Use HAML as template language

Note on Patches/Pull Requests

  • Fork the project.
  • Make your feature addition or bug fix.
  • Add tests for it. This is important so I don't break it in a future version unintentionally.
  • Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
  • Send me a pull request. Bonus points for topic branches.

Copyright (c) 2010 Kristian Mandrup. See LICENSE for details.