Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 210 lines (145 sloc) 15.118 kB
43e849c @binarylogic Released v0.10.4
authored
1 = Authlogic
1b98335 @binarylogic Initial commit
authored
2
605162d @binarylogic Release v2.0 RC1
authored
3 Authlogic is a clean, simple, and unobtrusive ruby authentication solution.
1b98335 @binarylogic Initial commit
authored
4
ec82400 @binarylogic Make the README simpler and more to-the-point
authored
5 A code example can replace a thousand words...
6
8c8e079 @binarylogic Release v2.0.11
authored
7 Authlogic introduces a new type of model. You can have as many as you want, and name them whatever you want, just like your other models. In this example we want to authenticate with the User model, which is inferred by the name:
ec82400 @binarylogic Make the README simpler and more to-the-point
authored
8
9 class UserSession < Authlogic::Session::Base
10 end
11
12 Log in with any of the following. Use it just like your other models:
13
14 UserSession.create(my_user_object)
15 UserSession.create(:login => "bjohnson", :password => "my password")
16 session = UserSession.new(:login => "bjohnson", :password => "my password"); session.save
17 UserSession.create(:openid_identifier => "identifier") # requires the authlogic-oid "add on" gem
18
8c8e079 @binarylogic Release v2.0.11
authored
19 After a session has been created, you can persist it across requests. Thus keeping the user logged in:
1b98335 @binarylogic Initial commit
authored
20
ec82400 @binarylogic Make the README simpler and more to-the-point
authored
21 session = UserSession.find
af4f7e0 @binarylogic Documentation fix for using AES as an encryption method.
authored
22
ec82400 @binarylogic Make the README simpler and more to-the-point
authored
23 You can also log out / destroy the session:
24
25 session.destroy
9bca67d @binarylogic Reorganized ORM code and tests
authored
26
605162d @binarylogic Release v2.0 RC1
authored
27 == Helpful links
28
29 * <b>Documentation:</b> http://authlogic.rubyforge.org
eb3f1f2 @binarylogic * HTTP basic auth can now be toggled on or off. It also checks for th…
authored
30 * <b>Repository:</b> http://github.com/binarylogic/authlogic/tree/master
a99a748 @binarylogic Update links
authored
31 * <b>Live example with OpenID "add on":</b> http://authlogicexample.binarylogic.com
d23f64e @binarylogic Add some comments on testing Authlogic, with a link to Authlogic::Tes…
authored
32 * <b>Live example repository with tutorial:</b> http://github.com/binarylogic/authlogic_example/tree/master
605162d @binarylogic Release v2.0 RC1
authored
33 * <b>Tutorial: Reset passwords with Authlogic the RESTful way:</b> http://www.binarylogic.com/2008/11/16/tutorial-reset-passwords-with-authlogic
34 * <b>Bugs / feature suggestions:</b> http://binarylogic.lighthouseapp.com/projects/18752-authlogic
35 * <b>Google group:</b> http://groups.google.com/group/authlogic
36
d23f64e @binarylogic Add some comments on testing Authlogic, with a link to Authlogic::Tes…
authored
37 <b>Before contacting me directly, please read:</b>
51f7b28 @binarylogic * Reset the @password_changed instance variable after the record has …
authored
38
d23f64e @binarylogic Add some comments on testing Authlogic, with a link to Authlogic::Tes…
authored
39 If you find a bug or a problem please post it on lighthouse. If you need help with something, please use google groups. I check both regularly and get emails when anything happens, so that is the best place to get help. This also benefits other people in the future with the same questions / problems. Thank you.
ee1f49b @binarylogic * Use MockCookieJar in tests instead of a Hash.
authored
40
5c0ac4f @binarylogic * Make password and login fields optional. This allows you to have an…
authored
41 == Authlogic "add ons"
ee1f49b @binarylogic * Use MockCookieJar in tests instead of a Hash.
authored
42
43 * <b>Authlogic OpenID addon:</b> http://github.com/binarylogic/authlogic_openid
51f7b28 @binarylogic * Reset the @password_changed instance variable after the record has …
authored
44 * <b>Authlogic LDAP addon:</b> http://github.com/binarylogic/authlogic_ldap
ee1f49b @binarylogic * Use MockCookieJar in tests instead of a Hash.
authored
45
ec82400 @binarylogic Make the README simpler and more to-the-point
authored
46 If you create one of your own, please let me know about it so I can add it to this list. Or just fork the project, add your link, and send me a pull request.
605162d @binarylogic Release v2.0 RC1
authored
47
ec82400 @binarylogic Make the README simpler and more to-the-point
authored
48 == Documentation explanation
605162d @binarylogic Release v2.0 RC1
authored
49
d23f64e @binarylogic Add some comments on testing Authlogic, with a link to Authlogic::Tes…
authored
50 You can find anything you want about Authlogic in the {documentation}, all that you need to do is understand the basic design behind it.
605162d @binarylogic Release v2.0 RC1
authored
51
ec82400 @binarylogic Make the README simpler and more to-the-point
authored
52 That being said, there are 2 models involved during authentication. Your Authlogic model and your ActiveRecord model:
605162d @binarylogic Release v2.0 RC1
authored
53
d23f64e @binarylogic Add some comments on testing Authlogic, with a link to Authlogic::Tes…
authored
54 1. <b>Authlogic::Session</b>, your session models that extend Authlogic::Session::Base.
55 2. <b>Authlogic::ActsAsAuthentic</b>, which adds in functionality to your ActiveRecord model when you call acts_as_authentic.
605162d @binarylogic Release v2.0 RC1
authored
56
0823cc7 @binarylogic Releast v2.0.10
authored
57 Each of the above has its various sub modules that contain common logic. The sub modules are responsible for including *everything* related to it: configuration, class methods, instance methods, etc.
605162d @binarylogic Release v2.0 RC1
authored
58
d1bf2d1 @binarylogic Fix some RDOC syntax mistakes
authored
59 For example, if you want to timeout users after a certain period of inactivity, you would look in <b>Authlogic::Session::Timeout</b>. To help you out, I listed the following "publicly relevant" modules with short descriptions. For the sake of brevity, there are more modules than listed here, the ones not listed are more for internal use, but you can easily read up on them in the {documentation}[http://authlogic.rubyforge.org].
605162d @binarylogic Release v2.0 RC1
authored
60
c355cdd @binarylogic Some documentation clean up
authored
61 === Authlogic::ActsAsAuthentic sub modules
605162d @binarylogic Release v2.0 RC1
authored
62
d23f64e @binarylogic Add some comments on testing Authlogic, with a link to Authlogic::Tes…
authored
63 These modules are for the ActiveRecord side of things, the models that call acts_as_authentic.
605162d @binarylogic Release v2.0 RC1
authored
64
d1bf2d1 @binarylogic Fix some RDOC syntax mistakes
authored
65 * <b>Authlogic::ActsAsAuthentic::Base</b> - Provides the acts_as_authentic class method and includes all of the submodules.
66 * <b>Authlogic::ActsAsAuthentic::Email</b> - Handles everything related to the email field.
67 * <b>Authlogic::ActsAsAuthentic::LoggedInStatus</b> - Provides handy named scopes and methods for determining if the user is logged in or out.
68 * <b>Authlogic::ActsAsAuthentic::Login</b> - Handles everything related to the login field.
69 * <b>Authlogic::ActsAsAuthentic::MagicColumns</b> - Handles everything related to the "magic" fields: login_count, failed_login_count, etc.
70 * <b>Authlogic::ActsAsAuthentic::Password</b> - This one is important. It handles encrypting your password, salting it, etc. It also has support for transitioning password algorithms.
71 * <b>Authlogic::ActsAsAuthentic::PerishableToken</b> - Handles maintaining the perishable token field, also provides a class level method for finding record using the token.
72 * <b>Authlogic::ActsAsAuthentic::PersistenceToken</b> - Handles maintaining the persistence token. This is the token stored in cookies and sessions to persist the users session.
73 * <b>Authlogic::ActsAsAuthentic::RestfulAuthentication</b> - Provides configuration options to easily migrate from the restful_authentication plugin.
74 * <b>Authlogic::ActsAsAuthentic::SessionMaintenance</b> - Handles automatically logging the user in. EX: a new user registers, automatically log them in.
75 * <b>Authlogic::ActsAsAuthentic::SingleAccessToken</b> - Handles maintaining the single access token.
76 * <b>Authlogic::ActsAsAuthentic::ValidationsScope</b> - Allows you to scope validations, etc. Just like the :scope option for validates_uniqueness_of
605162d @binarylogic Release v2.0 RC1
authored
77
c355cdd @binarylogic Some documentation clean up
authored
78 === Authlogic::Session sub modules
605162d @binarylogic Release v2.0 RC1
authored
79
d23f64e @binarylogic Add some comments on testing Authlogic, with a link to Authlogic::Tes…
authored
80 These modules are for the models that extend Authlogic::Session::Base.
605162d @binarylogic Release v2.0 RC1
authored
81
d1bf2d1 @binarylogic Fix some RDOC syntax mistakes
authored
82 * <b>Authlogic::Session::BruteForceProtection</b> - Disables accounts after a certain number of consecutive failed logins attempted.
83 * <b>Authlogic::Session::Callbacks</b> - Your tools to extend, change, or add onto Authlogic. Lets you hook in and do just about anything you want. Start here if you want to write a plugin or add on for Authlogic
84 * <b>Authlogic::Session::Cookies</b> - Authentication via cookies.
85 * <b>Authlogic::Session::Existence</b> - Creating, saving, and destroying objects.
86 * <b>Authlogic::Session::HttpAuth</b> - Authentication via basic HTTP authentication.
87 * <b>Authlogic::Session::Id</b> - Allows sessions to be separated by an id, letting you have multiple sessions for a single user.
88 * <b>Authlogic::Session::MagicColumns</b> - Maintains "magic" database columns, similar to created_at and updated_at for ActiveRecord.
89 * <b>Authlogic::Session::MagicStates</b> - Automatically validates based on the records states: active?, approved?, and confirmed?. If those methods exist for the record.
90 * <b>Authlogic::Session::Params</b> - Authentication via params, aka single access token.
91 * <b>Authlogic::Session::Password</b> - Authentication via a traditional username and password.
92 * <b>Authlogic::Session::Persistence</b> - Persisting sessions / finding sessions.
93 * <b>Authlogic::Session::Session</b> - Authentication via the session, the controller session that is.
94 * <b>Authlogic::Session::Timeout</b> - Automatically logging out after a certain period of inactivity.
95 * <b>Authlogic::Session::UnauthorizedRecord</b> - Handles authentication by passing an ActiveRecord object.
96 * <b>Authlogic::Session::Validation</b> - Validation / errors.
2155477 @binarylogic Updated readme
authored
97
605162d @binarylogic Release v2.0 RC1
authored
98 === Miscellaneous modules
43e849c @binarylogic Released v0.10.4
authored
99
d23f64e @binarylogic Add some comments on testing Authlogic, with a link to Authlogic::Tes…
authored
100 Miscellaneous modules that shared across the authentication process and are more "utility" modules and classes.
78f5bef @binarylogic Restructure configuration for acts_as_authentic
authored
101
d1bf2d1 @binarylogic Fix some RDOC syntax mistakes
authored
102 * <b>Authlogic::AuthenticatesMany</b> - Responsible for allowing you to scope sessions to a parent record. Similar to a has_many and belongs_to relationship. This lets you do the same thing with sessions.
103 * <b>Authlogic::CryptoProviders</b> - Contains various encryption algorithms that Authlogic uses, allowing you to choose your encryption method.
104 * <b>Authlogic::I18n</b> - Acts JUST LIKE the rails I18n library, and provides internationalization to Authlogic.
105 * <b>Authlogic::Random</b> - A simple class to generate random tokens.
106 * <b>Authlogic::TestCase</b> - Various helper methods for testing frameworks to help you test your code.
107 * <b>Authlogic::Version</b> - A handy class for determine the version of Authlogic in a number of ways.
605162d @binarylogic Release v2.0 RC1
authored
108
0823cc7 @binarylogic Releast v2.0.10
authored
109 == Quick Rails example
605162d @binarylogic Release v2.0 RC1
authored
110
111 What if creating sessions worked like an ORM library on the surface...
e77ca8a @binarylogic Updated readme
authored
112
4b1f8fa @binarylogic User column_names instead of colums when determining if a column exists
authored
113 UserSession.create(params[:user_session])
e77ca8a @binarylogic Updated readme
authored
114
34b225c @binarylogic Updated readme
authored
115 What if your user sessions controller could look just like your other controllers...
1b98335 @binarylogic Initial commit
authored
116
117 class UserSessionsController < ApplicationController
118 def new
119 @user_session = UserSession.new
120 end
121
122 def create
123 @user_session = UserSession.new(params[:user_session])
35f14ba @binarylogic Released v0.10.0
authored
124 if @user_session.save
c93bec2 @binarylogic Changed scope to id
authored
125 redirect_to account_url
1b98335 @binarylogic Initial commit
authored
126 else
127 render :action => :new
128 end
129 end
130
131 def destroy
ebdebfa @binarylogic Released v1.1.1
authored
132 current_user_session.destroy
4caccd0 @binarylogic Released 1.2.1
authored
133 redirect_to new_user_session_url
1b98335 @binarylogic Initial commit
authored
134 end
135 end
136
605162d @binarylogic Release v2.0 RC1
authored
137 As you can see, this fits nicely into the RESTful development pattern. What about the view...
1b98335 @binarylogic Initial commit
authored
138
139 <% form_for @user_session do |f| %>
791f700 @binarylogic Released v1.0.0 (see changelog)
authored
140 <%= f.error_messages %>
1b98335 @binarylogic Initial commit
authored
141 <%= f.label :login %><br />
142 <%= f.text_field :login %><br />
143 <br />
144 <%= f.label :password %><br />
145 <%= f.password_field :password %><br />
146 <br />
147 <%= f.submit "Login" %>
148 <% end %>
149
34b225c @binarylogic Updated readme
authored
150 Or how about persisting the session...
1b98335 @binarylogic Initial commit
authored
151
152 class ApplicationController
ebdebfa @binarylogic Released v1.1.1
authored
153 helper_method :current_user_session, :current_user
1b98335 @binarylogic Initial commit
authored
154
dbd8b8f @binarylogic Release v1.2.0
authored
155 private
ebdebfa @binarylogic Released v1.1.1
authored
156 def current_user_session
157 return @current_user_session if defined?(@current_user_session)
158 @current_user_session = UserSession.find
159 end
160
69f2c2b @binarylogic Add a logout_on_timeout configuration option for Session::Base
authored
161 def current_user
ebdebfa @binarylogic Released v1.1.1
authored
162 return @current_user if defined?(@current_user)
163 @current_user = current_user_session && current_user_session.user
1b98335 @binarylogic Initial commit
authored
164 end
165 end
166
0f38680 @binarylogic Update README and move setup tutorial to authlogic_example
authored
167 == Install & Use
c355cdd @binarylogic Some documentation clean up
authored
168
93a4787 @binarylogic Added Sha1 crypto provider to help with the restful_authentication tr…
authored
169 Install the gem / plugin (recommended)
1b98335 @binarylogic Initial commit
authored
170
43e849c @binarylogic Released v0.10.4
authored
171 $ sudo gem install authlogic
1b98335 @binarylogic Initial commit
authored
172
62ac95a @binarylogic Added should_be_authentic shoulda macro
authored
173 Now add the gem dependency in your config:
1d38644 @binarylogic Added last_request_at_threshold cconfig option
authored
174
93a4787 @binarylogic Added Sha1 crypto provider to help with the restful_authentication tr…
authored
175 # config/environment.rb
ebdebfa @binarylogic Released v1.1.1
authored
176 config.gem "authlogic"
93a4787 @binarylogic Added Sha1 crypto provider to help with the restful_authentication tr…
authored
177
62ac95a @binarylogic Added should_be_authentic shoulda macro
authored
178 Or you install this as a plugin (for older versions of rails)
1b98335 @binarylogic Initial commit
authored
179
43e849c @binarylogic Released v0.10.4
authored
180 script/plugin install git://github.com/binarylogic/authlogic.git
1b98335 @binarylogic Initial commit
authored
181
0823cc7 @binarylogic Releast v2.0.10
authored
182 == Detailed Setup Tutorial
35f14ba @binarylogic Released v0.10.0
authored
183
0823cc7 @binarylogic Releast v2.0.10
authored
184 See the {authlogic example}[http://github.com/binarylogic/authlogic_example/tree/master] for a detailed setup tutorial. I did this because not only do you have a tutorial to go by, but you have an example app that uses the same tutorial, so you can play around with with the code. If you have problems you can compare the code to see what you are doing differently.
40267c6 @binarylogic Update README with more thoroughh tutorial, the tutorial on my blog w…
authored
185
d23f64e @binarylogic Add some comments on testing Authlogic, with a link to Authlogic::Tes…
authored
186 == Testing
187
188 I think one of the best aspects of Authlogic is testing. For one, it cuts out <b>a lot</b> of redundant tests in your applications because Authlogic is already thoroughly tested for you. It doesn't include a bunch of tests into your application, because it comes tested, just like any other library.
189
190 For example, think about ActiveRecord. You don't test the internals of ActiveRecord, because the creators of ActiveRecord have already tested the internals for you. It wouldn't make sense for ActiveRecord to copy it's hundreds of tests into your applications. The same concept applies to Authlogic. You only need to test code you write that is specific to your application, just like everything else in your application.
191
8c8e079 @binarylogic Release v2.0.11
authored
192 That being said, testing your code that uses Authlogic is easy. Since everyone uses different testing suites, I created a helpful module called Authlogic::TestCase, which is basically a set of tools for testing code using Authlogic. I explain testing Authlogic thoroughly in the {Authlogic::TestCase section of the documentation}[http://authlogic.rubyforge.org/classes/Authlogic/TestCase.html]. It should answer any questions you have in regards to testing Authlogic.
d23f64e @binarylogic Add some comments on testing Authlogic, with a link to Authlogic::Tes…
authored
193
ec82400 @binarylogic Make the README simpler and more to-the-point
authored
194 == Tell me quickly how Authlogic works
2155477 @binarylogic Updated readme
authored
195
ec82400 @binarylogic Make the README simpler and more to-the-point
authored
196 Interested in how all of this all works? Think about an ActiveRecord model. A database connection must be established before you can use it. In the case of Authlogic, a controller connection must be established before you can use it. It uses that controller connection to modify cookies, the current session, login with HTTP basic, etc. It connects to the controller through a before filter that is automatically set in your controller which lets Authlogic know about the current controller object. Then Authlogic leverages that to do everything, it's a pretty simple design.
2155477 @binarylogic Updated readme
authored
197
ec82400 @binarylogic Make the README simpler and more to-the-point
authored
198 == What sets Authlogic apart and why I created it
2155477 @binarylogic Updated readme
authored
199
8c8e079 @binarylogic Release v2.0.11
authored
200 What inspired me to create Authlogic was the messiness of the current authentication solutions. Put simply, they just didn't feel right, because the logic was not organized properly. As you may know, a common misconception with the MVC design pattern is that the model "M" is only for data access logic, which is wrong. A model is a place for domain logic. This is why the RESTful design pattern and the current authentication solutions don't play nice. Authlogic solves this by placing the session maintenance logic into its own domain (aka "model"). Moving session maintenance into its own domain has its benefits:
ec0eb78 @binarylogic Updated readme
authored
201
ec82400 @binarylogic Make the README simpler and more to-the-point
authored
202 1. <b>It's cleaner.</b> There are no generators in Authlogic. Authlogic provides a class that you can use, it's plain and simple ruby. More importantly, the code in your app is code you write, written the way you want, nice and clean. It's code that should be in your app and is specific to your app, not a redundant authentication pattern.
2af08ab @binarylogic Add a quick model explanation in the README
authored
203 2. <b>Easier to stay up-to-date.</b> To make my point, take a look at the commits to any other authentication solution, then look at the {commits for authlogic}[http://github.com/binarylogic/authlogic/commits/master]. How many commits could you easily start using if you already had an app using that solution? With an alternate solution, very few, if any. All of those cool new features and bug fixes are going to have be manually added or wait for your next application. Which is the main reason a generator is not suitable as an authentication solution. With Authlogic you can start using the latest code with a simple update of a gem. No generators, no mess.
ec82400 @binarylogic Make the README simpler and more to-the-point
authored
204 3. <b>It ties everything together on the domain level.</b> Take a new user registration for example, no reason to manually log the user in, authlogic handles this for you via callbacks. The same applies to a user changing their password. Authlogic handles maintaining the session for you.
205 4. <b>No redundant tests.</b> Because Authlogic doesn't use generators, #1 also applies to tests. Authlogic is *thoroughly* tested for you. You don't go and test the internals of ActiveRecord in each of your apps do you? So why do the same for Authlogic? Your application tests should be for application specific code. Get rid of the noise and make your tests focused and concise, no reason to copy tests from app to app.
206 5. <b>You are not restricted to a single session.</b> Think about Apple's me.com, where they need you to authenticate a second time before changing your billing information. Why not just create a second session for this? It works just like your initial session. Then your billing controller can require an "ultra secure" session.
207 6. <b>Easily extendable.</b> One of the distinct advantages of using a library is the ability to use it's API, assuming it has one. Authlogic has an *excellent* public API, meaning it can easily be extended and grow beyond the core library. Checkout the "add ons" list above to see what I mean.
ec0eb78 @binarylogic Updated readme
authored
208
1b98335 @binarylogic Initial commit
authored
209
0823cc7 @binarylogic Releast v2.0.10
authored
210 Copyright (c) 2009 {Ben Johnson of Binary Logic}[http://www.binarylogic.com], released under the MIT license
Something went wrong with that request. Please try again.