fbauth 0.9.9.9 → 1.0.0.0

data/README.mdown

@@ -1,54 +1,239 @@
-FBAuth
-======
+# FBAuth #
 
-This gem provides authentication and basic Facebook functions for your Rails application.
+This gem provides authentication and basic Facebook functions for your
+Rails application.
 
-The Authentication Challenge
-----------------------------
+## The Authentication Challenge ##
 
-Facebook is an evolving platform, over the past couple years we've seen a lot of change in how it authenticates users of
-third-party applications.
+Facebook is an evolving platform, over the past couple years we've seen
+a lot of change in how it authenticates users of third-party
+applications.
 
-And as of this writing, authentication with the Javascript SDK remains broken due to the reliance on cross-domain
-cookies, which are simply not supported in mobile Safari, by default on Safari for Windows, and reportedly on the
-Android Webkit based browser.
+The documentation for Facebook is minimal, without historic reference or
+in-depth discussion of the different implementation scenarios that our
+applications may take.
 
-This plugin uses a few techniques to locate your "access token" and prefers to use the OAuth API to get what you need as
-a Facebook app to ensure your users have correctly added your app, authenticated in Facebook, and to communicate with
-the Graph API.
+For example, the preferred method of doing "Canvas" applications, those
+that live within the Facebook "wrapper" is now to use an iFrame. If you
+choose to utilize the Javascript Connect SDK and rely on its
+authentication mechanisms this will fail under any browsers that block
+cross-domain cookies - which is more prominent as time goes on due to
+the security risks involved in allowing cross-domain cookies.
+
+Therefore, as of this writing, applications using the prescribed iFrame
+style and using the JS SDK will fail on mobile Safari, Safari on
+Windows' default settings, and various mobile implementations of the
+Android browser.
+
+This plugin uses a few techniques to locate your "access token" and
+prefers to use the OAuth API to get what you need as a Facebook app to
+ensure your users have correctly added your app, authenticated in
+Facebook, and to communicate with the Graph and Query APIs.
 
 Here are the scenarios we currently handle:
 
-iFrame Apps
------------
+__iFrame Apps__
 
-- first page load as an iFrame app inside Facebook, where authentication params are sent in the URL used for your iFrame
-  - this is particularly required for mobile Safari and other browsers blocking cross-domain cookies by default
-  - handles the old session parameter, as well as the new signed_request parameter
+- first page load as an iFrame app inside Facebook, where authentication
+  params are sent in the URL used for your iFrame
+  - this is particularly required for mobile Safari and other browsers
+    blocking cross-domain cookies by default
+  - handles the old session parameter, as well as the new signed_request
+    parameter
 
 - loading from the cookie initialized by the JavaScript API
   - works great for browsers supporting cross-domain cookies by default
 
-- the access token you get is time-limited, if it has expired you need to be re-authenticated
+- the access token you get is time-limited, if it has expired you need
+  to be re-authenticated
+
+__External (Connect) Apps__
+
+- handling an OAuth exchange back & forth with Facebook to handle
+  authentication and capture URL parameters back for token
+
+## Integration with Your Rails App ##
+
+Add fbauth to your Gemfile
+
+    gem 'fbauth', '~> 1.0'
+
+Create `config/facebook.yml`
+
+    development:
+      app_id: 'xxxxxxxxxxxxx'
+      app_context: 'my-app-dev'
+      auth_path: '/login'
+      canvas_url: 'http://dev.myapp.com/facebook'
+      app_secret: 'xxxxxxxxxxxx'
+
+    test:
+      app_id: 'fake_id'
+      app_context: 'my-app'
+      auth_path: '/login'
+      canvas_url: 'http://myapp.com/facebook'
+      app_secret: 'fake_secret'
+
+    production:
+      app_id: 'xxxxxxxxxxxxx'
+      app_context: 'my-app'
+      auth_path: '/login'
+      canvas_url: 'http://myapp.com/facebook'
+      app_secret: 'xxxxxxxxxxxx'
+
+- `app_id` - this is your Facebook App ID
+- `app_context` - this is your Canvas Page path, ie.
+  `http://apps.facebook.com/my-app-dev`
+- `auth_path` - the path in your application to your login page (must be
+  a string, not a logical route name)
+- `canvas_url` - this is the Facebook Canvas URL, the base URL that gets
+  to the Facebook iFrame pages for your Canvas app
+- `app_secret` - the Facebook App Secret code for your application
+
+Note: _We are assuming that you will be registering **two** facebook
+applications, one that you will be using to actively develop your
+application and the other for production use for your users._
+
+Include the fbauth modules in your application controllers
+
+    include FacebookAuthFunctions
+    include FbauthHelper
+
+In the controllers you want restricted to authorized users, or in your
+`Application` controller, add the filters
+
+    before_filter :require_facebook_auth
+
+Create the controller and method that will live at your `auth_path`
+specified in your facebook.yml file.
+
+    class AuthController < ApplicationController
+
+      # Use this if you've included FacebookAuthFunctions in your
+      # Application controller...
+      # skip_before_filter :require_facebook_auth
+
+      def login
+      end
+    end
+
+And then create your login template (we use HAML, but you can use ERB if
+you want.
+
+    %div.fblogin
+      You are not logged in to Facebook, please click here:
+      %fb:login-button{:perms => 'publish_stream'} Log In to Facebook
+
+    %div.fbadd
+      Please add this Application - it's great!
+      %fb:login-button{:perms => 'publish_stream'} Add This Application
+
+    %div.fbready
+      Please wait...
 
-External (Connect) Apps
------------------------
+    = fbauth_login_javascript(:login => '.fblogin', :add => '.fbadd', :ready => '.fbready')
 
-- handling an OAuth exchange back & forth with Facebook to handle authentication and capture URL parameters back for
-  token
+The three areas noted above are exposed in the following scenarios:
 
-Things Remaining Unclear
-========================
+- `:login` - this element is exposed when the user has not logged into
+  Facebook, they may or may not have added your application but we don't
+  know that yet.
+- `:add` - this element is exposed when the user is logged in to
+  Facebook but has not added / authorized your application. Note we are
+  requesting certain permissions when the app is added:
+  `<fb:login-button perms="publish_stream"></fb:login-button>`
+- `:ready` - once the user has satisfied the pop-ups that appear when
+  logging in and/or adding the application, or if the user loads this
+  screen and is already fully authenticated, this element appears and
+  a redirect is done to your application root_path
 
-Documentation for the Facebook platform is a little fragmented, so we haven't (that we recall) come across the answers
-to these questions yet:
+## Using the Facebook APIs ##
 
-- what timezone is the OAuth token expiry value in? (we get it in Epoch, no TZ data, currently assuming San Francisco)
+### Graph API ###
+
+The Graph API gives you the ability to request a great deal of
+information about individual social relationships and perform basic
+updates to that graph (ie. posting news-feed events).
+
+Certain actions (posting changes, reading certain restricted attributes)
+are only available if you provide an access token and make an
+authenticated call.
+
+__Unauthenticated Call__
+
+    graph = FacebookGraph.new
+    graph.call('svetzal')
+
+This will retrieve publicly available information on the provided user's
+Facebook UID or handle in a Ruby hash structure.
+
+    {"name"=>"Steven Vetzal", "gender"=>"male", "id"=>"849395216", "last_name"=>"Vetzal",
+     "locale"=>"en_US", "link"=>"http://www.facebook.com/svetzal", "first_name"=>"Steven"}
+
+__Authenticated Call__
+
+    graph = FacebookGraph.new(fbauth.access_token)
+    graph.call('svetzal', { :scope => "birthday" })
+
+This will make a similar call but as an authenticated caller we can
+request a restricted scope, in this case information about the user's
+birthday (if our app has requested the birthday permission from the
+user).
+
+### Query API (FQL) ###
+
+__Unauthenticated Call__
+
+    query = FacebookQuery.new
+    query.fql('SELECT name, first_name, last_name FROM user WHERE uid in ("849395216","58001611","1018515154")')
+
+FQL is handy for performing multiple lookups at once, and can save you a
+lot of latency.
+
+    [
+      {"name"=>"Steven Vetzal", "last_name"=>"Vetzal", "first_name"=>"Steven"},
+      {"name"=>"Nate Smith", "last_name"=>"Smith", "first_name"=>"Nate"},
+      {"name"=>"Craig Savolainen", "last_name"=>"Savolainen", "first_name"=>"Craig"}
+    ]
+
+__Authenticated Call__
+
+    query = FacebookQuery.new(fbauth.access_token)
+
+__Manually Building an Access Token__
+
+If you scan your logs, you'll see the `signed_request` OAuth GET
+parameter being sent to your application. You can manually build
+yourself an authentication token from this using the following code.
+
+    data = FacebookDecoder.decode('{"signed_request"=>"oXWWpLi2tX7QW3cjX...(removed)"}')
+    fbauth = FacebookAuth.create(data)
+    fbauth.validate
+
+The `.validate` step is optional, but pre-warns you if the token you are
+about to use is good. If it is not, you can find out why by looking at
+`fbauth.validation_error`.
+
+# Things Remaining Unclear #
+
+Documentation for the Facebook platform is a little fragmented, so we
+haven't (that we recall) come across the answers to these questions yet:
+
+- what timezone is the OAuth token expiry value in? (we get it in Epoch,
+  no TZ data, currently assuming San Francisco)
 - what happens when time approaches the OAuth token expiry?
     - do we get a new one?
     - are we expected to stop functioning and redirect to a FB login?
 
-Change Log
-==========
+# Change Log #
+
+v1.0.0.0
+
+- Changed call semantics for FacebookGraph and FacebookQuery,
+  use objects instead of class methods
+- Preparing for public release
 
-v0.9.9.6 - Raising info-rich exceptions when errors returned from Facebook on graph calls
+v0.9.9.6
+ 
+- Raising info-rich exceptions when errors returned from
+  Facebook on graph calls

data/app/controllers/facebook_auth_functions.rb

@@ -5,9 +5,6 @@ module FacebookAuthFunctions
   end
 
   def require_facebook_auth
-    # Prep IE so it will take our cookies in a Facebook iFrame
-    response.headers['P3P'] = 'CP="IDC DSP COR ADM DEVi TAIi PSA PSD IVAi IVDi CONi HIS OUR IND CNT"'
-
     setup_facebook_auth
     if @facebook_auth.nil?
       redirect_to build_auth_url
@@ -21,6 +18,9 @@ private
   end
 
   def facebook_auth
+    # Prep IE so it will take our cookies in a Facebook iFrame
+    response.headers['P3P'] = 'CP="IDC DSP COR ADM DEVi TAIi PSA PSD IVAi IVDi CONi HIS OUR IND CNT"'
+
     # If we have valid auth in session, use it
     data = parse_session
     auth = validate_and_save(data) unless data.nil?
@@ -70,6 +70,7 @@ private
       parms = JSON.parse(params[:session])
       logger.warn("Parsed facebook params from session parameter (deprecated)")
     elsif params[:signed_request].present?
+      logger.warn("Found signed_request param")
       begin
         parms = FacebookDecoder.decode(params[:signed_request])
         logger.warn("Parsed facebook params from signed_request parameter")

data/lib/facebook_auth.rb

@@ -36,7 +36,7 @@ class FacebookAuth
     msgs = []
     unless self.uid.nil? || self.access_token.nil?
       begin
-        self.user_data = FacebookGraph.call(self.uid, self.access_token)
+        self.user_data = FacebookGraph.new(self.access_token).call(self.uid)
       rescue => e
         msgs << "Error calling FacebookGraph - #{e}"
       end

data/lib/facebook_graph.rb

@@ -2,56 +2,25 @@ require 'net/http'
 require 'uri'
 
 class FacebookGraph
+  include FacebookHttp
 
-  def self.call(path, access_token = nil, options = {})
-    params = []
-    options.keys.each do |k|
-      params << "#{k}=#{options[k]}" unless options[k].nil?
-    end
-    token = access_token ? CGI::escape(access_token) : nil
-    url = "https://graph.facebook.com/#{path}&access_token=#{token}"
-    url = "#{url}?#{params.join('&')}" unless params.empty?
-    uri = URI.parse(url)
-    http = Net::HTTP.new uri.host, uri.port
-    begin
-      http.use_ssl = (uri.scheme == "https")
-      req = Net::HTTP::Get.new(uri.path)
-      response = http.request(req)
-      raise "Facebook error response #{response.code} - #{response.body}" unless response.code == '200'
-      begin
-        json = JSON.parse(response.body)
-      rescue => e
-        raise "Error parsing Facebook response: #{response.body}"
-      end
-    ensure
-      http.finish if http.started?
-    end
-    json
+  FB_GRAPH_URL = "https://graph.facebook.com"
+
+  def initialize(access_token = nil, options = {})
+    @options = options.merge({ :access_token => access_token })
+  end
+
+  # Generic Graph call to lookup data for any path
+  def call(path, options = {})
+    get "#{FB_GRAPH_URL}/#{path}", merged_options(options)
   end
 
-  # Available options:
-  #   message, picture, link, name, caption, description
-  def self.publish_to_member_feed(uid, access_token, options)
-    token = access_token ? CGI::escape(access_token) : nil
-    if %w{staging production}.include? ENV['RAILS_ENV']
-      url = "https://graph.facebook.com/#{uid}/feed&access_token=#{token}"
-      uri = URI.parse(url)
-      http = Net::HTTP.new uri.host, uri.port
-      begin
-        http.use_ssl = (uri.scheme == "https")
-        req = Net::HTTP::Post.new(uri.path)
-        req.set_form_data(options)
-        response = http.request(req)
-        raise "Facebook error response #{response.code} - #{response.body}" unless response.code == '200'
-        begin
-          json = JSON.parse(response.body)
-        rescue => e
-          raise "Error parsing Facebook response: #{response.body}"
-        end
-      ensure
-        http.finish if http.started?
-      end
-      json
+  # Post item to member's wall
+  #   Available options: message, picture, link, name, caption, description
+  def publish_to_member_feed(uid, options)
+    raise "access_token required" unless has_access_token?(options)
+    if %w{staging production}.include? Rails.env
+      post "#{FB_GRAPH_URL}/#{uid}/feed", merged_options(options)
     end
   end
 end

data/lib/facebook_http.rb

@@ -0,0 +1,87 @@
+require 'benchmark'
+require 'net/http'
+require 'uri'
+require 'cgi'
+
+module FacebookHttp
+
+  def build_get_url(url, params = {})
+    q = build_query_string(params)
+    if q
+      url + q
+    else
+      url
+    end
+  end
+
+  def get(url, params = {})
+    json = nil
+    uri = URI.parse(build_get_url(url, params))
+    bench = Benchmark.measure do
+      http = Net::HTTP.new uri.host, uri.port
+      begin
+        http.use_ssl = (uri.scheme == "https")
+        req = Net::HTTP::Get.new(uri.request_uri)
+        response = http.request(req)
+        raise "Facebook error response #{response.code} - #{response.body}" unless response.code == '200'
+        begin
+          json = JSON.parse(response.body)
+        rescue => e
+          raise "Error parsing facebook response: #{response.body}"
+        end
+      ensure
+        http.finish if http.started?
+      end
+    end
+    logger.warn("Facebook GET call to #{uri.to_s} completed in #{bench.total} seconds")
+    json
+  end
+
+  def post(url, params = {})
+    json = nil
+    uri = URI.parse(url)
+    bench = Benchmark.measure do
+      http = Net::HTTP.new uri.host, uri.port
+      begin
+        http.use_ssl = (uri.scheme == "https")
+        req = Net::HTTP::Post.new(uri.path)
+        req.set_form_data(params)
+        response = http.request(req)
+        raise "Facebook error response #{response.code} - #{response.body}" unless response.code == '200'
+        begin
+          json = JSON.parse(response.body)
+        rescue => e
+          raise "Error parsing Facebook response: #{response.body}"
+        end
+      ensure
+        http.finish if http.started?
+      end
+    end
+    logger.warn("Facebook POST call to #{uri.to_s} completed in #{bench.total} seconds")
+    json
+  end
+
+  def build_query_string options={}
+    params = []
+    str_keys = options.keys.collect{ |k| k.to_s }
+    str_keys.sort.each do |str_key|
+      key = str_key.to_sym
+      value = options[key]
+      params << "#{key.to_s}=#{URI.escape(value.to_s)}" unless value.nil?
+    end
+    "?#{params.join('&')}" unless params.empty?
+  end
+
+  def merged_options(options = {})
+    options.merge!(@options) if @options
+    options
+  end
+
+  def has_access_token?(options = {})
+    merged_options.has_key? :access_token
+  end
+
+  def logger
+    Rails.logger
+  end
+end

data/lib/facebook_query.rb

@@ -0,0 +1,16 @@
+require 'uri'
+
+class FacebookQuery
+  include FacebookHttp
+
+  FB_API_URL = "https://api.facebook.com/method/fql.query"
+
+  def initialize(access_token = nil, options = {})
+    @options = options.merge({ :access_token => access_token })
+    @options.merge!({ :format => "JSON" }) unless @options.has_key?(:format)
+  end
+
+  def fql(query, options = {})
+    get FB_API_URL, merged_options(options.merge({ :query => query }))
+  end
+end

data/lib/fbauth.rb

@@ -12,4 +12,6 @@ end
 require 'facebook_decoder.rb'
 require 'facebook_auth.rb'
 require 'facebook_config.rb'
+require 'facebook_http.rb'
 require 'facebook_graph.rb'
+require 'facebook_query.rb'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification 
 name: fbauth
 version: !ruby/object:Gem::Version 
-  hash: 49
+  hash: 95
   prerelease: false
   segments: 
+  - 1
   - 0
-  - 9
-  - 9
-  - 9
-  version: 0.9.9.9
+  - 0
+  - 0
+  version: 1.0.0.0
 platform: ruby
 authors: 
 - Three Wise Men Inc.
@@ -16,7 +16,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-02-28 00:00:00 -05:00
+date: 2011-03-03 00:00:00 -05:00
 default_executable: 
 dependencies: []
 
@@ -33,6 +33,8 @@ files:
 - lib/facebook_config.rb
 - lib/facebook_decoder.rb
 - lib/facebook_graph.rb
+- lib/facebook_http.rb
+- lib/facebook_query.rb
 - lib/fbauth.rb
 - app/controllers/facebook_auth_functions.rb
 - app/helpers/fbauth_helper.rb