Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Magical authentication for Rails 3
Ruby JavaScript

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
lib
spec
.document
.gitignore
.rspec
Gemfile
Gemfile.lock
LICENSE.txt
README.rdoc
Rakefile
VERSION
sorcery.gemspec

README.rdoc

sorcery

Magical Authentication for Rails 3.

Inspired by restful_authentication, Authlogic and Devise. Crypto code taken almost unchanged from Authlogic. OAuth code inspired by OmniAuth.

Summary

Sorcery aims to make your life easier by giving you an easy API to write your own user authentication flow with. It does this with a few goals in mind:

  • Less is more - less than 20 simple methods to remember for the entire feature-set make the lib easy to 'get'.

  • No built-in or generated code - use the API inside *your own* MVC structures, and don't fight to fix someone else's.

  • Magic yes, Voodoo no - the lib should be easy to hack for most developers.

  • Configuration over Confusion - Simple & short configuration as possible, not drowning in syntactic sugar.

  • Keep MVC cleanly separated - DB is for models, sessions are for controllers. Models stay unaware of sessions.

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

Useful Links:

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

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

Full Features List by module:

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

  • login/logout, optional return user to requested url on login, configurable redirect for non-logged-in users.

  • password encryption, algorithms: bcrypt(default), md5, sha1, sha256, sha512, aes256, custom(yours!), none. Configurable stretches and salt.

  • configurable attribute names for username, password and email.

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

  • User activation by email with optional success email.

  • configurable attribute names.

  • configurable mailer, method name, and attribute name.

  • configurable temporary token expiration.

  • Optionally prevent non-active users to login.

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

  • Reset password with email verification.

  • configurable mailer, method name, and attribute name.

  • configurable temporary token expiration.

  • configurable time between emails (hammering protection).

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

  • Remember me with configurable expiration.

  • configurable attribute names.

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

  • Configurable session timeout.

  • Optionally session timeout will be calculated from last user action.

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

  • Brute force login hammering protection.

  • configurable logins before lock and lock duration.

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

  • A before filter for requesting authentication with HTTP Basic.

  • automatic login from HTTP Basic.

  • automatic login is disabled if session key changed.

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

  • automatic logging of last login, last logout and last activity time.

  • an easy method of collecting the list of currently logged in users.

  • configurable timeout by which to decide whether to include a user in the list of logged in users.

Oauth (see lib/sorcery/controller/submodules/oauth.rb):

  • OAuth1 and OAuth2 support (currently twitter & facebook)

  • configurable db field names and authentications table.

Next Planned Features:

I've got many plans which include (by priority):

  • Sinatra support

  • Mongoid support

  • Configurable Auto login on registration/activation

  • Other reset password strategies (security questions?)

  • Other brute force protection strategies (captcha)

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

Installation:

You can either git clone and then 'rake install' to live on the edge (unstable),

Or simply (stable):

gem install sorcery

Configuration:

First add 'sorcery' to your Gemfile:

gem “sorcery”

And run bundle install

There are 2 required places to configure the plugin, and an optional one:

  1. config/application.rb

config.sorcery.submodules = [:user_activation, :remember_me] # add the modules you want to use

You can also configure here any controller and any controller-submodule option here. For example:

config.sorcery.session_timeout = 10.minutes

  1. app/models/user.rb (or another model of your choice)

activate_sorcery! do |config|

	  config.user_activation_mailer = MyMailer

config.username_attribute_name = :email end

  1. app/controllers/application_controller.rb (OPTIONAL: this is actually needed only in some cases)

activate_sorcery! do |config|

	  config.session_timeout = 10.minutes

end

Also check the migrations in the example app to see what database fields are expected.

The configuration options vary with the modules you've chosen to use.

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:

  • 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 Rakefiles, 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.

If you feel my work has made your life easier, and you would like to thank me through a donation, my paypal email is in the contact details.

Contact

email: nbenari@gmail.com ( also for paypal ) twitter: @nbenari

Copyright

Copyright © 2010 Noam Ben Ari (nbenari@gmail.com). See LICENSE.txt for further details. Released with permission from Kontera (www.kontera.com), where I work.

Something went wrong with that request. Please try again.