spec/rack-auth/authenticated_data_store_spec.rb @@ -1,5 +1,3 @@ -* Implement logout -* Implement authenticated data store * Allow a spec / test mode where a _spec_authenticate! method is called on a strategy instead if present * Implement back urls * Document the crap out of it \ No newline at end of file TODO.textile @@ -11,5 +11,6 @@ require 'rack-auth/authentication/strategies' module Rack module Auth + class NotAuthenticated < StandardError; end end end lib/rack-auth.rb @@ -3,29 +3,92 @@ module Rack class Manager class << self - + # A callback hook set to run every time after a user is set. + # This will happen the first time the user is either authenticated, accessed or manually set + # during a request. You can supply as many hooks as you like, and they will be run in order of decleration + # + # Parameters: + # <block> A block where you can set arbitrary logic to run every time a user is set + # Block Parameters: |user, auth, opts| + # user - The user object that is being set + # auth - The raw authentication proxy object. + # opts - any options passed into the set_user call includeing :scope + # + # Example: + # Rack::Auth::Manager.after_set_user do |user,auth,opts| + # scope = opts[:scope] + # if auth.session["#{scope}.last_access"].to_i > (Time.now - 5.minutes) + # auth.logout(scope) + # throw(:auth, :scope => scope, :reason => "Times Up") + # end + # auth.session["#{scope}.last_access"] = Time.now + # end + # + # :api: public def after_set_user(&block) raise BlockNotGiven unless block_given? _after_set_user << block end - def _after_set_user + # Provides access to the array of after_set_user blocks to run + # :api: private + def _after_set_user # :nodoc: @_after_set_user ||= [] end + # A callback hook set to run after the first authentiation of a session. + # This will only happenwhen the session is first authenticated + # + # Parameters: + # <block> A block to contain logic for the callback + # Block Parameters: |user, auth, opts| + # user - The user object that is being set + # auth - The raw authentication proxy object. + # opts - any options passed into the authenticate call includeing :scope + # + # Example: + # + # Rack::Auth::Manager.after_authentication do |user, auth, opts| + # throw(:auth, opts) unless user.active? + # end + # + # :api: public def after_authentication(&block) raise BlockNotGiven unless block_given? _after_authentication << block end + # Provides access to the array of after_authentication blocks + # :api: private def _after_authentication @_after_authentication ||= [] end + # A callback that runs just prior to the failur application being called. + # This callback occurs after PATH_INFO has been modified for the failure (default /unauthenticated) + # In this callback you can mutate the environment as required by the failure application + # If a Rails controller were used for the failure_app for example, you would need to set request[:params][:action] = :unauthenticated + # + # Parameters: + # <block> A block to contain logic for the callback + # Block Parameters: |user, auth, opts| + # env - The rack env hash + # opts - any options passed into the authenticate call includeing :scope + # + # Example: + # Rack::Auth::Manager.before_failure do |env, opts| + # params = Rack::Request.new(env).params + # params[:action] = :unauthenticated + # params[:authentication_failure] = opts + # end + # + # :api: public def before_failure(&block) _before_failure << block end + # Provides access to the callback array for before_failure + # :api: private def _before_failure @_before_failure ||= [] end lib/rack-auth/authentication/hooks.rb @@ -2,6 +2,34 @@ module Rack module Auth module Strategies class << self + + # Adds a strategy to the grab-bag of strategies available to use. + # A strategy is a place where you can put logic related to authentication. + # A strategy inherits from Rack::Auth::Strategies::Base. The _add_ method provides a clean way + # to declare your strategies. + # You _must_ declare an @authenticate!@ method. + # You _may_ provide a @valid?@ method. + # The valid method should return true or false depending on if the strategy is a valid one for the request. + # + # Parameters: + # <label: Symbol> The label is the name given to a strategy. Use the label to refer to the strategy when authenticating + # <strategy: Class|nil> The optional stragtegy argument if set _must_ be a class that inherits from Rack::Auth::Strategies::Base and _must_ + # implement an @authenticate!@ method + # <block> The block acts as a convinient way to declare your strategy. Inside is the class definition of a strategy. + # + # Examples: + # + # Block Declared Strategy: + # Rack::Auth::Strategies.add(:foo) do + # def authenticate! + # # authentication logic + # end + # end + # + # Class Declared Strategy: + # Rack::Auth::Strategies.add(:foo, MyStrategy) + # + # :api: public def add(label, strategy = nil, &blk) strategy = strategy.nil? ? Class.new(Rack::Auth::Strategies::Base, &blk) : strategy raise NoMethodError, "authenitate! is not declared in the #{label} strategy" if !strategy.instance_methods.include?("authenticate!") @@ -9,10 +37,14 @@ module Rack _strategies[label] = strategy end + # Provides access to declared strategies by label + # :api: public def [](label) _strategies[label] end + # Clears all declared middleware. + # :api: public def clear! @strategies = {} end lib/rack-auth/authentication/strategies.rb @@ -2,55 +2,103 @@ module Rack module Auth module Strategies class Base - attr_accessor :user, :message, :result, :custom_response - attr_reader :_status, :env + # :api: public + attr_accessor :user, :message + + #:api: private + attr_accessor :result, :custom_response + + # Setup for redirection + # :api: private + attr_reader :_status + + # Accessor for the rack env + # :api: public + attr_reader :env include ::Rack::Auth::Mixins::Common - def initialize(env, config = {}) + # :api: private + def initialize(env, config = {}) # :nodoc: @config = config @env, @_status, @headers = env, nil, {} @halted = false end - def _run! + # The method that is called from above. This method calls the underlying authetniate! method + # :api: private + def _run! # :nodoc: result = authenticate! self end + # Acts as a guarding method for the strategy. + # If #valid? responds false, the strategy will not be executed + # Overwrite with your own logic + # :api: overwritable def valid?; true; end + # Provides access to the headers hash for setting custom headers + # :api: public def headers(header = {}) @headers ||= {} @headers.merge! header @headers end + # Access to the errors object. + # :api: public def errors @env['rack-auth.errors'] end + # Cause the processing of the strategies to stop and cascade no further + # :api: public def halt! @halted = true end + # Checks to see if a strategy was halted + # :api: public def halted? !!@halted end + # A simple method to return from authenticate! if you want to ignore this strategy + # :api: public def pass; end + # Whenever you want to provide a user object as "authenticated" use the +success!+ method. + # This will halt the strategy, and set the user in the approprieate scope. + # It is the "login" method + # + # Parameters: + # user - The user object to login. This object can be anything you have setup to serialize in and out of the session + # + # :api: public def success!(user) halt! @user = user @result = :success end + # This causes the strategy to fail. It does not throw an :auth symbol to drop the request out to the failure application + # You must throw an :auth symbol somewhere in the application to enforce this + # :api: public def fail!(message = "Failed to Login") halt! @message = message @result = :failure end + # Causes the authentication to redirect. An :auth symbol must be thrown to actually execute this redirect + # + # Parameters: + # url <String> - The string representing the URL to be redirected to + # pararms <Hash> - Any parameters to encode into the URL + # opts <Hash> - Any options to recirect with. + # available options: permanent => (true || false) + # + # :api: public def redirect!(url, params = {}, opts = {}) halt! @_status = opts[:permanent] ? 301 : 302 @@ -64,6 +112,8 @@ module Rack headers["Location"] end + # Return a custom rack array. You must throw an :auth symbol to activate this + # :api: public def custom!(response) halt! @custom_response = response lib/rack-auth/authentication/strategy_base.rb @@ -1,6 +1,7 @@ module Rack module Auth - class Proxy + class Proxy + # :api: public def errors @env['rack-auth.errors'] ||= Errors.new end lib/rack-auth/errors.rb @@ -5,16 +5,22 @@ module Rack # The middleware injects an authentication object into # the rack environment hash class Manager - attr_accessor :config + attr_accessor :config, :failure_app + # initialize the middleware. + # Provide a :failure_app in the options to setup an application to run when there is a failure + # :api: public def initialize(app, config = {}) @app = app @failure_app = config[:failure_app] - raise "You must specify a :failure_app for authentication" unless @failure_app @config = config end - def call(env) + # :api: private + def call(env) # :nodoc: + # if this is downstream from another rack-auth instance, don't do anything. + return @app.call(env) unless env['rack-auth'].nil? + env['rack-auth'] = Proxy.new(env, @config) result = catch(:auth) do @app.call(env) @@ -30,39 +36,71 @@ module Rack end when Hash if (result[:action] ||= :unauthenticated) == :unauthenticated - case env['rack-auth'].result - when :failure - call_failure_app(env, result) - when :redirect - [env['rack-auth']._status, env['rack-auth'].headers, [env['rack-auth'].message || "You are being redirected to #{env['rack-auth'].headers['Location']}"]] - when :custom - env['rack-auth'].custom_response - when nil - call_failure_app(env, result) - end # case env['rack-auth'].result + process_unauthenticated(result,env) end # case result end end class << self - def _store_user(user, session, scope = :default) - session["rack-auth.user..#{scope}.key"] = user_session_key(user) + # Does the work of storing the user in the session + # :api: private + def _store_user(user, session, scope = :default) # :nodoc: + session["rack-auth.user.#{scope}.key"] = user_session_key.call(user) end - def _fetch_user(session, scope = :default) - user_from_session(session["rack-auth.user..#{scope}.key"]) + # Does the work of fetching the user from the session + # :api: private + def _fetch_user(session, scope = :default) # :nodoc: + user_from_session.call(session["rack-auth.user.#{scope}.key"]) end - def user_session_key(user) - user + # Prepares the user to serialize into the session. + # Any object that can be serialized into the session in some way can be used as a "user" object + # Generally however complex object should not be stored in the session. + # If possible store only a "key" of the user object that will allow you to reconstitute it. + # + # Example: + # Rack::Auth::Manager.user_session_key{ |user| user.id } + # + # :api: public + def user_session_key(&block) + @user_session_key = block if block_given? + @user_session_key ||= lambda{|user| user} end - def user_from_session(key) - key + # Reconstitues the user from the session. + # Use the results of user_session_key to reconstitue the user from the session on requests after the initial login + # + # Example: + # Rack::Auth::Manager.user_from_session{ |id| User.get(id) } + # + # :api: public + def user_from_session(&blk) + @user_from_session = blk if block_given? + @user_from_session ||= lambda{|key| key} end end - private + private + # When a request is unauthentiated, here's where the processing occurs. + # It looks at the result of the proxy to see if it's been executed and what action to take. + # :api: private + def process_unauthenticated(result, env) + case env['rack-auth'].result + when :failure + call_failure_app(env, result) + when :redirect + [env['rack-auth']._status, env['rack-auth'].headers, [env['rack-auth'].message || "You are being redirected to #{env['rack-auth'].headers['Location']}"]] + when :custom + env['rack-auth'].custom_response + when nil + call_failure_app(env, result) + end # case env['rack-auth'].result + end + + # Calls the failure app. + # The before_failure hooks are run on each failure + # :api: private def call_failure_app(env, opts = {}) env["PATH_INFO"] = "/#{opts[:action]}" lib/rack-auth/manager.rb @@ -3,14 +3,20 @@ module Rack module Mixins module Common + # Convinience method to access the session + # :api: public def session @env['rack.session'] end # session + # Convenience method to access the rack request + # :api: public def request @request ||= Rack::Request.new(@env) end # request - + + # Convenience method to access the rack request params + # :api: public def params request.params end # params lib/rack-auth/mixins/common.rb @@ -3,41 +3,81 @@ module Rack class UserNotSet < RuntimeError; end class Proxy + # :api: private attr_accessor :winning_strategy + + # An accessor to the rack env hash + # :api: public attr_reader :env extend ::Forwardable include ::Rack::Auth::Mixins::Common + # :api: private def_delegators :winning_strategy, :headers, :message, :_status, :custom_response - - def initialize(env, config = {}) + + def initialize(env, config = {}) # :nodoc: @env = env @config = config @strategies = @config.fetch(:default, []) @users = {} errors # setup the error object in the session end - + + # Check to see if there is an authenticated user for the given scope. + # When scope is not specified, :default is assumed. + # + # Parameters: + # args - a list of symbols (labels) that name the strategies to attempt + # opts - an options hash that contains the :scope of the user to check + # + # Example: + # env['rack-auth'].authenticated?(:password, :scope => :admin) + # :api: public def authenticated?(*args) scope = scope_from_args(args) _perform_authentication(*args) !user(scope).nil? end # authenticated? + # Run the authentiation strategies for the given strategies. + # If there is already a user logged in for a given scope, the strategies are not run + # This does not halt the flow of control and is a passive attempt to authenticate only + # When scope is not specified, :default is assumed. + # + # Parameters: + # args - a list of symbols (labels) that name the strategies to attempt + # opts - an options hash that contains the :scope of the user to check + # + # Example: + # env['auth'].authenticate(:password, :basic, :scope => :sudo) + # :api: public def authenticate(*args) _perform_authentication(*args) winning_strategy end + # The same as +authenticate+ except on failure it will throw an :auth symbol causing the request to be halted + # and rendered through the +failure_app+ + # + # Example + # env['rack-auth'].authenticate!(:password, :scope => :publisher) # throws if it cannot authenticate + # + # :api: public def authenticate!(*args) scope = scope_from_args(args) _perform_authentication(*args) throw(:auth, :action => :unauthenticated) if !user(scope) end + # Manually set the user into the session and auth proxy + # + # Parameters: + # user - An object that has been setup to serialize into and out of the session. + # opts - An options hash. Use the :scope option to set the scope of the user + # :api: public def set_user(user, opts = {}) - scope = opts.fetch(:scope, :default) + scope = (opts[:scope] ||= :default) Rack::Auth::Manager._store_user(user, session, scope) # Get the user into the session # Run the after hooks for setting the user @@ -45,41 +85,85 @@ module Rack @users[scope] = user # Store the user in the proxy user object end - + + # Provides acccess to the user object in a given scope for a request. + # will be nil if not logged in + # + # Example: + # # without scope (default user) + # env['rack-auth'].user + # + # # with scope + # env['rack-auth'].user(:admin) + # + # :api: public def user(scope = :default) @users[scope] end + # Provides a scoped data repository for authenticated users. + # Rack::Auth manages clearing out this data when a user logs out + # + # Example + # # default scope + # env['rack-auth'].data[:foo] = "bar" + # + # # :sudo scope + # env['rack-auth'].data(:sudo)[:foo] = "bar" + # + # :api: public def data(scope = :default) - session["rack-auth.user..#{scope}.data"] ||= {} + raise NotAuthenticated, "#{scope.inspect} user is not logged in" unless authenticated?(:scope => scope) + session["rack-auth.user.#{scope}.data"] ||= {} end + # Provides logout functionality. + # The logout also manages any authenticated data storage and clears it when a user logs out. + # + # Parameters: + # scopes - a list of scopes to logout + # + # Example: + # # Logout everyone and clear the session + # env['rack-auth'].logout + # + # # Logout the default user but leave the rest of the session alone + # env['rack-auth'].logout(:default) + # + # # Logout the :publisher and :admin user + # env['rack-auth'].logout(:publisher, :admin) + # + # :api: public def logout(*scopes) if scopes.empty? session.clear else scopes.each do |s| - session["rack-auth.user..#{s}.key"] = nil - session["rack-auth.user..#{s}.data"] = nil + session["rack-auth.user.#{s}.key"] = nil + session["rack-auth.user.#{s}.data"] = nil end end end # proxy methods through to the winning strategy - def result; winning_strategy.nil? ? nil : winning_strategy.result; end + # :api: private + def result # :nodoc: + winning_strategy.nil? ? nil : winning_strategy.result + end private + # :api: private def _perform_authentication(*args) scope = scope_from_args(args) opts = opts_from_args(args) # Look for an existing user in the session for this scope - if @users[scope] || @users[scope] = Rack::Auth::Manager._fetch_user(session, scope) + if @users[scope] || set_user(Rack::Auth::Manager._fetch_user(session, scope), :scope => scope) return @users[scope] end # If there was no user in the session. See if we can get one from the request strategies = args.empty? ? @strategies : args - raise "No Strategies Found" if strategies.empty? + raise "No Strategies Found" if strategies.empty? || !(strategies - Rack::Auth::Strategies._strategies.keys).empty? strategies.each do |s| strategy = Rack::Auth::Strategies[s].new(@env, @conf) next unless strategy.valid? @@ -88,6 +172,7 @@ module Rack break if result.halted? end + if winning_strategy.user set_user(winning_strategy.user, opts) @@ -98,10 +183,12 @@ module Rack winning_strategy end + # :api: private def scope_from_args(args) Hash === args.last ? args.last.fetch(:scope, :default) : :default end + # :api: private def opts_from_args(args) Hash === args.last ? args.pop : {} end lib/rack-auth/proxy.rb @@ -1,5 +1,5 @@ #!/usr/bin/env ruby -APP_ROOT = File.expand_path(File.join(File.dirname(__FILE__), '..')) +APP_ROOT = File.expand_path(File.join(File.dirname(__FILE__), '.')) begin require 'rubigen' script/destroy @@ -1,5 +1,5 @@ #!/usr/bin/env ruby -APP_ROOT = File.expand_path(File.join(File.dirname(__FILE__), '..')) +APP_ROOT = File.expand_path(File.join(File.dirname(__FILE__), '.')) begin require 'rubigen' script/generate @@ -12,14 +12,7 @@ describe Rack::Auth::Manager do it "should take a user and store it in the provided session" do session = {} Rack::Auth::Manager._store_user("The User", session, "some_scope") - session["rack-auth.user..some_scope.key"].should == "The User" - end - - it "should use the use the user_session_key method to encode the user into the session" do - session = {} - Rack::Auth::Manager.should_receive(:user_session_key).with("The User").and_return(:keyed_user_for_session) - Rack::Auth::Manager._store_user("The User", session, "some_scope") - session["rack-auth.user..some_scope.key"].should == :keyed_user_for_session + session["rack-auth.user.some_scope.key"].should == "The User" end end spec/rack-auth/manager_spec.rb @@ -97,11 +97,10 @@ describe Rack::Auth::Proxy do it "should look for an active user in the session with authenticate!" do app = lambda do |env| - env['rack.session']["rack-auth.user..default.key"] = "foo as a user" + env['rack.session']["rack-auth.user.default.key"] = "foo as a user" env['rack-auth'].authenticate!(:pass) valid_response end - Rack::Auth::Manager.should_receive(:user_from_session).with("foo as a user").and_return("foo as a user") env = env_with_params setup_rack(app).call(env) env['rack-auth'].user.should == "foo as a user" @@ -109,11 +108,10 @@ describe Rack::Auth::Proxy do it "should look for an active user in the session with authenticate?" do app = lambda do |env| - env['rack.session']['rack-auth.user..foo_scope.key'] = "a foo user" + env['rack.session']['rack-auth.user.foo_scope.key'] = "a foo user" env['rack-auth'].authenticated?(:pass, :scope => :foo_scope) valid_response end - Rack::Auth::Manager.should_receive(:user_from_session).with("a foo user").and_return("a foo user") env = env_with_params setup_rack(app).call(env) env['rack-auth'].user(:foo_scope).should == "a foo user" @@ -121,8 +119,8 @@ describe Rack::Auth::Proxy do it "should login 2 different users from the session" do app = lambda do |env| - env['rack.session']['rack-auth.user..foo.key'] = 'foo user' - env['rack.session']['rack-auth.user..bar.key'] = 'bar user' + env['rack.session']['rack-auth.user.foo.key'] = 'foo user' + env['rack.session']['rack-auth.user.bar.key'] = 'bar user' env['rack-auth'].authenticated?(:pass, :scope => :foo).should be_true env['rack-auth'].authenticated?(:pass, :scope => :bar).should be_true env['rack-auth'].authenticated?(:password).should be_false @@ -143,7 +141,7 @@ describe Rack::Auth::Proxy do app = lambda do |env| env['rack-auth'].should be_authenticated(:pass) env['rack-auth'].user.should == "Valid User" - env['rack.session']["rack-auth.user..default.key"].should == "Valid User" + env['rack.session']["rack-auth.user.default.key"].should == "Valid User" valid_response end setup_rack(app).call(env) @@ -154,7 +152,7 @@ describe Rack::Auth::Proxy do before(:each) do @env = env = env_with_params - @env['rack.session'] = {"rack-auth.user..default.key" => "default key", "rack-auth.user..foo.key" => "foo key", :foo => "bar"} + @env['rack.session'] = {"rack-auth.user.default.key" => "default key", "rack-auth.user.foo.key" => "foo key", :foo => "bar"} app = lambda do |e| e['rack-auth'].logout(env['rack-auth.spec.which_logout']) valid_response @@ -165,16 +163,16 @@ describe Rack::Auth::Proxy do it "should logout only the scoped foo user" do @env['rack-auth.spec.which_logout'] = :foo @app.call(@env) - @env['rack.session']['rack-auth.user..default.key'].should == "default key" - @env['rack.session']['rack-auth.user..foo.key'].should be_nil + @env['rack.session']['rack-auth.user.default.key'].should == "default key" + @env['rack.session']['rack-auth.user.foo.key'].should be_nil @env['rack.session'][:foo].should == "bar" end it "should logout only the scoped default user" do @env['rack-auth.spec.which_logout'] = :default @app.call(@env) - @env['rack.session']['rack-auth.user..default.key'].should be_nil - @env['rack.session']['rack-auth.user..foo.key'].should == "foo key" + @env['rack.session']['rack-auth.user.default.key'].should be_nil + @env['rack.session']['rack-auth.user.foo.key'].should == "foo key" @env['rack.session'][:foo].should == "bar" end spec/rack-auth/proxy_spec.rb spec/rack-auth/authenticated_data_store.rb a4cd579842d45ef60020f6734faf3f63536fcca3 Daniel Neighman has.sox@gmail.com http://github.com/hassox/warden/commit/5c96d723de7be0ec802feeb60b8670062fad2d19 5c96d723de7be0ec802feeb60b8670062fad2d19 2009-04-17T08:25:47-07:00 2009-04-17T08:25:47-07:00 Updates the documentation for an initial review 61cabc9bb181aa45127a9077acd286e67ed24875 Daniel Neighman has.sox@gmail.com