sorcery

Magical Authentication for Rails 3. Supports ActiveRecord, Mongoid and MongoMapper.

Inspired by restful_authentication, Authlogic and Devise. Crypto code taken almost unchanged from Authlogic. OAuth code inspired by OmniAuth and Ryan Bates's railscasts about it.

Philosophy

Sorcery is a stripped-down, bare-bones authentication library, with which you can write your own authentication flow. It was built with a few goals in mind:

Hopefully, I've achieved this. If not, let me know.

Useful Links:

Railscast: railscasts.com/episodes/283-authentication-with-sorcery

Example Rails 3 app using sorcery: github.com/NoamB/sorcery-example-app

Documentation: rubydoc.info/gems/sorcery/0.7.4/frames

Check out the tutorials in the github wiki!

API Summary

Below is a summary of the library methods. Most method names are self explaining and the rest are commented:

# core
 # this is a before filter
(username,password,remember_me = false)
(user)# login without credentials
logout
logged_in?      # available to view
current_user    # available to view
redirect_back_or_to # used when a user tries to access a page while logged out, is asked to login, and we want to return him back to the page he originally wanted.
@user.external? # external users, such as facebook/twitter etc.
User.authenticates_with_sorcery!

# activity logging
current_users

# http basic auth
 # this is a before filter

# external
(provider) # sends the user to an external service (twitter etc.) to authenticate.
(provider) # tries to login from the external provider's callback.
create_from(provider) # create the user in the local app db.

# remember me
(user, should_remember=false)  # login without credentials, optional remember_me
remember_me!
forget_me!

# reset password
User.load_from_reset_password_token(token)
@user.deliver_reset_password_instructions!
@user.change_password!(new_password)

# user activation
User.load_from_activation_token(token)
@user.activate!

Please see the tutorials in the github wiki for detailed usage information.

Installation:

If using bundler, first add 'sorcery' to your Gemfile:

gem “sorcery”

And run bundle install

Otherwise simply

gem install sorcery

Rails 3 Configuration:

rails generate sorcery:install

This will generate the core migration file, the initializer file and the 'User' model class.

rails generate sorcery:install remember_me reset_password

This will generate the migrations files for remember_me and reset_password submodules and will create the initializer file (and add submodules to it), and create the 'User' model class.

rails generate sorcery:install --model Person

This will generate the core migration file, the initializer and change the model class (in the initializer and migration files) to the class 'Person' (and its pluralized version, 'people')

rails generate sorcery:install http_basic_auth external remember_me --migrations

This will generate only the migration files for the specified submodules and will add them to the initializer file.

Inside the initializer, the comments will tell you what each setting does.

Full Features List by module:

Core (see lib/sorcery/model.rb and lib/sorcery/controller.rb):

User Activation (see lib/sorcery/model/submodules/user_activation.rb):

Reset Password (see lib/sorcery/model/submodules/reset_password.rb):

Remember Me (see lib/sorcery/model/submodules/remember_me.rb):

Session Timeout (see lib/sorcery/controller/submodules/session_timeout.rb):

Brute Force Protection (see lib/sorcery/model/submodules/brute_force_protection.rb):

Basic HTTP Authentication (see lib/sorcery/controller/submodules/http_basic_auth.rb):

Activity Logging (see lib/sorcery/model/submodules/activity_logging.rb):

External (see lib/sorcery/controller/submodules/external.rb):

Next Planned Features:

I've got some thoughts which include (unordered):

Have an idea? Let me know, and it might get into the gem!

Backward compatibility

While the lib is young and evolving fast I'm breaking backward compatibility quite often. I'm constantly finding better ways to do things and throwing away old ways. To let you know when things are changing in a non-compatible way, I'm bumping the minor version of the gem. The patch version changes are backward compatible.

In short, an app that works with x.3.1 should be able to upgrade to x.3.2 with no code changes. The same cannot be said about upgrading to x.4.0 and above, however.

Upgrading

Important notes while upgrading:

Contributing to sorcery

Your feedback is very welcome and will make this gem much much better for you, me and everyone else. Besides feedback on code, features, suggestions and bug reports, you may want to actually make an impact on the code. For this:

If you feel sorcery has made your life easier, and you would like to express your thanks via a donation, my paypal email is in the contact details.

Contact

Feel free to ask questions using these contact details: email: nbenari@gmail.com ( also for paypal ) twitter: @nbenari

Copyright

Copyright © 2010 Noam Ben Ari (nbenari@gmail.com). See LICENSE.txt for further details.