Parent

Included Modules

Files

Merb::Authentication

These are not intended to be used directly

Attributes

body[RW]
error_message[W]
session[RW]

Public Class Methods

activate!(label) click to toggle source

Activates a registered strategy by it’s label. Intended for use with plugin authors. There is little need to register your own strategies. Just declare them and they will be active.

# File lib/merb-auth-core/strategy.rb, line 40
def self.activate!(label)
  path = self.registered_strategies[label]
  raise "The #{label} Strategy is not registered" unless path
  require path
end
after_authentication(*callbacks, &block) click to toggle source

Use the after_authentication callbacks to setup things that should occur after the user is authenticated.

Pass in symbols, procs and or a block to the method to setup the callbacks. Callbacks are executed in the order they are added.

@params <*callbacks:> The callback.. Symbol == method on the user object

Proc will be passed the user, request and param objects

<&block> A block to check. The user, request and params will be passed into the block

To confirm that the user is still eligable to login, simply return the user from the method or block. To stop the user from being authenticated return false or nil

Example

Merb::Authentication.after_authentication do |user,request,params|
   user.active? ? user : nil
end

@api public

# File lib/merb-auth-core/callbacks.rb, line 28
def self.after_authentication(*callbacks, &block)
  self.after_callbacks = after_callbacks + callbacks.flatten unless callbacks.blank?
  after_callbacks << block if block_given?
end
customize_default(&block) click to toggle source

Adds any customizations just before the after_app_loads boot loader so that plugins can offer default customization. This will still allow for a user to overwrite any customizations if required in the after_app_loads block @plugin

# File lib/merb-auth-core/customizations.rb, line 11
def customize_default(&block)
  default_customizations << block
  default_customizations
end
default_customizations() click to toggle source

Gets the list of declared customizations

# File lib/merb-auth-core/customizations.rb, line 17
def default_customizations
  @custom_default_blocks ||= []
end
default_strategy_order=(*order) click to toggle source

Use this to set the default order of strategies if you need to in your application. You don’t need to use all avaiable strategies in this array, but you may not include a strategy that has not yet been defined.

@params [Merb::Authentiation::Strategy,Merb::Authentication::Strategy]

@public

# File lib/merb-auth-core/strategy.rb, line 13
def self.default_strategy_order=(*order)
  order = order.flatten
  bad = order.select{|s| !s.ancestors.include?(Strategy)}
  raise ArgumentError, "#{bad.join(",")} do not inherit from Merb::Authentication::Strategy" unless bad.empty?
  @@default_strategy_order = order
end
lookup_strategy() click to toggle source

Keeps track of strategies by class or string When loading from string, strategies are loaded withing the Merb::Authentication::Strategies namespace When loaded by class, the class is stored directly @private

# File lib/merb-auth-core/authentication.rb, line 152
def self.lookup_strategy
  @strategy_lookup || reset_strategy_lookup!
end
maintain_session_keys() click to toggle source

Maintains a list of keys to maintain when needing to keep some state in the face of session.abandon! You need to maintain this state yourself @public

# File lib/merb-auth-core/authentication.rb, line 171
def self.maintain_session_keys
  @maintain_session_keys ||= [:authentication_strategies]
end
new(session) click to toggle source
# File lib/merb-auth-core/authentication.rb, line 24
def initialize(session)
  @session = session
end
register(label, path) click to toggle source

Allows for the registration of strategies. @params <Symbol, String>

+label+ The label is the label to identify this strategy
+path+  The path to the file containing the strategy.  This must be an absolute path!

Registering a strategy does not add it to the list of strategies to use it simply makes it available through the Merb::Authentication.activate method

This is for plugin writers to make a strategy availalbe but this should not stop you from declaring your own strategies

@plugin

# File lib/merb-auth-core/strategy.rb, line 32
def self.register(label, path)
  self.registered_strategies[label] = path
end
reset_strategy_lookup!() click to toggle source

Restets the strategy lookup. Useful in specs

# File lib/merb-auth-core/authentication.rb, line 157
def self.reset_strategy_lookup!
  @strategy_lookup = Mash.new do |h,k|
    case k
    when Class
      h[k] = k
    when String, Symbol
      h[k] = Merb::Authentication::Strategies.full_const_get(k.to_s)
    end
  end
end

Public Instance Methods

abandon!() click to toggle source

“Logs Out” a user from the session. Also clears out all session data

# File lib/merb-auth-core/authentication.rb, line 113
def abandon!
  @user = nil
  session.clear
end
authenticate!(request, params, *rest) click to toggle source

The workhorse of the framework. The authentiate! method is where the work is done. authenticate! will try each strategy in order either passed in, or in the default_strategy_order.

If a strategy returns some kind of user object, this will be stored in the session, otherwise a Merb::Controller::Unauthenticated exception is raised

@params Merb::Request, [List,Of,Strategies, optional_options_hash]

Pass in a list of strategy objects to have this list take precedence over the normal defaults

Use an options hash to provide an error message to be passed into the exception.

@return user object of the verified user. An exception is raised if no user is found

# File lib/merb-auth-core/authentication.rb, line 69
def authenticate!(request, params, *rest)
  opts = rest.last.kind_of?(Hash) ? rest.pop : {}
  rest = rest.flatten

  strategies = if rest.empty?
    if request.session[:authentication_strategies]
      request.session[:authentication_strategies]
    else
      Merb::Authentication.default_strategy_order
    end
  else
    request.session[:authentication_strategies] ||= []
    request.session[:authentication_strategies] << rest
    request.session[:authentication_strategies].flatten!.uniq!
    request.session[:authentication_strategies]
  end

  msg = opts[:message] || error_message
  user = nil
  # This one should find the first one that matches.  It should not run antother
  strategies.detect do |s|
    s = Merb::Authentication.lookup_strategy[s] # Get the strategy from string or class
    unless s.abstract?
      strategy = s.new(request, params)
      user = strategy.run!
      if strategy.halted?
        self.headers, self.status, self.body = [strategy.headers, strategy.status, strategy.body]
        halt!
        return
      end
      user
    end
  end

  # Check after callbacks to make sure the user is still cool
  user = run_after_authentication_callbacks(user, request, params) if user

  # Finally, Raise an error if there is no user found, or set it in the session if there is.
  raise Merb::Controller::Unauthenticated, msg unless user
  session[:authentication_strategies] = nil # clear the session of Failed Strategies if login is successful
  self.user = user
end
authenticated?() click to toggle source

Returns true if there is an authenticated user attached to this session

@return <TrueClass|FalseClass>

# File lib/merb-auth-core/authentication.rb, line 32
def authenticated?
  !!session[:user]
end
error_message() click to toggle source

A simple error message mechanism to provide general information. For more specific information

This message is the default message passed to the Merb::Controller::Unauthenticated exception during authentication.

This is a very simple mechanism for error messages. For more detailed control see Authenticaiton#errors

@api overwritable

# File lib/merb-auth-core/authentication.rb, line 126
def error_message
  @error_message || "Could not log in"
end
errors() click to toggle source
# File lib/merb-auth-core/errors.rb, line 4
def errors
  @errors ||= Errors.new
end
fetch_user(session_contents = session[:user]) click to toggle source

Tells the framework how to reconstitute a user from the data stored by store_user.

You must overwrite this method for user in your projects. Slices and plugins may set this.

@api overwritable

# File lib/merb-auth-core/authentication.rb, line 144
def fetch_user(session_contents = session[:user])
  raise NotImplemented
end
halt!() click to toggle source
# File lib/merb-auth-core/responses.rb, line 31
def halt!
  @halt = true
end
halted?() click to toggle source
# File lib/merb-auth-core/responses.rb, line 22
def halted?
  !!@halt
end
headers() click to toggle source
# File lib/merb-auth-core/responses.rb, line 10
def headers
  @headers ||= {}
end
headers=(headers) click to toggle source
# File lib/merb-auth-core/responses.rb, line 26
def headers=(headers)
  raise ArgumentError, "Need to supply a hash to headers.  Got #{headers.class}" unless headers.kind_of?(Hash)
  @headers = headers
end
redirected?() click to toggle source
# File lib/merb-auth-core/responses.rb, line 6
def redirected?
  !!headers["Location"]
end
status() click to toggle source
# File lib/merb-auth-core/responses.rb, line 14
def status
  @status ||= 200
end
status=(sts) click to toggle source
# File lib/merb-auth-core/responses.rb, line 18
def status=(sts)
  @status = sts
end
store_user(user) click to toggle source

Tells the framework how to store your user object into the session so that it can be re-created on the next login. You must overwrite this method for use in your projects. Slices and plugins may set this.

@api overwritable

# File lib/merb-auth-core/authentication.rb, line 135
def store_user(user)
  raise NotImplemented
end
user() click to toggle source

This method will retrieve the user object stored in the session or nil if there is no user logged in.

@return <User class>|NilClass

# File lib/merb-auth-core/authentication.rb, line 40
def user
  return nil if !session[:user]
  @user ||= fetch_user(session[:user])
end
user=(user) click to toggle source

This method will store the user provided into the session and set the user as the currently logged in user @return <User Class>|NilClass

# File lib/merb-auth-core/authentication.rb, line 48
def user=(user)
  session[:user] = nil && return if user.nil?
  session[:user] = store_user(user)
  @user = session[:user] ? user : session[:user]
end

[Validate]

Generated with the Darkfish Rdoc Generator 2.