Home

Awesome

Sorcery: Magical Authentication

[!WARNING]

Sorcery is currently unmaintained.

What should I do?

  1. Help maintain Sorcery (see: https://github.com/Sorcery/sorcery/issues/350)
  2. Keep using Sorcery, and accept the risk that it may break or have unpatched security vulnerabilities.
  3. Consider switching to alternative libraries that are actively maintained:

Gem Version Gem Downloads Build Status

Magical Authentication for Rails. Supports ActiveRecord, DataMapper, 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 Railscast 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:

Table of Contents

  1. Useful Links
  2. API Summary
  3. Installation
  4. Configuration
  5. Full Features List by Module
  6. Planned Features
  7. Contributing
  8. Contact
  9. License

Useful Links

Check out the tutorials in the wiki for more:

API Summary

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

Core

require_login # This is a before action
login(email, password, remember_me = false)
auto_login(user) # Login without credentials
logout
logged_in? # Available in views
current_user # Available in views
redirect_back_or_to # Use 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? # Users who signed up using Facebook, Twitter, etc.
@user.active_for_authentication? # Add this method to define behaviour that will prevent selected users from signing in
@user.valid_password?('secret') # Compares 'secret' with the actual user's password, returns true if they match
User.authenticates_with_sorcery!

HTTP Basic Auth

require_login_from_http_basic # This is a before action

External

login_at(provider) # Sends the user to an external service (Facebook, Twitter, etc.) to authenticate
login_from(provider) # Tries to login from the external provider's callback
create_from(provider) # Create the user in the local app database
build_from(provider) # Build user instance using user_info_mappings

Remember Me

auto_login(user, should_remember = false) # Login without credentials, optional remember_me
remember_me!
forget_me!
force_forget_me! # Forgets all sessions by clearing the token, even if remember_me_token_persist_globally is set to true

Reset Password

User.load_from_reset_password_token(token)
@user.generate_reset_password_token! # Use if you want to send the email by yourself
@user.deliver_reset_password_instructions! # Generates the token and sends the email
@user.change_password(new_password)
@user.change_password!(new_password) # Same as change_password but raises exception on save

Session Timeout

invalidate_active_sessions! #Invalidate all sessions with a login_time or last_action_time before the current time. Must Opt-in

User Activation

User.load_from_activation_token(token)
@user.setup_activation
@user.activate!

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

Installation

Add this line to your application's Gemfile:

gem 'sorcery'

And then execute:

$ bundle

Or install it yourself as:

$ gem install sorcery

Configuration

Run the following command to generate the core migration file, the initializer file and the User model class.

$ rails generate sorcery:install

Run the following command 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 remember_me reset_password

Run the following command to 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 --model Person

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

$ rails generate sorcery:install http_basic_auth external remember_me --only-submodules

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):

Planned Features

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

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/Sorcery/sorcery.

Contact

Feel free to ask questions using these contact details:

Current Maintainers:

Past Maintainers:

License

The gem is available as open source under the terms of the MIT License.