Class: Authlogic::Session::Base

Inherits:
Object
  • Object
show all
Includes:
Authlogic::Session, ActiveRecordTrickery, BruteForceProtection, Callbacks, Config, Cookies, Params, Perishability, RecordInfo, Scopes, Timeout
Defined in:
lib/authlogic/session/base.rb,
lib/authlogic.rb

Overview

Base

This is the muscle behind Authlogic. For detailed information on how to use this please refer to the README. For detailed method explanations see below.

Constant Summary

Constants included from Callbacks

Callbacks::METHODS

Class Attribute Summary collapse

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Config

included

Methods included from Timeout

#find_record_with_timeout, included, #stale?

Methods included from Scopes

included

Methods included from RecordInfo

included

Methods included from Perishability

included

Methods included from Params

#valid_params?

Methods included from Cookies

included, #valid_cookie?

Methods included from BruteForceProtection

included, #reset_failed_login_count

Methods included from Callbacks

included

Methods included from ActiveRecordTrickery

included

Constructor Details

#initialize(*args) ⇒ Base

You can initialize a session by doing any of the following:

UserSession.new
UserSession.new(:login => "login", :password => "password", :remember_me => true)
UserSession.new(User.first, true)

If a user has more than one session you need to pass an id so that Authlogic knows how to differentiate the sessions. The id MUST be a Symbol.

UserSession.new(:my_id)
UserSession.new({:login => "login", :password => "password", :remember_me => true}, :my_id)
UserSession.new(User.first, true, :my_id)

For more information on ids see the id method.

Lastly, the reason the id is separate from the first parameter hash is becuase this should be controlled by you, not by what the user passes. A user could inject their own id and things would not work as expected.

Raises:



116
117
118
119
120
121
122
123
124
125
126
127
128
129
 
# File 'lib/authlogic/session/base.rb', line 116

def initialize(*args)
  raise NotActivated.new(self) unless self.class.activated?
  
  create_configurable_methods!
  
  self.id = args.pop if args.last.is_a?(Symbol)
  
  if args.first.is_a?(Hash)
    self.credentials = args.first
  elsif !args.first.blank? && args.first.class < ::ActiveRecord::Base
    self.unauthorized_record = args.first
    self.remember_me = args[1] if args.size > 1
  end
end

Class Attribute Details

.methods_configured ⇒ Object

Returns the value of attribute methods_configured.



10
11
12
 
# File 'lib/authlogic/session/base.rb', line 10

def methods_configured
  @methods_configured
end

Instance Attribute Details

#attempted_record ⇒ Object

Returns the value of attribute attempted_record.



96
97
98
 
# File 'lib/authlogic/session/base.rb', line 96

def attempted_record
  @attempted_record
end

#authenticating_with ⇒ Object

A flag for how the user is logging in. Possible values:

  • :password - username and password

  • :unauthorized_record - an actual ActiveRecord object

By default this is :password



137
138
139
 
# File 'lib/authlogic/session/base.rb', line 137

def authenticating_with
  @authenticating_with ||= :password
end

#id ⇒ Object

Allows you to set a unique identifier for your session, so that you can have more than 1 session at a time. A good example when this might be needed is when you want to have a normal user session and a “secure” user session. The secure user session would be created only when they want to modify their billing information, or other sensitive information. Similar to me.com. This requires 2 user sessions. Just use an id for the “secure” session and you should be good.

You can set the id during initialization (see initialize for more information), or as an attribute:

session.id = :my_id

Just be sure and set your id before you save your session.

Lastly, to retrieve your session with the id check out the find class method.



224
225
226
 
# File 'lib/authlogic/session/base.rb', line 224

def id
  @id
end

#new_session ⇒ Object

Returns the value of attribute new_session.



96
97
98
 
# File 'lib/authlogic/session/base.rb', line 96

def new_session
  @new_session
end

#persisting ⇒ Object

:nodoc:



245
246
247
248
 
# File 'lib/authlogic/session/base.rb', line 245

def persisting # :nodoc:
  return @persisting if defined?(@persisting)
  @persisting = true
end

#record ⇒ Object

Returns the value of attribute record.



96
97
98
 
# File 'lib/authlogic/session/base.rb', line 96

def record
  @record
end

#unauthorized_record ⇒ Object

Returns the value of attribute unauthorized_record.



97
98
99
 
# File 'lib/authlogic/session/base.rb', line 97

def unauthorized_record
  @unauthorized_record
end

Class Method Details

.activated? ⇒ Boolean

Returns true if a controller has been set and can be used properly. This MUST be set before anything can be done. Similar to how ActiveRecord won’t allow you to do anything without establishing a DB connection. In your framework environment this is done for you, but if you are using Authlogic outside of your framework, you need to assign a controller object to Authlogic via Authlogic::Session::Base.controller = obj. See the controller= method for more information.

Returns:

  • (Boolean) 


15
16
17
 
# File 'lib/authlogic/session/base.rb', line 15

def activated?
  !controller.nil?
end

.controller ⇒ Object

:nodoc:



25
26
27
 
# File 'lib/authlogic/session/base.rb', line 25

def controller # :nodoc:
  Thread.current[:authlogic_controller]
end

.controller=(value) ⇒ Object

This accepts a controller object wrapped with the Authlogic controller adapter. The controller adapters close the gap between the different controllers in each framework. That being said, Authlogic is expecting your object’s class to extend Authlogic::ControllerAdapters::AbstractAdapter. See Authlogic::ControllerAdapters for more info.



21
22
23
 
# File 'lib/authlogic/session/base.rb', line 21

def controller=(value)
  Thread.current[:authlogic_controller] = value
end

.create(*args, &block) ⇒ Object

A convenince method. The same as:

session = UserSession.new
session.create



33
34
35
36
 
# File 'lib/authlogic/session/base.rb', line 33

def create(*args, &block)
  session = new(*args)
  session.save(&block)
end

.create!(*args) ⇒ Object

Same as create but calls create!, which raises an exception when authentication fails.



39
40
41
42
 
# File 'lib/authlogic/session/base.rb', line 39

def create!(*args)
  session = new(*args)
  session.save!
end

.find(id = nil, priority_record = nil) ⇒ Object

A convenience method for session.find_record. Finds your session by parameters, then session, then cookie, and finally by basic http auth. This is perfect for persisting your session:

helper_method :current_user_session, :current_user

def current_user_session
  return @current_user_session if defined?(@current_user_session)
  @current_user_session = UserSession.find
end

def current_user
  return @current_user if defined?(@current_user)
  @current_user = current_user_session && current_user_session.user
end

Accepts a single parameter as the id, to find session that you marked with an id:

UserSession.find(:secure)

See the id method for more information on ids.



64
65
66
67
68
69
70
71
72
73
74
 
# File 'lib/authlogic/session/base.rb', line 64

def find(id = nil, priority_record = nil)
  session = new(id)
  session.before_find
  if record = session.find_record
    session.after_find
    record.save_without_session_maintenance(false) if record.changed? && record != priority_record
    session
  else
    nil
  end
end

.klass ⇒ Object

The name of the class that this session is authenticating with. For example, the UserSession class will authenticate with the User class unless you specify otherwise in your configuration. See authenticate_with for information on how to change this value.



78
79
80
81
82
83
84
85
 
# File 'lib/authlogic/session/base.rb', line 78

def klass
  @klass ||=
    if klass_name
      klass_name.constantize
    else
      nil
    end
end

.klass_name ⇒ Object

Same as klass, just returns a string instead of the actual constant.



88
89
90
91
92
93
 
# File 'lib/authlogic/session/base.rb', line 88

def klass_name
  @klass_name ||= 
    if guessed_name = name.scan(/(.*)Session/)[0]
      @klass_name = guessed_name[0]
    end
end

Instance Method Details

#authenticating_with_password? ⇒ Boolean

Returns true if logging in with credentials. Credentials mean username and password.

Returns:

  • (Boolean) 


142
143
144
 
# File 'lib/authlogic/session/base.rb', line 142

def authenticating_with_password?
  authenticating_with == :password
end

#authenticating_with_unauthorized_record? ⇒ Boolean Also known as: authenticating_with_record?

Returns true if logging in with an unauthorized record

Returns:

  • (Boolean) 


147
148
149
 
# File 'lib/authlogic/session/base.rb', line 147

def authenticating_with_unauthorized_record?
  authenticating_with == :unauthorized_record
end

#credentials ⇒ Object

Your login credentials in hash format. Usually => “my login”, :password => “<protected>” depending on your configuration. Password is protected as a security measure. The raw password should never be publicly accessible.



154
155
156
 
# File 'lib/authlogic/session/base.rb', line 154

def credentials
  { => send(), password_field => "<Protected>"}
end

#credentials=(values) ⇒ Object

Lets you set your loging and password via a hash format. This is “params” safe. It only allows for 3 keys: your login field name, password field name, and remember me.



159
160
161
162
163
164
165
166
 
# File 'lib/authlogic/session/base.rb', line 159

def credentials=(values)
  return if values.blank? || !values.is_a?(Hash)
  values.symbolize_keys!
  values.each do |field, value|
    next if value.blank?
    send("#{field}=", value)
  end
end

#destroy ⇒ Object

Resets everything, your errors, record, cookies, and session. Basically “logs out” a user.



169
170
171
172
173
174
175
176
177
178
 
# File 'lib/authlogic/session/base.rb', line 169

def destroy
  before_destroy
  
  errors.clear
  @record = nil
  
  after_destroy
  
  true
end

#errors ⇒ Object

The errors in Authlogic work JUST LIKE ActiveRecord. In fact, it uses the exact same ActiveRecord errors class. Use it the same way:

Example

class UserSession
  before_validation :check_if_awesome

  private
    def check_if_awesome
      errors.add(:login, "must contain awesome") if  && !.include?("awesome")
      errors.add_to_base("You must be awesome to log in") unless record.awesome?
    end
end



193
194
195
 
# File 'lib/authlogic/session/base.rb', line 193

def errors
  @errors ||= Errors.new(self)
end

#find_record ⇒ Object

Attempts to find the record by params, then session, then cookie, and finally basic http auth. See the class level find method if you are wanting to use this to persist your session.



198
199
200
201
202
203
204
205
206
207
208
209
210
211
 
# File 'lib/authlogic/session/base.rb', line 198

def find_record
  if record
    self.new_session = false
    return record
  end
  
  find_with.each do |find_method|
    if send("valid_#{find_method}?")
      self.new_session = false
      return record
    end
  end
  nil
end

#inspect ⇒ Object

:nodoc:



228
229
230
231
232
233
234
235
236
237
238
 
# File 'lib/authlogic/session/base.rb', line 228

def inspect # :nodoc:
  details = {}
  case authenticating_with
  when :unauthorized_record
    details[:unauthorized_record] = "<protected>"
  else
    details[.to_sym] = send()
    details[password_field.to_sym] = "<protected>"
  end
  "#<#{self.class.name} #{details.inspect}>"
end

#new_session? ⇒ Boolean

Similar to ActiveRecord’s new_record? Returns true if the session has not been saved yet.

Returns:

  • (Boolean) 


241
242
243
 
# File 'lib/authlogic/session/base.rb', line 241

def new_session?
  new_session != false
end

#persisting? ⇒ Boolean

Returns true if the session is being persisted. This is set to false if the session was found by the single_access_token, since logging in via a single access token should not remember the user in the session or the cookie.

Returns:

  • (Boolean) 


252
253
254
 
# File 'lib/authlogic/session/base.rb', line 252

def persisting?
  persisting == true
end

#remember_me ⇒ Object

:nodoc:



256
257
258
259
 
# File 'lib/authlogic/session/base.rb', line 256

def remember_me # :nodoc:
  return @remember_me if defined?(@remember_me)
  @remember_me = self.class.remember_me
end

#remember_me=(value) ⇒ Object

Accepts a boolean as a flag to remember the session or not. Basically to expire the cookie at the end of the session or keep it for “remember_me_until”.



262
263
264
 
# File 'lib/authlogic/session/base.rb', line 262

def remember_me=(value)
  @remember_me = value
end

#remember_me? ⇒ Boolean

Allows users to be remembered via a cookie.

Returns:

  • (Boolean) 


267
268
269
 
# File 'lib/authlogic/session/base.rb', line 267

def remember_me?
  remember_me == true || remember_me == "true" || remember_me == "1"
end

#remember_me_until ⇒ Object

When to expire the cookie. See remember_me_for configuration option to change this.



272
273
274
275
 
# File 'lib/authlogic/session/base.rb', line 272

def remember_me_until
  return unless remember_me?
  remember_me_for.from_now
end

#save {|result| ... } ⇒ Object

Creates / updates a new user session for you. It does all of the magic:

  1. validates

  2. sets session

  3. sets cookie

  4. updates magic fields

Yields:

  • (result) 


283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
 
# File 'lib/authlogic/session/base.rb', line 283

def save(&block)
  result = nil
  if valid?
    # hooks
    before_save
    new_session? ? before_create : before_update
    new_session? ? after_create : after_update
    after_save
    
    record.save_without_session_maintenance(false) if record.changed?
    self.new_session = false
    result = self
  else
    result = false
  end
  
  yield result if block_given?
  result
end

#save! ⇒ Object

Same as save but raises an exception when authentication fails

Raises:



304
305
306
307
308
 
# File 'lib/authlogic/session/base.rb', line 304

def save!
  result = save
  raise SessionInvalid.new(self) unless result
  result
end

#valid? ⇒ Boolean

Returns if the session is valid or not. Basically it means that a record could or could not be found. If the session is valid you will have a result when calling the “record” method. If it was unsuccessful you will not have a record.

Returns:

  • (Boolean) 


323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
 
# File 'lib/authlogic/session/base.rb', line 323

def valid?
  errors.clear
  self.attempted_record = nil
  
  before_validation
  new_session? ? before_validation_on_create : before_validation_on_update
  valid_credentials?
  validate
  
  if errors.empty?
    new_session? ? after_validation_on_create : after_validation_on_update
    after_validation
  else
    self.record = nil
  end
  
  attempted_record.save_without_session_maintenance(false) if attempted_record && attempted_record.changed?
  self.attempted_record = nil
  errors.empty?
end

#valid_http_auth? ⇒ Boolean

Tries to validate the session from information from a basic http auth, if it was provided.

Returns:

  • (Boolean) 


345
346
347
348
349
350
351
352
353
354
355
 
# File 'lib/authlogic/session/base.rb', line 345

def valid_http_auth?
  controller.authenticate_with_http_basic do |, password|
    if !.blank? && !password.blank?
      send("#{}=", )
      send("#{password_field}=", password)
      return valid?
    end
  end
  
  false
end