Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 262 lines (166 sloc) 9.326 kb
5687b84 added travis status image
Luciano Sousa authored
1 {<img src="https://secure.travis-ci.org/NoamB/sorcery.png" />}[http://travis-ci.org/NoamB/sorcery]
2
5fd1c29 @NoamB renamed plugin to a little more original name
authored
3 = sorcery
75c2307 @NoamB removing sinatra support, the gem is now a rails3 gem, and this will …
authored
4 Magical Authentication for Rails 3.
3c8ace7 @kbighorse all mongoid tests passing with mongo_mapper
kbighorse authored
5 Supports ActiveRecord, Mongoid and MongoMapper.
dfc6fc8 @NoamB Initial commit to simple_auth.
authored
6
06ceb5b @NoamB fixing login_from_cookie bug and adding login(user,pwd,remember) form
authored
7 Inspired by restful_authentication, Authlogic and Devise.
b00e7bd @NoamB fixing aes256 a bit before adding and also adding SHA variants
authored
8 Crypto code taken almost unchanged from Authlogic.
d8e4e84 @NoamB updated README
authored
9 OAuth code inspired by OmniAuth and Ryan Bates's railscasts about it.
b00e7bd @NoamB fixing aes256 a bit before adding and also adding SHA variants
authored
10
0bd4ebd @NoamB improved README, some docs, changed 'return_or_redirect_to' to 'redir…
authored
11 == Philosophy
71d7e66 @NoamB updated README
authored
12
13
d8e4e84 @NoamB updated README
authored
14 Sorcery is a stripped-down, bare-bones authentication library, with which you can write your own authentication flow.
15 It was built with a few goals in mind:
16
17 * Less is more - less than 20 public methods to remember for the entire feature-set make the lib easy to 'get'.
18 * No built-in or generated code - use the library's methods inside *your own* MVC structures, and don't fight to fix someone else's.
71d7e66 @NoamB updated README
authored
19 * Magic yes, Voodoo no - the lib should be easy to hack for most developers.
b5680a9 @NoamB updated README
authored
20 * Configuration over Confusion - Centralized (1 file), Simple & short configuration as possible, not drowning in syntactic sugar.
71d7e66 @NoamB updated README
authored
21 * Keep MVC cleanly separated - DB is for models, sessions are for controllers. Models stay unaware of sessions.
22
23 Hopefully, I've achieved this. If not, let me know.
24
d8e4e84 @NoamB updated README
authored
25
39658ae @NoamB beginning oauth integration
authored
26 == Useful Links:
27
f30ee2c @NoamB update README
authored
28 Railscast: http://railscasts.com/episodes/283-authentication-with-sorcery
d8e4e84 @NoamB updated README
authored
29
2df4a07 @NoamB updated README
authored
30 Example Rails 3 app using sorcery: https://github.com/NoamB/sorcery-example-app
31
39db61d @NoamB last changes before new gem
authored
32 Documentation: http://rubydoc.info/gems/sorcery/0.7.13/frames
71d7e66 @NoamB updated README
authored
33
9e2e984 @NoamB updated README
authored
34 Check out the tutorials in the github wiki!
35
d8e4e84 @NoamB updated README
authored
36
4048a0e @NoamB updating README and adding the 'configure' methods to controller module
authored
37 == API Summary
38
39
40 Below is a summary of the library methods. Most method names are self explaining and the rest are commented:
41
42 # core
43 require_login # this is a before filter
44 login(username,password,remember_me = false)
3439484 @NoamB addressing issue #23 by adding auto_login to the API
authored
45 auto_login(user)# login without credentials
4048a0e @NoamB updating README and adding the 'configure' methods to controller module
authored
46 logout
73ae86f @NoamB updated README
authored
47 logged_in? # available to view
48 current_user # available to view
4048a0e @NoamB updating README and adding the 'configure' methods to controller module
authored
49 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.
50 @user.external? # external users, such as facebook/twitter etc.
51 User.authenticates_with_sorcery!
52
53 # activity logging
54 current_users
55
56 # http basic auth
57 require_login_from_http_basic # this is a before filter
58
59 # external
60 login_at(provider) # sends the user to an external service (twitter etc.) to authenticate.
61 login_from(provider) # tries to login from the external provider's callback.
62 create_from(provider) # create the user in the local app db.
63
64 # remember me
3439484 @NoamB addressing issue #23 by adding auto_login to the API
authored
65 auto_login(user, should_remember=false) # login without credentials, optional remember_me
4048a0e @NoamB updating README and adding the 'configure' methods to controller module
authored
66 remember_me!
67 forget_me!
68
69 # reset password
70 User.load_from_reset_password_token(token)
71 @user.deliver_reset_password_instructions!
414ae3b @NoamB updated README
authored
72 @user.change_password!(new_password)
4048a0e @NoamB updating README and adding the 'configure' methods to controller module
authored
73
74 # user activation
75 User.load_from_activation_token(token)
76 @user.activate!
77
78 Please see the tutorials in the github wiki for detailed usage information.
79
80
d8e4e84 @NoamB updated README
authored
81 == Installation:
82
83
84 If using bundler, first add 'sorcery' to your Gemfile:
85
64e0f0c @tricknotes Improve README layout
tricknotes authored
86 gem "sorcery"
d8e4e84 @NoamB updated README
authored
87
5687b84 added travis status image
Luciano Sousa authored
88 And run
64e0f0c @tricknotes Improve README layout
tricknotes authored
89
90 bundle install
d8e4e84 @NoamB updated README
authored
91
92 Otherwise simply
93
64e0f0c @tricknotes Improve README layout
tricknotes authored
94 gem install sorcery
d8e4e84 @NoamB updated README
authored
95
96
4048a0e @NoamB updating README and adding the 'configure' methods to controller module
authored
97 == Rails 3 Configuration:
d8e4e84 @NoamB updated README
authored
98
1e67573 @NoamB update README
authored
99 rails generate sorcery:install
d8e4e84 @NoamB updated README
authored
100
1e67573 @NoamB update README
authored
101 This will generate the core migration file, the initializer file and the 'User' model class.
d8e4e84 @NoamB updated README
authored
102
1e67573 @NoamB update README
authored
103 rails generate sorcery:install remember_me reset_password
d8e4e84 @NoamB updated README
authored
104
1e67573 @NoamB update README
authored
105 This will generate the migrations files for remember_me and reset_password submodules
106 and will create the initializer file (and add submodules to it), and create the 'User' model class.
d8e4e84 @NoamB updated README
authored
107
ea19381 @NoamB updated README
authored
108 rails generate sorcery:install --model Person
d8e4e84 @NoamB updated README
authored
109
1e67573 @NoamB update README
authored
110 This will generate the core migration file, the initializer and change the model class
111 (in the initializer and migration files) to the class 'Person' (and its pluralized version, 'people')
9988007 @NoamB updated README
authored
112
ea19381 @NoamB updated README
authored
113 rails generate sorcery:install http_basic_auth external remember_me --migrations
9988007 @NoamB updated README
authored
114
1e67573 @NoamB update README
authored
115 This will generate only the migration files for the specified submodules and will
116 add them to the initializer file.
5687b84 added travis status image
Luciano Sousa authored
117
88e5ced @NoamB updated README
authored
118 Inside the initializer, the comments will tell you what each setting does.
119
120
29e7e70 @xpepermint Adding the delayed_job integration instructions.
xpepermint authored
121 == DelayedJob Integration
122
123 By default emails are sent synchronously. You can send them asynchronously by using the
124 [delayed_job gem](https://github.com/collectiveidea/delayed_job).
125
126 After implementing the `delayed_job` into your project add the code below at the end of
127 the `config/initializers/sorcery.rb` file. After that all emails will be sent asynchronously.
128
129 module Sorcery
130 module Model
131 module InstanceMethods
132 def generic_send_email(method, mailer)
133 config = sorcery_config
134 mail = config.send(mailer).delay.send(config.send(method), self)
135 end
136 end
137 end
138 end
139
140
4338726 @gavinhughes Removed old STI support buried in Wiki and added it here.
gavinhughes authored
141 == Single Table Inheritance (STI) Support
142 STI is supported via a single setting in config/initializers/sorcery.rb.
143
144
50a5df4 @NoamB separated mailers between user_activation and password_reset and upda…
authored
145 == Full Features List by module:
4fe9ba3 @NoamB updated readme
authored
146
d8e4e84 @NoamB updated README
authored
147
a6af741 @NoamB fixed little error in README
authored
148 Core (see lib/sorcery/model.rb and lib/sorcery/controller.rb):
e56621e @NoamB fixed 'return_to' feature and also dealt with missing User model by p…
authored
149 * login/logout, optional return user to requested url on login, configurable redirect for non-logged-in users.
50a5df4 @NoamB separated mailers between user_activation and password_reset and upda…
authored
150 * password encryption, algorithms: bcrypt(default), md5, sha1, sha256, sha512, aes256, custom(yours!), none. Configurable stretches and salt.
151 * configurable attribute names for username, password and email.
32adc70 @NoamB updated README
authored
152 * allow multiple fields to serve as username.
50a5df4 @NoamB separated mailers between user_activation and password_reset and upda…
authored
153
53a0ced @NoamB updated README
authored
154 User Activation (see lib/sorcery/model/submodules/user_activation.rb):
4fe9ba3 @NoamB updated readme
authored
155 * User activation by email with optional success email.
50a5df4 @NoamB separated mailers between user_activation and password_reset and upda…
authored
156 * configurable attribute names.
e56621e @NoamB fixed 'return_to' feature and also dealt with missing User model by p…
authored
157 * configurable mailer, method name, and attribute name.
158 * configurable temporary token expiration.
b82dd2a @NoamB updated readme
authored
159 * Optionally prevent non-active users to login.
50a5df4 @NoamB separated mailers between user_activation and password_reset and upda…
authored
160
53a0ced @NoamB updated README
authored
161 Reset Password (see lib/sorcery/model/submodules/reset_password.rb):
4fe9ba3 @NoamB updated readme
authored
162 * Reset password with email verification.
50a5df4 @NoamB separated mailers between user_activation and password_reset and upda…
authored
163 * configurable mailer, method name, and attribute name.
e56621e @NoamB fixed 'return_to' feature and also dealt with missing User model by p…
authored
164 * configurable temporary token expiration.
61f28e7 @NoamB adding password_reset hammering protection
authored
165 * configurable time between emails (hammering protection).
50a5df4 @NoamB separated mailers between user_activation and password_reset and upda…
authored
166
53a0ced @NoamB updated README
authored
167 Remember Me (see lib/sorcery/model/submodules/remember_me.rb):
4fe9ba3 @NoamB updated readme
authored
168 * Remember me with configurable expiration.
50a5df4 @NoamB separated mailers between user_activation and password_reset and upda…
authored
169 * configurable attribute names.
170
53a0ced @NoamB updated README
authored
171 Session Timeout (see lib/sorcery/controller/submodules/session_timeout.rb):
4fe9ba3 @NoamB updated readme
authored
172 * Configurable session timeout.
50a5df4 @NoamB separated mailers between user_activation and password_reset and upda…
authored
173 * Optionally session timeout will be calculated from last user action.
174
53a0ced @NoamB updated README
authored
175 Brute Force Protection (see lib/sorcery/model/submodules/brute_force_protection.rb):
3863c4c @NoamB updated README
authored
176 * Brute force login hammering protection.
b59f82e @NoamB updated README
authored
177 * configurable logins before lock and lock duration.
50a5df4 @NoamB separated mailers between user_activation and password_reset and upda…
authored
178
53a0ced @NoamB updated README
authored
179 Basic HTTP Authentication (see lib/sorcery/controller/submodules/http_basic_auth.rb):
930e224 @NoamB adding HTTP BASIC AUTH submodule with tests
authored
180 * A before filter for requesting authentication with HTTP Basic.
181 * automatic login from HTTP Basic.
182 * automatic login is disabled if session key changed.
183
53a0ced @NoamB updated README
authored
184 Activity Logging (see lib/sorcery/model/submodules/activity_logging.rb):
01378b9 @NoamB adding activity logging submodule, updated readme, and bugfix to basi…
authored
185 * automatic logging of last login, last logout and last activity time.
186 * an easy method of collecting the list of currently logged in users.
187 * configurable timeout by which to decide whether to include a user in the list of logged in users.
188
64b89dc @NoamB refactoring oauth submodule into 'external' to make the API nicer and…
authored
189 External (see lib/sorcery/controller/submodules/external.rb):
4c8ff9f @NoamB fixing bug in http basic auth
authored
190 * OAuth1 and OAuth2 support (currently twitter & facebook)
191 * configurable db field names and authentications table.
192
d8e4e84 @NoamB updated README
authored
193
930e224 @NoamB adding HTTP BASIC AUTH submodule with tests
authored
194 == Next Planned Features:
8c3bfec @NoamB added brute_force_protection module to controller
authored
195
d8e4e84 @NoamB updated README
authored
196
59bb8aa @NoamB update README
authored
197 I've got some thoughts which include (unordered):
b5680a9 @NoamB updated README
authored
198 * Passing a block to encrypt, allowing the developer to define his own mix of salting and encrypting
7bc34b7 @NoamB updating version in Gemfiles
authored
199 * Forgot username, maybe as part of the reset_password module
a6af741 @NoamB fixed little error in README
authored
200 * Scoping logins (to a subdomain or another arbitrary field)
b5680a9 @NoamB updated README
authored
201 * Allowing storing the salt and crypted password in the same DB field for extra security
8c3bfec @NoamB added brute_force_protection module to controller
authored
202 * Other reset password strategies (security questions?)
b59f82e @NoamB updated README
authored
203 * Other brute force protection strategies (captcha)
b5680a9 @NoamB updated README
authored
204
205
206 Have an idea? Let me know, and it might get into the gem!
207
8c3bfec @NoamB added brute_force_protection module to controller
authored
208
4048a0e @NoamB updating README and adding the 'configure' methods to controller module
authored
209 == Backward compatibility
210
211
7bc34b7 @NoamB updating version in Gemfiles
authored
212 While the lib is young and evolving fast I'm breaking backward compatibility quite often.
4048a0e @NoamB updating README and adding the 'configure' methods to controller module
authored
213 I'm constantly finding better ways to do things and throwing away old ways.
214 To let you know when things are changing in a non-compatible way, I'm bumping the minor version of the gem.
215 The patch version changes are backward compatible.
216
7bc34b7 @NoamB updating version in Gemfiles
authored
217 In short, an app that works with x.3.1 should be able to upgrade to x.3.2 with no code changes.
218 The same cannot be said about upgrading to x.4.0 and above, however.
4048a0e @NoamB updating README and adding the 'configure' methods to controller module
authored
219
4b7e216 @brianp Added Upgrading section to make note about initializer line.
brianp authored
220 == Upgrading
221
222 Important notes while upgrading:
223
61e9d51 @NoamB updated README
authored
224 * If upgrading from <= 0.6.1 to >= 0.7.0 you need to change 'username_attribute_name' to 'username_attribute_names' in initializer.
4b7e216 @brianp Added Upgrading section to make note about initializer line.
brianp authored
225 * If upgrading from <= v0.5.1 to >= v0.5.2 you need to explicitly set your user_class model in the initializer file.
c0cf834 @brianp Fixed Code block issue in upgrading section
brianp authored
226
227 # This line must come after the 'user config' block.
e8fbd75 @brianp Fixed wrong config attribute name in upgrading section.
brianp authored
228 config.user_class = User
4048a0e @NoamB updating README and adding the 'configure' methods to controller module
authored
229
75c2307 @NoamB removing sinatra support, the gem is now a rails3 gem, and this will …
authored
230 * Sinatra support existed until v0.7.0 (including), but was dropped later due to being a maintenance nightmare.
231
232
5fd1c29 @NoamB renamed plugin to a little more original name
authored
233 == Contributing to sorcery
dfc6fc8 @NoamB Initial commit to simple_auth.
authored
234
0bd4ebd @NoamB improved README, some docs, changed 'return_or_redirect_to' to 'redir…
authored
235
b82dd2a @NoamB updated readme
authored
236 Your feedback is very welcome and will make this gem much much better for you, me and everyone else.
237 Besides feedback on code, features, suggestions and bug reports, you may want to actually make an impact on the code.
01378b9 @NoamB adding activity logging submodule, updated readme, and bugfix to basi…
authored
238 For this:
239
4048a0e @NoamB updating README and adding the 'configure' methods to controller module
authored
240 * Fork it.
241 * Fix it.
242 * Test it.
243 * Commit it.
244 * Send me a pull request so I'll... Pull it.
01378b9 @NoamB adding activity logging submodule, updated readme, and bugfix to basi…
authored
245
4048a0e @NoamB updating README and adding the 'configure' methods to controller module
authored
246 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.
deabb59 @NoamB Version bump to 0.3.0
authored
247
d8e4e84 @NoamB updated README
authored
248
deabb59 @NoamB Version bump to 0.3.0
authored
249 == Contact
250
4048a0e @NoamB updating README and adding the 'configure' methods to controller module
authored
251
2df4a07 @NoamB updated README
authored
252 Feel free to ask questions using these contact details:
d8e4e84 @NoamB updated README
authored
253
928d0d5 @NoamB adding the activity_logging submodule which will be used to display t…
authored
254 email: nbenari@gmail.com ( also for paypal )
50a5df4 @NoamB separated mailers between user_activation and password_reset and upda…
authored
255 twitter: @nbenari
deabb59 @NoamB Version bump to 0.3.0
authored
256
d8e4e84 @NoamB updated README
authored
257
dfc6fc8 @NoamB Initial commit to simple_auth.
authored
258 == Copyright
259
260
4fe9ba3 @NoamB updated readme
authored
261 Copyright (c) 2010 Noam Ben Ari (nbenari@gmail.com). See LICENSE.txt for further details.
Something went wrong with that request. Please try again.