sorcery 0.1.4 → 0.2.0

data/lib/sorcery/controller/submodules/http_basic_auth.rb

@@ -1,6 +1,9 @@
 module Sorcery
   module Controller
     module Submodules
+      # This submodule integrates HTTP Basic authentication into sorcery.
+      # You are provided with a before filter, require_login_from_http_basic, which requests the browser for authentication.
+      # Then the rest of the submodule takes care of logging the user in into the session, so that the next requests will keep him logged in.
       module HttpBasicAuth
         def self.included(base)
           base.send(:include, InstanceMethods)
@@ -31,17 +34,19 @@ module Sorcery
           def require_login_from_http_basic
             (request_http_basic_authentication(realm_name_by_controller) and (session[:http_authentication_used] = true) and return) if (request.authorization.nil? || session[:http_authentication_used].nil?)
             require_login
+            session[:http_authentication_used] = nil unless logged_in?
           end
           
           # given to main controller module as a login source callback
           def login_from_basic_auth
             authenticate_with_http_basic do |username, password|
-              @logged_in_user = (Config.user_class.authenticate(username, password) if session[:http_authentication_used]) || false
-              login_user(@logged_in_user) if @logged_in_user
-              @logged_in_user
+              @current_user = (Config.user_class.authenticate(username, password) if session[:http_authentication_used]) || false
+              login_user(@current_user) if @current_user
+              @current_user
             end
           end
           
+          # Sets the realm name by searching the controller name in the hash given at configuration time.
           def realm_name_by_controller
             current_controller = self.class
             while current_controller != ActionController::Base

data/lib/sorcery/controller/submodules/oauth.rb

@@ -0,0 +1,95 @@
+module Sorcery
+  module Controller
+    module Submodules
+      # This submodule helps you login users from OAuth providers such as Twitter.
+      # This is the controller part which handles the http requests and tokens passed between the app and the provider.
+      # For more configuration options see Sorcery::Model::Oauth.
+      module Oauth
+        def self.included(base)
+          base.send(:include, InstanceMethods)
+          Config.module_eval do
+            class << self
+              attr_reader :oauth_providers                           # oauth providers like twitter.
+              
+              attr_accessor :authentications_class
+                            
+              def merge_oauth_defaults!
+                @defaults.merge!(:@oauth_providers => [],
+                                 :@authentications_class => nil)
+              end
+              
+              def oauth_providers=(providers)
+                providers.each do |provider|
+                  include Providers.const_get(provider.to_s.split("_").map {|p| p.capitalize}.join(""))
+                end
+              end
+            end
+            merge_oauth_defaults!
+          end
+        end
+
+        module InstanceMethods
+          protected
+          
+          # sends user to authenticate at the provider's website.
+          # after authentication the user is redirected to the callback defined in the provider config
+          def auth_at_provider(provider)
+            @provider = Config.send(provider)
+            if @provider.respond_to?(:get_request_token)
+              args = {:request_token => @provider.get_request_token} 
+              session[:request_token] = args[:request_token]
+            end
+            redirect_to @provider.authorize_url(args)
+          end
+          
+          # tries to login the user from access token
+          def login_from_access_token(provider)
+            @provider = Config.send(provider)
+            args = {}
+            args.merge!({:oauth_verifier => params[:oauth_verifier], :request_token => session[:request_token]}) if @provider.respond_to?(:get_request_token)
+            args.merge!({:code => params[:code]}) if params[:code]
+            @access_token = @provider.get_access_token(args)
+            @user_hash = @provider.get_user_hash(@access_token)
+            if user = Config.user_class.load_from_provider(provider,@user_hash[:uid])
+              reset_session
+              login_user(user)
+              user
+            end
+          end
+          
+          def get_user_hash(provider)
+            @provider = Config.send(provider)
+            @provider.get_user_hash(@access_token)
+          end
+          
+          # this method automatically creates a new user from the data in the external user hash.
+          # The mappings from user hash fields to user db fields are set at controller config.
+          # If the hash field you would like to map is nested, use slashes. For example, Given a hash like:
+          #
+          #   "user" => {"name"=>"moishe"}
+          #
+          # You will set the mapping:
+          #
+          #   {:username => "user/name"}
+          #
+          # And this will cause 'moishe' to be set as the value of :username field.
+          def create_from_provider!(provider)
+            provider = provider.to_sym
+            @provider = Config.send(provider)
+            @user_hash = get_user_hash(provider)
+            config = Config.user_class.sorcery_config
+            attrs = {}
+            @provider.user_info_mapping.each do |k,v|
+              (varr = v.split("/")).size > 1 ? attrs.merge!(k => varr.inject(@user_hash[:user_info]) {|hsh,v| hsh[v] }) : attrs.merge!(k => @user_hash[:user_info][v])
+            end
+            Config.user_class.transaction do
+              @user = Config.user_class.create!(attrs)
+              Config.authentications_class.create!({config.authentications_user_id_attribute_name => @user.id, config.provider_attribute_name => provider, config.provider_uid_attribute_name => @user_hash[:uid]})
+            end
+            @user
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sorcery/controller/submodules/oauth/oauth1.rb

@@ -0,0 +1,25 @@
+module Sorcery
+  module Controller
+    module Submodules
+      module Oauth
+        module Oauth1
+          def oauth_version
+            "1.0"
+          end
+          
+          def get_request_token
+            ::OAuth::Consumer.new(@key, @secret, :site => @site).get_request_token(:oauth_callback => @callback_url)
+          end
+          
+          def authorize_url(args)
+            args[:request_token].authorize_url(:oauth_callback => @callback_url)
+          end
+          
+          def get_access_token(args)
+            args[:request_token].get_access_token(:oauth_verifier => args[:oauth_verifier])
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sorcery/controller/submodules/oauth/oauth2.rb

@@ -0,0 +1,23 @@
+module Sorcery
+  module Controller
+    module Submodules
+      module Oauth
+        module Oauth2
+          def oauth_version
+            "2.0"
+          end
+          
+          def authorize_url(args)
+            client = ::OAuth2::Client.new(@key, @secret, :site => @site)
+            client.web_server.authorize_url(:redirect_uri => @callback_url, :scope => @scope)
+          end
+          
+          def get_access_token(args)
+            client = ::OAuth2::Client.new(@key, @secret, :site => @site)
+            client.web_server.get_access_token(args[:code], :redirect_uri => @callback_url)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sorcery/controller/submodules/oauth/providers/facebook.rb

@@ -0,0 +1,64 @@
+module Sorcery
+  module Controller
+    module Submodules
+      module Oauth
+        module Providers
+          # This module adds support for OAuth with facebook.com.
+          # When included in the 'config.providers' option, it adds a new option, 'config.facebook'.
+          # Via this new option you can configure Facebook specific settings like your app's key and secret.
+          #
+          #   config.facebook.key = <key>
+          #   config.facebook.secret = <secret>
+          #   ...
+          #
+          module Facebook
+            def self.included(base)
+              base.module_eval do
+                class << self
+                  attr_reader :facebook                           # access to facebook_client.
+          
+                  def merge_facebook_defaults!
+                    @defaults.merge!(:@facebook => FacebookClient)
+                  end
+                end
+                merge_facebook_defaults!
+                update!
+              end
+            end
+          
+            module FacebookClient
+              class << self
+                attr_accessor :key,
+                              :secret,
+                              :callback_url,
+                              :site,
+                              :user_info_path,
+                              :scope,
+                              :user_info_mapping
+                            
+                include Oauth2
+            
+                def init
+                  @site           = "https://graph.facebook.com"
+                  @user_info_path = "/me"
+                  @scope          = "email,offline_access"
+                  @user_info_mapping = {}
+                end
+                
+                def get_user_hash(access_token)
+                  user_hash = {}
+                  response = access_token.get(@user_info_path)
+                  user_hash[:user_info] = JSON.parse(response)
+                  user_hash[:uid] = user_hash[:user_info]['id'].to_i
+                  user_hash
+                end
+              end
+              init
+            end
+            
+          end
+        end    
+      end
+    end
+  end
+end

data/lib/sorcery/controller/submodules/oauth/providers/twitter.rb

@@ -0,0 +1,61 @@
+module Sorcery
+  module Controller
+    module Submodules
+      module Oauth
+        module Providers
+          # This module adds support for OAuth with Twitter.com.
+          # When included in the 'config.providers' option, it adds a new option, 'config.twitter'.
+          # Via this new option you can configure Twitter specific settings like your app's key and secret.
+          #
+          #   config.twitter.key = <key>
+          #   config.twitter.secret = <secret>
+          #   ...
+          #
+          module Twitter
+            def self.included(base)
+              base.module_eval do
+                class << self
+                  attr_reader :twitter                           # access to twitter_client.
+
+                  def merge_twitter_defaults!
+                    @defaults.merge!(:@twitter => TwitterClient)
+                  end
+                end
+                merge_twitter_defaults!
+                update!
+              end
+            end
+
+            module TwitterClient
+              class << self
+                attr_accessor :key,
+                              :secret,
+                              :callback_url,
+                              :site,
+                              :user_info_path,
+                              :user_info_mapping
+                
+                include Oauth1
+                
+                def init
+                  @site           = "https://api.twitter.com"
+                  @user_info_path = "/1/account/verify_credentials.json"
+                  @user_info_mapping = {}
+                end
+                
+                def get_user_hash(access_token)
+                  user_hash = {}
+                  response = access_token.get(@user_info_path)
+                  user_hash[:user_info] = JSON.parse(response.body)
+                  user_hash[:uid] = user_hash[:user_info]['id']
+                  user_hash
+                end
+              end  
+              init
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sorcery/controller/submodules/remember_me.rb

@@ -1,6 +1,9 @@
 module Sorcery
   module Controller
     module Submodules
+      # The Remember Me submodule takes care of setting the user's cookie so that he will be automatically logged in to the site on every visit,
+      # until the cookie expires.
+      # See Sorcery::Model::Submodules::RememberMe for configuration options.
       module RememberMe
         def self.included(base)
           base.send(:include, InstanceMethods)
@@ -10,29 +13,35 @@ module Sorcery
         end
         
         module InstanceMethods
+          # This method sets the cookie and calls the user to save the token and the expiration to db.
           def remember_me!
-            logged_in_user.remember_me!
-            cookies[:remember_me_token] = { :value => logged_in_user.remember_me_token, :expires => logged_in_user.remember_me_token_expires_at }        
+            current_user.remember_me!
+            cookies[:remember_me_token] = { :value => current_user.remember_me_token, :expires => current_user.remember_me_token_expires_at }        
           end
 
+          # Clears the cookie and clears the token from the db.
           def forget_me!
-            logged_in_user.forget_me!
+            current_user.forget_me!
             cookies[:remember_me_token] = nil
           end
           
           protected
           
+          # calls remember_me! if a third credential was passed to the login method.
+          # Runs as a hook after login.
           def remember_me_if_asked_to(user, credentials)
             remember_me! if credentials.size == 3 && credentials[2]
           end
           
+          # Checks the cookie for a remember me token, tried to find a user with that token and logs the user in if found.
+          # Runs as a login source. See 'current_user' method for how it is used.
           def login_from_cookie
             user = cookies[:remember_me_token] && Config.user_class.find_by_remember_me_token(cookies[:remember_me_token])
             if user && user.remember_me_token?
               cookies[:remember_me_token] = { :value => user.remember_me_token, :expires => user.remember_me_token_expires_at }
-              @logged_in_user = user
+              @current_user = user
             else
-              @logged_in_user = false
+              @current_user = false
             end
           end
         end

data/lib/sorcery/controller/submodules/session_timeout.rb

@@ -1,6 +1,8 @@
 module Sorcery
   module Controller
     module Submodules
+      # This submodule helps you set a timeout to all user sessions.
+      # The timeout can be configured and also you can choose to reset it on every user action.
       module SessionTimeout
         def self.included(base)
           base.send(:include, InstanceMethods)
@@ -23,16 +25,19 @@ module Sorcery
         module InstanceMethods
           protected
           
+          # Registers last login to be used as the timeout starting point.
+          # Runs as a hook after a successful login.
           def register_login_time(user, credentials)
             session[:login_time] = session[:last_action_time] = Time.now.utc
           end
           
+          # Checks if session timeout was reached and expires the current session if so.
           # To be used as a before_filter, before require_login
           def validate_session
             session_to_use = Config.session_timeout_from_last_action ? session[:last_action_time] : session[:login_time]
             if session_to_use && (Time.now.utc - session_to_use > Config.session_timeout)
               reset_session
-              @logged_in_user = false
+              @current_user = false
             else
               session[:last_action_time] = Time.now.utc
             end

data/lib/sorcery/engine.rb

@@ -13,8 +13,15 @@ module Sorcery
     
     initializer "extend Controller with sorcery" do |app|
       ActionController::Base.send(:include, Sorcery::Controller)
-      ActionController::Base.helper_method :logged_in_user
+      ActionController::Base.helper_method :current_user
     end
-
+    
+    initializer "attempt to preload user model" do |app|
+      begin
+        require Rails.root + "app/models/user.rb"
+      rescue LoadError
+      end
+    end
+    
   end
 end

data/lib/sorcery/model.rb

@@ -55,7 +55,8 @@ module Sorcery
         _salt = user.send(@sorcery_config.salt_attribute_name) if user && !@sorcery_config.salt_attribute_name.nil? && !@sorcery_config.encryption_provider.nil?
         user if user && @sorcery_config.before_authenticate.all? {|c| user.send(c)} && credentials_match?(user.send(@sorcery_config.crypted_password_attribute_name),credentials[1],_salt)
       end
-
+      
+      # Calls the configured encryption provider to compare the supplied password with the encrypted one.
       def credentials_match?(crypted, *tokens)
         return crypted == tokens.join if @sorcery_config.encryption_provider.nil?
         @sorcery_config.encryption_provider.matches?(crypted, *tokens)
@@ -78,13 +79,19 @@ module Sorcery
         self.class.sorcery_config
       end
       
+      # identifies whether this user is regular, i.e. we hold his credentials in our db,
+      # or that he is external, and his credentials are saved elsewhere (twitter/facebook etc.).
+      def external?
+        send(sorcery_config.crypted_password_attribute_name).nil?
+      end
+      
       protected
       
       # creates new salt and saves it.
       # encrypts password with salt and save it.
       def encrypt_password
         config = sorcery_config
-        new_salt = self.send(:"#{config.salt_attribute_name}=", generate_random_code) if !config.salt_attribute_name.nil?
+        new_salt = self.send(:"#{config.salt_attribute_name}=", generate_random_token) if !config.salt_attribute_name.nil?
         self.send(:"#{config.crypted_password_attribute_name}=", self.class.encrypt(self.send(config.password_attribute_name),new_salt))
       end
 
@@ -104,7 +111,7 @@ module Sorcery
       end
       
       # Random code, used for salt and temporary tokens.
-      def generate_random_code
+      def generate_random_token
         return Digest::SHA1.hexdigest( Time.now.to_s.split(//).sort_by {rand}.join )
       end
     end