Rack::FacebookConnect

This is a Rack middleware to provide as simple as possible Facebook Connect functionality to Rack apps. It is built to be as simple and unobtrusive as possible and mimic the kinds of authentication flows more common with other SSO providers such as OpenID or OAuth.

Installation

Rack::FacebookConnect is available as a RubyGem:

gem install rack_facebook_connect

Application Setup

To use Rack::Facebook connect you will need to install it as a middleware in your Rack application. You will also need to set up a Facebook application for yourself with appropriate credentials in the Connect settings panel for your application.

Rails 2.3-2.X

To use Rack::FacebookConnect in your Rails 2.X application you need to add it to your gems and middlewares. In environment.rb do the following:

config.gem 'rack_facebook_connect'
config.middleware.use 'Rack::FacebookConnect', 'your_api_key', 'your_api_secret'

Rails 3

In Rails 3.0 you simply need to add the middleware to your Gemfile and the provided config.ru file before run YourApp::Application:

# in Gemfile
gem 'rack_facebook_connect'

# in config.ru
use Rack::FacebookConnect 'your_api_key', 'your_api_secret'

Sinatra

In Sinatra you need to require the Rack::FacebookConnect file somehow (either through bundler or just require 'rack/facebook_connect' if you have RubyGems accessible) and then simply declare a “use” statement in your code before your DSL routes:

use Rack::FacebookConnect 'your_api_key', 'your_api_secret'

get '/'
  #...
end

Usage

Once you’ve installed Rack::FacebookConnect as a middleware it will take care of many things for you. Rack::FacebookConnect handles:

1. Adding the required Javascript files to any HTML files rendered by your application to perform Facebook Connect actions.
2. Providing the cross-domain receiver file for Facebook's Javascript to bridge to your application.
3. A convenient method to perform an authentication 'callback' like with other systems.

Because of the Javascript Rack::FacebookConnect automatically injects into your site, you will be able to use XFBML, meaning that to provide a Facebook Connect login experience you simply need to add the following code to your application’s HTML:

<fb:login-button onlogin='rack_fbconnect()'></fb:login-button>

This will render a Facebook Connect button that will prompt the user first to log into Facebook and then to grant access to your application for certain permissions. Once that is done, your user will be redirected to the callback URL.

Callback

Rack::FacebookConnect doesn’t make assumptions about how you want to handle your user system. Instead, you simply need to provide some route on your application that responds to the path /auth/facebook/callback. This URL will be the destination of the redirect performed after authentication. On this URL Rack::FacebookConnect will modify the request parameters with an :auth key that provides information about the logged in user. So in Rails you could do something like this:

# in routes.rb
map.connect '/auth/facebook/callback', :controller => 'sessions', :action => 'fb_connect'

# in app/controllers/sessions_controller.rb
class SessionsController < ApplicationController
  def fb_connect
    @user = User.find_by_facebook_uid(params[:auth][:user_id]) || 
            User.create(:facebook_uid => params[:auth][:user_id],
                        :name => params[:auth][:info][:name],
                        :email => params[:auth][:info][:email])
    session[:user_id] = @user.id
    redirect_to root_path
  end
end

Or if you’re in Sinatra:

get '/auth/facebook/callback' do
  @user = User.find_by_facebook_uid(params[:auth][:user_id]) || 
          User.create(:facebook_uid => params[:auth][:user_id],
                      :name => params[:auth][:info][:name],
                      :email => params[:auth][:info][:email])
  session[:user_id] = @user.id
  redirect '/'
end

Gotchas

Facebook’s privacy policy requires that any user information other that the UID be stored for no longer than 24 hours. This means to comply with this policy you will need to re-fetch user information daily by storing the user’s session key and secret to make subsequent API calls.

Note on Patches/Pull Requests

Fork the project.
Make your feature addition or bug fix.
Add tests for it. This is important so I don’t break it in a future version unintentionally.
Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
Send me a pull request. Bonus points for topic branches.