Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 212 lines (144 sloc) 10.509 kb
1b98335 @binarylogic Initial commit
authored
1 = Authgasm
2
e77ca8a @binarylogic Updated readme
authored
3 Authgasm is "rails authentication done right"
1b98335 @binarylogic Initial commit
authored
4
ae1d3bb @binarylogic Released v0.9.1
authored
5 The last thing we need is another authentication solution for rails, right? That's what I thought. It was disappointing to find that all of the current solutions were overly complicated, bloated, poorly written, littered my application with code, and were just plain confusing. They felt very Microsoftish. This is not the simple / elegant rails we all fell in love with. It's like some Microsoft .NET engineers decided to dabble in ruby / rails for a day and their project was to write an authentication solution. That's what went through my head when I was trying out all of the current solutions. It's time someone makes a "rails like" authentication solution. So I give you Authgasm...
6
7 What if you could have authentication up and running in minutes without having to run a generator? All because it's simple, like everything else in rails.
1b98335 @binarylogic Initial commit
authored
8
34b225c @binarylogic Updated readme
authored
9 What if creating a user session could be as simple as...
e77ca8a @binarylogic Updated readme
authored
10
11 UserSession.create(params[:user])
12
34b225c @binarylogic Updated readme
authored
13 What if your user sessions controller could look just like your other controllers...
1b98335 @binarylogic Initial commit
authored
14
15 class UserSessionsController < ApplicationController
16 def new
17 @user_session = UserSession.new
18 end
19
20 def create
21 @user_session = UserSession.new(params[:user_session])
22 if @user_session.create
c93bec2 @binarylogic Changed scope to id
authored
23 redirect_to account_url
1b98335 @binarylogic Initial commit
authored
24 else
25 render :action => :new
26 end
27 end
28
29 def destroy
30 @user_session.destroy
31 end
32 end
33
34 Look familiar? If you didn't know any better, you would think UserSession was an ActiveRecord model. I think that's pretty cool. Why is that cool? Because it fits nicely into the RESTful development pattern and its a style we all know and love. Wouldn't this be cool too...
35
36 <%= error_messages_for "user_session" %>
37 <% form_for @user_session do |f| %>
38 <%= f.label :login %><br />
39 <%= f.text_field :login %><br />
40 <br />
41 <%= f.label :password %><br />
42 <%= f.password_field :password %><br />
43 <br />
44 <%= f.submit "Login" %>
45 <% end %>
46
34b225c @binarylogic Updated readme
authored
47 Or how about persisting the session...
1b98335 @binarylogic Initial commit
authored
48
49 class ApplicationController
50 before_filter :load_user
51
52 protected
53 def load_user
54 @user_session = UserSession.find
55 @current_user = @user_session && @user_session.record
56 end
57 end
58
34b225c @binarylogic Updated readme
authored
59 Authgasm makes this a reality. This is just the tip of the ice berg. Keep reading to find out everything Authgasm can do.
1b98335 @binarylogic Initial commit
authored
60
61 == Helpful links
62
63 * <b>Documentation:</b> http://authgasm.rubyforge.org
64 * <b>Authgasm tutorial:</b> coming soon...
65 * <b>Live example of the tutorial above (with source):</b> coming soon....
66 * <b>Bugs / feature suggestions:</b> http://binarylogic.lighthouseapp.com/projects/18752-authgasm
67
68 == Install and use
69
70 === Install the gem / plugin
71
72 $ sudo gem install authgasm
73 $ cd vendor/plugins
74 $ sudo gem unpack authgasm
75
76 Or as a plugin
77
78 script/plugin install git://github.com/binarylogic/authgasm.git
79
77798f2 @binarylogic Updated installation guide
authored
80 === Create your session
1b98335 @binarylogic Initial commit
authored
81
77798f2 @binarylogic Updated installation guide
authored
82 For this walk through lets assume you are setting up a session for your User model.
1b98335 @binarylogic Initial commit
authored
83
77798f2 @binarylogic Updated installation guide
authored
84 Create your user_session.rb file:
1b98335 @binarylogic Initial commit
authored
85
77798f2 @binarylogic Updated installation guide
authored
86 # app/models/user_session.rb
87 class UserSession < Authgasm::Session::Base
88 # configuration here, just like ActiveRecord, or in an initializer
89 # See Authgasm::Session::Config::ClassMethods for more details
90 end
1b98335 @binarylogic Initial commit
authored
91
ae1d3bb @binarylogic Released v0.9.1
authored
92 It is important to set your configuration for your session before you set the configuration for your model. This will save you some time. Your model will try to guess its own configuration based on what you set in the session. These are completely separate, making Authgasm as flexible as it needs to be, but the majority of the time they will be the same and no one likes to repeat their self.
1b98335 @binarylogic Initial commit
authored
93
3691177 @binarylogic Updated readme
authored
94 === Ensure proper database fields
1b98335 @binarylogic Initial commit
authored
95
96 The user model needs to have the following columns. The names of these columns can be changed with configuration.
97
98 t.string :login, :null => false
99 t.string :crypted_password, :null => false
100 t.string :password_salt, :null => false # not needed if you are encrypting your pw instead of using a hash algorithm
101 t.string :remember_token, :null => false
c00672f @binarylogic Updated automatic session maintenance
authored
102 t.integer :login_count # This is optional, it is a "magic" column, just like "created_at". See below for a list of all magic columns.
1b98335 @binarylogic Initial commit
authored
103
77798f2 @binarylogic Updated installation guide
authored
104 === Set up your model
1b98335 @binarylogic Initial commit
authored
105
77798f2 @binarylogic Updated installation guide
authored
106 Make sure you have a model that you will be authenticating with. For this example let's say you have a User model:
107
108 class User < ActiveRecord::Base
109 acts_as_authentic # for options see documentation: Authgasm::ActsAsAuthentic::ClassMethods
1b98335 @binarylogic Initial commit
authored
110 end
111
112 Done! Now go use it just like you would with any other ActiveRecord model (see above).
113
114 == Magic Columns
115
116 Just like ActiveRecord has "magic" columns, such as: created_at and updated_at. Authgasm has its own "magic" columns too:
117
118 Column name Description
ae1d3bb @binarylogic Released v0.9.1
authored
119 login_count Increased every time an explicit login is made. This will *NOT* increase if logging in by a session, cookie, or basic http auth
e77ca8a @binarylogic Updated readme
authored
120 last_request_at Updates every time the user logs in, either by explicitly logging in, or logging in by cookie, session, or http auth
1b98335 @binarylogic Initial commit
authored
121 current_login_at Updates with the current time when an explicit login is made.
122 last_login_at Updates with the value of current_login_at before it is reset.
123 current_login_ip Updates with the request remote_ip when an explicit login is made.
124 last_login_ip Updates with the value of current_login_ip before it is reset.
125
126 == Magic States
127
128 Authgasm tries to check the state of the record before creating the session. If your record responds to the following methods and any of them return false, validation will fail:
129
130 Method name Description
131 approved? Has the record been approved?
132 confirmed? Has the record been conirmed?
133 inactive? Is the record marked as inactive?
134
ff67374 @binarylogic Cleaned up identifier doc
authored
135 What's neat about this is that these are checked upon any type of login. When logging in explicitly, by cookie, session, or basic http auth. So if you mark a user inactive in the middle of their session they wont be logged back in next time they refresh the page. Giving you complete control.
1b98335 @binarylogic Initial commit
authored
136
137 == Hooks / Callbacks
138
139 Just like ActiveRecord you can create your own hooks / callbacks so that you can do whatever you want when certain actions are performed. Here they are:
140
141 before_create
142 after_create
143 before_destroy
144 after_destroy
145 before_update
146 after_update
147 before_validation
148 after_validation
149
150 == Automatic Session Updating
151
ae1d3bb @binarylogic Released v0.9.1
authored
152 This is one of my favorite features that I think its pretty cool. It's things like this that make a library great and let you know you are on the right track.
718f2cf @binarylogic Updated readme on session updating
authored
153
ae1d3bb @binarylogic Released v0.9.1
authored
154 What if a user changes their password? You have to re-log them in with the new password, recreate the session, etc, pain in the ass. Or what if a user creates a new user account? You have to do the same thing. Here's an even better one: what if a user is in the admin area and changes his own password? There might even be another place passwords can change. It shouldn't matter, your code should be written in a way where you don't have to remember to do this.
718f2cf @binarylogic Updated readme on session updating
authored
155
34b225c @binarylogic Updated readme
authored
156 Instead of updating sessions all over the place, doesn't it make sense to do this at a lower level? Like the User model? You're saying "but Ben, models can't mess around with sessions and cookies". True...but Authgasm can, and you can access Authgasm just like a model. I know in most situations it's not good practice to do this but I view this in the same class as sweepers, and feel like it actually is good practice here. User sessions are directly tied to users, they should be connected on the model level.
718f2cf @binarylogic Updated readme on session updating
authored
157
34b225c @binarylogic Updated readme
authored
158 Fear not, because the acts_as_authentic method you call in your model takes care of this for you, by adding an after_create and after_update callback to automatically keep the session up to date. You don't have to worry about it anymore. Don't even think about it. Let your UsersController deal with users, not users *AND* sessions. *ANYTIME* the user changes his password in *ANY* way, his session will be updated.
718f2cf @binarylogic Updated readme on session updating
authored
159
34b225c @binarylogic Updated readme
authored
160 Here is basically how this is done....
1b98335 @binarylogic Initial commit
authored
161
34b225c @binarylogic Updated readme
authored
162 class User < ActiveRecord::Base
163 after_create :create_sessions!
164 after_update :update_sessions!
165
166 private
167 def create_sessions!
168 # create a new UserSession if they are not logged in
169 end
170
171 def update_sessions!
172 # find their session
173 # check that their session's record is the same one as this one: session.record == self
174 # update the session with the new info: session.update
175 end
176 end
177
ae1d3bb @binarylogic Released v0.9.1
authored
178 Obviously there is a little more to it than this, but hopefully this clarifies any confusion. Lastly, this can be altered / disabled via a configuration option.
1b98335 @binarylogic Initial commit
authored
179
180 When things come together like this I think its a sign that you are doing something right. Put that in your pipe and smoke it!
181
ff67374 @binarylogic Cleaned up identifier doc
authored
182 == Multiple Sessions / Session Identifiers
bf796a0 @binarylogic Added info in the readme on multiple sessions
authored
183
184 You're asking: "why would I want multiple sessions?". Take this example:
185
ff67374 @binarylogic Cleaned up identifier doc
authored
186 You have an app where users login and then need to re-login to view / change their billing information. Similar to how Apples' me.com works, if you've ever used it. What you could do is have the user login with their normal session, then have an entirely new session that represents their "secure" session. But wait, this is 2 users sessions. No problem:
bf796a0 @binarylogic Added info in the readme on multiple sessions
authored
187
188 # regular user session
189 @user_session = UserSession.new
190 @user_session.id
191 # => nil
192
193 # secure user session
194 @secure_user_session = UserSession.new(:secure)
195 @secure_user_session.id
196 # => :secure
197
7c5c3cb @binarylogic Added info in the readme on multiple sessions
authored
198 This will keep everything separate. The :secure session will store its info in a separate cookie, separate session, etc. Just set the id and you are good to go. Need to retrieve the session?
199
200 @user_session = UserSession.find
201 @secure_user_session = UserSession.find(:secure)
202
203 For more information on ids checkout Authgasm::Session::Base#initialize
bf796a0 @binarylogic Added info in the readme on multiple sessions
authored
204
1b98335 @binarylogic Initial commit
authored
205 == How it works
206
ff67374 @binarylogic Cleaned up identifier doc
authored
207 Interested in how all of this all works? Basically a before_filter is automatically set in your controller which lets Authgasm know about the current controller object. This allows Authgasm to set sessions, cookies, login via basic http auth, etc. If you are using rails in a multiple thread environment, don't worry. I kept that in mind and made this is thread safe.
1b98335 @binarylogic Initial commit
authored
208
77798f2 @binarylogic Updated installation guide
authored
209 From there it is pretty simple. When you try to create a new session the record is authenticated and then all of the session / cookie magic is done for you. The sky is the limit.
1b98335 @binarylogic Initial commit
authored
210
211
212 Copyright (c) 2008 Ben Johnson of [Binary Logic](http://www.binarylogic.com), released under the MIT license
Something went wrong with that request. Please try again.