mbleigh-twitter-auth 0.0.2 → 0.1.1

data/README.markdown

@@ -1,52 +1,83 @@
 TwitterAuth
 ===========
 
-TwitterAuth is a plugin to provide a standard authentication stack using Twitter 
-as an SSO provider. This is obviously most useful and therefore targeted at
-apps that intend to heavily use the Twitter API.
+TwitterAuth aims to provide a complete authentication and API access solution for creating Twitter applications in Rails. It provides a generator and all of the necessary components to use Twitter as the sole authentication provider for an application using either Twitter's OAuth or HTTP Basic authentication strategies.
 
-**Note:** TwitterAuth uses Rails Engines functionality from Rails 2.3 and is
-therefore incompatible with earlier versions of Rails.
+Installation
+============
 
-Getting Started
----------------
+You can include TwitterAuth as a gem in your project like so:
 
-First, install either by gem or by plugin:
+    config.gem 'mbleigh-twitter-auth', :source => 'http://gems.github.com'
+
+Or you can install it as a traditional Rails plugin:
 
-    config.gem 'mbleigh-twitter-auth', :source => 'http://gems.github.com/'
-    
-OR
-    
     script/plugin install git://github.com/mbleigh/twitter-auth.git
 
-Next, to get started, you will need to generate the migration for the User 
-model that TwitterAuth uses. It's simple:
+Note that because TwitterAuth utilizes Rails Engines functionality introduced in Rails 2.3, it will not work with earlier versions of Rails.
+
+**NOTE:** TwitterAuth requires Rails version 2.3 or later because it makes extensive use of the new support for Rails Engines. Previous versions of Rails are not supported.
+
+Usage
+=====
+
+To utilize TwitterAuth in your application you will need to run the generator:
+
+    script/generate twitter_auth [--oauth (default) | --basic]
+
+This will generate a migration as well as set up the stubs needed to use the Rails Engines controllers and models set up by TwitterAuth. It will also create a User class that inherits from TwitterUser, abstracting away all of the Twitter authentication functionality and leaving you a blank slate to work with for your application. 
+
+Finally, it will create a configuration file in `config/twitter_auth.yml` in which you should input your OAuth consumer key and secret (if using the OAuth strategy) as well as a custom callback for development (the `oauth_callback` option is where Twitter will send the browser after authentication is complete. If you leave it blank Twitter will send it to the URL set up when you registered your application).
+
+Usage Basics
+------------
+
+If you need more information about how to use OAuth with Twitter, please visit Twitter's [OAuth FAQ](http://apiwiki.twitter.com/OAuth-FAQ).
+
+TwitterAuth borrows heavily from [Restful Authentication](http://github.com/technoweenie/restful-authentication) for its API because it's simple and well-known. Here are some of the familiar methods that are available:
+
+* `login_required`: a before filter that can be added to a controller to require that a user logs in before he/she can view the page.
+* `current_user`: returns the logged in user if one exists, otherwise returns `nil`.
+* `logged_in?`: true if logged in, false otherwise.
+* `redirect_back_or_default(url)`: redirects to the location where `store_location` was last called or the specified default URL.
+* `store_location`: store the current URL for returning to when a `redirect_back_or_default` is called.
+* `authorized?`: override this to add fine-grained access control for when `login_required` is already called.
+
+Accessing the Twitter API
+-------------------------
+
+Obviously if you're using Twitter as an authentication strategy you probably have interest in accessing Twitter API information as well. Because I wasn't really satisfied with either of the popular Twitter API Ruby libraries ([Twitter4R](http://twitter4r.rubyforge.org) and [Twitter](http://twitter.rubyforge.org)) and also because neither support OAuth (yet), I decided to go with a simple, dependency-free API implementation.
+
+The `User` class will have a `twitter` method that provides a generic dispatcher with HTTP verb commands available (`get`, `put`, `post`, and `delete`). These are automatically initialized to the `base_url` you specified in the `twitter_auth.yml` file, so you need only specify a path. Additionally, it will automatically append a .json extension and parse the JSON if you don't provide (it returns strings for XML because, well, I don't like XML and don't feel like parsing it).
+
+    # This code will work with the OAuth and Basic strategies alike.
+    user = User.find_by_login('mbleigh')
+
+    user.twitter.get('/account/verify_credentials')
+    # => {'screen_name' => 'mbleigh', 'name' => 'Michael Bleigh' ... }
+
+    user.twitter.post('/statuses/update.json', 'status' => 'This is my status.')
+    # => {"user"=>{"login" => "mbleigh" ... }, "text"=>"This is my status.", "id"=>1234567890 ... }
+
+This area of the code is still a little raw, but hopefully will evolve to be a little more user-friendly as TwitterAuth matures. In the meantime, it's a perfectly workable foundation library, and the fact that it works the same with OAuth and HTTP Basic makes it all the better!
+
+Customizing TwitterAuth
+-----------------------
 
-    script/generate migration twitter_auth_migration
-    
-If you look in the migration you will see that there are some information
-fields pre-populated (name, location, etc). These will automatically be
-retrieved from Twitter at each login and therefor kept both accessible
-and fresh for your usage.
+There are a number of hooks to extend the functionality of TwitterAuth. Here is a brief description of each of them.
 
-Believe it or not, that's it! You now have access to the standard suite
-of restful-auth controller helpers such as:
+### Controller Methods
 
-* login_required
-* current_user
-* logged_in?
+TwitterAuth provides some default controller methods that may be overridden in your `ApplicationController` to behave differently.
 
-And you also have the ability to login through the built-in SessionController.
-Just run the app and point your browser to '/login' to get started! You don't
-need to sign up because it will automatically create new users if the logging
-in user has never logged in before.
+* `authentication_failed(message)`: called when Twitter authorization has failed during the process. By default, simply redirects to the site root and sets the `flash[:error]`.
+* `authentication_succeeded(message=default)`: called when Twitter authorization has completed successfully. By default, simply redirects to the site root and sets the `flash[:notice]`.
+* `access_denied`: what happens when the `login_required` before filter fails. By default it stores the current location to return to and redirects to the login process.
 
-Caveats
--------
 
-This is **extremely alpha** code and has not been thoroughly spec'ed or even
-inspected. Use at your own risk as the functionality is likely to change
-drastically even in the near future.
+Copyright
+---------
 
+**TwitterAuth** is Copyright (c) 2009 [Michael Bleigh](http://www.mbleigh.com) and [Intridea, Inc.](http://www.intridea.com/), released under the MIT License.
 
-Copyright (c) 2009 [Michael Bleigh](http://www.mbleigh.com) and [Intridea, Inc.](http://www.intridea.com/), released under the MIT license
+TwitterAuth is not affiliated with Twitter, Inc.

data/VERSION.yml

@@ -1,4 +1,4 @@
 --- 
+:minor: 1
+:patch: 1
 :major: 0
-:minor: 0
-:patch: 2

data/generators/twitter_auth/USAGE

@@ -0,0 +1,12 @@
+TwitterAuth Generator
+=====================
+
+The TwitterAuth generator allows you to generate the components necessary to implement Twitter as a Single Sign-On provider for your site.
+
+To run it, you simply need to call it:
+
+script/generate twitter_auth
+
+This will generate the migration necessary for the users table as well as generate a User model that extends the appropriate TwitterAuth model template and a config/twitter.yml that allows you to set your OAuth consumer key and secret. 
+
+By default, TwitterAuth uses OAuth as its authentication strategy. If you wish to use HTTP Basic you can pass in the --basic option.

data/generators/twitter_auth/templates/migration.rb

@@ -1,33 +1,42 @@
 class TwitterAuthMigration < ActiveRecord::Migration
   def self.up
     create_table :users do |t|
-      t.string   :login
-      t.string   :crypted_password
-      t.string   :salt
-      
-      # Basic info pulled automatically from Twitter. 
-      # Feel free to remove any of these columns you don't want.
-      t.string  :name
-      t.string  :location
-      t.text    :description
-      t.string  :profile_image_url
-      t.string  :url
+      t.string :login
+<% if options[:oauth] -%>
+      t.string :access_token
+      t.string :access_secret
+<% elsif options[:basic] -%>
+      t.binary :crypted_password
+      t.string :salt
+<% end -%>
+
+      # This information is automatically kept
+      # in-sync at each login of the user. You
+      # may remove any/all of these columns.
+      t.string :name
+      t.string :location
+      t.string :description
+      t.string :profile_image_url
+      t.string :url
       t.boolean :protected
-      t.string  :profile_background_color
-      t.string  :profile_sidebar_fill_color
-      t.string  :profile_link_color
-      t.string  :profile_sidebar_border_color
-      t.string  :profile_text_color      
+      t.string :profile_background_color
+      t.string :profile_sidebar_fill_color
+      t.string :profile_link_color
+      t.string :profile_sidebar_border_color
+      t.string :profile_text_color
       t.integer :friends_count
       t.integer :statuses_count
-      t.integer :followers_count      
-      t.integer :favourites_count      
+      t.integer :followers_count
+      t.integer :favourites_count
+
+      # Probably don't need both, but they're here.
       t.integer :utc_offset
-      
+      t.string :time_zone
+
       t.timestamps
     end
   end
-  
+
   def self.down
     drop_table :users
   end

data/generators/twitter_auth/templates/twitter_auth.yml

@@ -0,0 +1,38 @@
+<% if options[:oauth] -%>
+development:
+  strategy: oauth
+  base_url: "https://twitter.com"
+  api_timeout: 10
+  oauth_consumer_key: devkey
+  oauth_consumer_secret: devsecret
+  oauth_callback: "http://localhost:3000/oauth_callback"
+test:
+  strategy: oauth
+  base_url: "https://twitter.com"
+  api_timeout: 10
+  oauth_consumer_key: testkey
+  oauth_consumer_secret: testsecret
+  oauth_callback: "http://localhost:3000/oauth_callback"
+production:
+  strategy: oauth
+  api_timeout: 10
+  base_url: "https://twitter.com"
+  oauth_consumer_key: prodkey
+  oauth_consumer_secret: prodsecret
+<% else -%>
+development:
+  strategy: basic
+  api_timeout: 10
+  base_url: "https://twitter.com"
+  # randomly generated key for encrypting Twitter passwords
+  encryption_key: "<%= key = ActiveSupport::SecureRandom.hex(12) %>"
+test:
+  strategy: basic
+  api_timeout: 10
+  base_url: "https://twitter.com"
+  encryption_key: "<%= key %>"
+production:
+  strategy: basic
+  api_timeout: 10
+  encryption_key: "<%= key %>"
+<% end %>

data/generators/twitter_auth/templates/user.rb

@@ -1,7 +1,5 @@
 class User < TwitterAuth::GenericUser
-  # Because Rails 2.3 does not allow for simple
-  # overriding of an Engine class from a samely
-  # named model in the app, this is instead
-  # inheriting from a GenericUser class that
-  # already utilizes the 'users' table.
-end
+  # Extend and define your user model as you see fit.
+  # All of the authentication logic is handled by the 
+  # parent TwitterAuth::GenericUser class.
+end

data/generators/twitter_auth/twitter_auth_generator.rb

@@ -1,10 +1,34 @@
-class TwitterAuthGenerator < Rails::Generator::Base 
-  def manifest 
-    record do |m| 
+class TwitterAuthGenerator < Rails::Generator::Base
+  default_options :oauth => true, :basic => false
+
+  def manifest
+    record do |m|
       m.class_collisions 'User'
-      
-      m.migration_template 'migration.rb', 'db/migrate', :migration_file_name => "twitter_auth_migration"
-      m.template 'user.rb', File.join('app/models', 'user.rb')
+
+      m.migration_template 'migration.rb', 'db/migrate', :migration_file_name => 'twitter_auth_migration'
+      m.template 'user.rb', File.join('app','models','user.rb')
+      m.template 'twitter_auth.yml', File.join('config','twitter_auth.yml')
     end
   end
-end
+
+  protected
+
+  def banner
+    "Usage: #{$0} twitter_auth"
+  end
+
+  def add_options!(opt)
+    opt.separator ''
+    opt.separator 'Options:'
+    
+    opt.on('-O', '--oauth', 'Use the OAuth authentication strategy to connect to Twitter. (default)') { |v| 
+      options[:oauth] = v
+      options[:basic] = !v
+    }
+
+    opt.on('-B', '--basic', 'Use the HTTP Basic authentication strategy to connect to Twitter.') { |v| 
+      options[:basic] = v
+      options[:oauth] = !v
+    }
+  end
+end

data/lib/twitter_auth.rb

@@ -1,5 +1,69 @@
 module TwitterAuth
   class Error < StandardError; end
+
+  def self.config(environment=RAILS_ENV)
+    @config ||= {}
+    @config[environment] ||= YAML.load(File.open(RAILS_ROOT + '/config/twitter_auth.yml').read)[environment]
+  end
+
+  def self.base_url
+    config['base_url'] || 'https://twitter.com'    
+  end
+
+  def self.api_timeout
+    config['api_timeout'] || 10
+  end
+
+  def self.encryption_key
+    raise TwitterAuth::Cryptify::Error, 'You must specify an encryption_key in config/twitter_auth.yml' if config['encryption_key'].blank?
+    config['encryption_key'] 
+  end
+
+  def self.oauth_callback?
+    config.key?('oauth_callback')
+  end
+
+  def self.oauth_callback
+    config['oauth_callback']
+  end
+
+  # The authentication strategy employed by this
+  # application. Set in +config/twitter.yml+ as
+  # strategy; valid options are oauth or basic.
+  def self.strategy
+    strat = config['strategy']
+    raise ArgumentError, 'Invalid TwitterAuth Strategy: Valid strategies are oauth and basic.' unless %w(oauth basic).include?(strat)
+    strat.to_sym
+  rescue Errno::ENOENT
+    :oauth
+  end
+
+  def self.oauth?
+    strategy == :oauth
+  end
+
+  def self.basic?
+    strategy == :basic
+  end
+  
+  # The OAuth consumer used by TwitterAuth for authentication. The consumer key and secret are set in your application's +config/twitter.yml+
+  def self.consumer
+    OAuth::Consumer.new(
+      config['oauth_consumer_key'],          
+      config['oauth_consumer_secret'],
+      :site => TwitterAuth.base_url
+    )
+  end
+
+  def self.net
+    uri = URI.parse(TwitterAuth.base_url)
+    net = Net::HTTP.new(uri.host, uri.port)
+    net.use_ssl = uri.scheme == 'https'
+    net.read_timeout = TwitterAuth.api_timeout
+    net
+  end
 end
 
-require 'twitter_auth/controller_extensions'
+require 'twitter_auth/controller_extensions'
+require 'twitter_auth/cryptify'
+require 'twitter_auth/dispatcher/oauth'

data/lib/twitter_auth/controller_extensions.rb

@@ -1,200 +1,64 @@
 module TwitterAuth
-  # The extensions to ActionController to enable our
-  # usage of Twitter-based authentication. This is
-  # taken directly from restful-authentication, so
-  # no credit is due here.
+  # These methods borrow HEAVILY from Rick Olsen's
+  # Restful Authentication. All cleverness props
+  # go to him, not me.
   module ControllerExtensions
-    # Returns true or false if the user is logged in.
-    # Preloads @current_user with the user model if they're logged in.
-    def logged_in?
-      !!current_user
+    def self.included(base)
+      base.send :helper_method, :current_user, :logged_in?, :authorized?
+    end
+
+    protected
+
+    def authentication_failed(message, destination='/')
+      flash[:error] = message
+      redirect_to destination
+    end
+
+    def authentication_succeeded(message = 'You have logged in successfully.', destination = '/')
+      flash[:notice] = message
+      redirect_to destination
     end
 
-    # Accesses the current user from the session.
-    # Future calls avoid the database because nil is not equal to false.
     def current_user
-      @current_user ||= (login_from_session || login_from_basic_auth) unless @current_user == false
+      @current_user ||= User.find_by_id(session[:user_id])
     end
 
-    # Store the given user id in the session.
     def current_user=(new_user)
-      session[:user_id] = new_user ? new_user.id : nil
-      @current_user = new_user || false
+      session[:user_id] = new_user.id
+      @current_user = new_user
     end
 
-    # Check if the user is authorized
-    #
-    # Override this method in your controllers if you want to restrict access
-    # to only a few actions or if you want to check if the user
-    # has the correct rights.
-    #
-    # Example:
-    #
-    #  # only allow nonbobs
-    #  def authorized?
-    #    current_user.login != "bob"
-    #  end
-    #
-    def authorized?(action=nil, resource=nil, *args)
-      logged_in?
+    def authorized?
+      !!current_user
     end
 
-    # Filter method to enforce a login requirement.
-    #
-    # To require logins for all actions, use this in your controllers:
-    #
-    #   before_filter :login_required
-    #
-    # To require logins for specific actions, use this in your controllers:
-    #
-    #   before_filter :login_required, :only => [ :edit, :update ]
-    #
-    # To skip this in a subclassed controller:
-    #
-    #   skip_before_filter :login_required
-    #
     def login_required
-      authorized? || access_denied
+      authorized? || access_denied 
     end
 
-    # Redirect as appropriate when an access request fails.
-    #
-    # The default action is to redirect to the login screen.
-    #
-    # Override this method in your controllers if you want to have special
-    # behavior in case the user is not authorized
-    # to access the requested action.  For example, a popup window might
-    # simply close itself.
     def access_denied
-      respond_to do |format|
-        format.html do
-          store_location
-          redirect_to new_session_path
-        end
-        # format.any doesn't work in rails version < http://dev.rubyonrails.org/changeset/8987
-        # you may want to change format.any to e.g. format.any(:js, :xml)
-        format.any(:xml, :json) do
-          request_http_basic_authentication 'Web Password'
-        end
-      end
+      store_location
+      redirect_to login_path
     end
 
-    # Store the URI of the current request in the session.
-    #
-    # We can return to this location by calling #redirect_back_or_default.
     def store_location
       session[:return_to] = request.request_uri
     end
 
-    # Redirect to the URI stored by the most recent store_location call or
-    # to the passed default.  Set an appropriately modified
-    #   after_filter :store_location, :only => [:index, :new, :show, :edit]
-    # for any controller you want to be bounce-backable.
-    def redirect_back_or_default(default=nil)
-      redirect_to(session[:return_to] || default || self.default_location)
+    def redirect_back_or_default(default)
+      redirect_to(session[:return_to] || default)
       session[:return_to] = nil
     end
-    
-    # Override this method with what you want your 'default default'
-    # to be (where it will redirect if there's no back and no explicit
-    # default).
-    def default_location
-      '/'
-    end
 
-    # Inclusion hook to make #current_user and #logged_in?
-    # available as ActionView helper methods.
-    def self.included(base)
-      base.send :helper_method, :current_user, :logged_in?, :authorized? if base.respond_to? :helper_method
-    end
-
-    #
-    # Login
-    #
-
-    # Called from #current_user.  First attempt to login by the user id stored in the session.
-    def login_from_session
-      self.current_user = User.find_by_id(session[:user_id]) if session[:user_id]
-    end
-
-    # Called from #current_user.  Now, attempt to login by basic authentication information.
-    def login_from_basic_auth
-      authenticate_with_http_basic do |login, password|
-        self.current_user = User.authenticate(login, password)
-      end
+    def logged_in?
+      !!current_user
     end
-    
-    #
-    # Logout
-    #
 
-    # Called from #current_user.  Finaly, attempt to login by an expiring token in the cookie.
-    # for the paranoid: we _should_ be storing user_token = hash(cookie_token, request IP)
-    # def login_from_cookie
-    #   user = cookies[:auth_token] && User.find_by_remember_token(cookies[:auth_token])
-    #   if user && user.remember_token?
-    #     self.current_user = user
-    #     handle_remember_cookie! false # freshen cookie token (keeping date)
-    #     self.current_user
-    #   end
-    # end
-
-    # This is ususally what you want; resetting the session willy-nilly wreaks
-    # havoc with forgery protection, and is only strictly necessary on login.
-    # However, **all session state variables should be unset here**.
     def logout_keeping_session!
-      # Kill server-side auth cookie
-      @current_user.forget_me if @current_user.is_a? User
-      @current_user = false     # not logged in, and don't do it for me
-      # kill_remember_cookie!     # Kill client-side auth cookie
-      session[:user_id] = nil   # keeps the session but kill our variable
-      # explicitly kill any other session variables you set
-    end
-
-    # The session should only be reset at the tail end of a form POST --
-    # otherwise the request forgery protection fails. It's only really necessary
-    # when you cross quarantine (logged-out to logged-in).
-    def logout_killing_session!
-      logout_keeping_session!
-      reset_session
+      @current_user = nil
+      session[:user_id] = nil
     end
-    
-    #
-    # Remember_me Tokens
-    #
-    # Cookies shouldn't be allowed to persist past their freshness date,
-    # and they should be changed at each login
-
-    # Cookies shouldn't be allowed to persist past their freshness date,
-    # and they should be changed at each login
-
-    # def valid_remember_cookie?
-    #   return nil unless @current_user
-    #   (@current_user.remember_token?) && 
-    #     (cookies[:auth_token] == @current_user.remember_token)
-    # end
-    
-    # Refresh the cookie auth token if it exists, create it otherwise
-    # def handle_remember_cookie! new_cookie_flag
-    #       return unless @current_user
-    #       case
-    #       when valid_remember_cookie? then @current_user.refresh_token # keeping same expiry date
-    #       when new_cookie_flag        then @current_user.remember_me 
-    #       else                             @current_user.forget_me
-    #       end
-    #       send_remember_cookie!
-    #     end
-    #   
-    #     def kill_remember_cookie!
-    #       cookies.delete :auth_token
-    #     end
-    #     
-    #     def send_remember_cookie!
-    #       cookies[:auth_token] = {
-    #         :value   => @current_user.remember_token,
-    #         :expires => @current_user.remember_token_expires_at }
-    #     end
   end
 end
 
-ActionController::Base.send :include, TwitterAuth::ControllerExtensions
+ActionController::Base.send(:include, TwitterAuth::ControllerExtensions)