meal_ticket

MealTicket simplifies the process of authenticating with 3rd-party APIs by eliminating the stuff that's the same for everyone, letting you focus solely on the parts of authentication that matter to you.

== Overview

• You pick a service you want to authenticate against
• You decide what permissions you need
• You redirect your user to something like facebook_auth_url(root_url, "user_photos,publish_stream")
• MealTicket handles the gruesome details of the various psuedo-OAuth schemes
• MealTicket redirects the user back to a url of your choice along with their access token

== Currently Supported Services

• facebook
• flickr

== Getting Started

• Require the gem. In your gemfile:

  gem 'meal_ticket'

• Install the gem. In your console:

  bundle install (or maybe 'sudo bundle install')

• Install MealTicket as middleware to handle cross-domain communication. In Rails, you'd add something like this to your application.rb:

  module YourAppName class Application < Rails::Application config.middleware.use "MealTicket"

• Make meal_ticket URLs available to your views. In Rails, you'd add something like this to your application_helper.rb:

  require 'meal_ticket'

  module ApplicationHelper include MealTicketRoutes end

• Optionally, make meal_ticket URLs available to your controllers. In Rails, you'd add something like this to your application_controller.rb:

  require 'meal_ticket'

  class ApplicationController < ActionController::Base include MealTicketRoutes end

Now that you've finished installing MealTicket, look below for further instructions on how to connect with individual services.

= Service-Specific Instructions

For each service you want to integrate with, find it here and follow the steps to get your API keys.

In general, you'll need to do a couple things for each service:

• Go to their site, get your API keys, and make global constants for them.
• Create a callback method to receive the user's access token. Make sure you also map a route for this method.

== Facebook

• Log in to Facebook.
• Go to https://www.facebook.com/developers/apps.php and click the "Set Up New App" button.
• Fill out the forms to create a new app.
• Once you land on the "Edit" page, click the "Web Site" tab on the left.
• In the "Site Url" field, type the address of your site. For development, use something like +localhost:3000+. You may want to set up a separate app for production.

Create global constants that look something like this:

FACEBOOK_APP_ID = "158079864105359" # facebook calls this "App ID" FACEBOOK_SECRET = "98882d6d6cf0d7b69a5de5cc43abc10" # facebook calls this "App Secret" FACEBOOK_CALLBACK = "path/to/my/facebook/callback" # whatever URL you've created to grab the user data and do something useful

Now, redirect users to facebook_auth_url, passing the permissions you want to ask for. Like so:

For a full list of permissions, see https://developers.facebook.com/docs/authentication/permissions/

redirect_to facebook_auth_url(root_url, "user_photos,publish_stream")

After they authenticate, they'll be redirected to your +FACEBOOK_CALLBACK+ URL with query string params like:

?facebook[token]=q2jf89ojq.j32f|FQf9j23la&facebook[expires]=4829

• or, more legibly: - {:facebook => {:token => "q2jf89ojq.j32f|FQf9j23la", :expires => "4829"}}

Notes:

• Your facebook "API key" is never actually used.
• The expires value is the number of seconds for while this token is valid. If you request the offline_access permission, expires will be blank and the token is valid forever.

== Flickr

• Log in to Flickr.
• Go to http://www.flickr.com/services/apps/create/apply/ to register for API keys.
• Fill out the forms to create a new app.
• Once you're done, find the "edit authentication flow" page ({www.flickr.com/services/apps/YOUR_FLICKR_APP_ID/auth/}[www.flickr.com/services/apps]) and set the Callback URL to /meal_ticket/flickr_callback

Create global constants that look something like this:

FLICKR_TOKEN = "3637b1e30ae90503fedf9aaca8a4c370" FLICKR_SECRET = "3570d29a7a3c086b" FLICKR_CALLBACK = "path/to/my/flickr/callback" # whatever URL you've created to grab the user data and do something useful

Now, redirect users to flickr_auth_url, passing the permission level you want to ask for. Like so:

For a full list of permissions, see https://developers.facebook.com/docs/authentication/permissions/

redirect_to flickr_auth_url("write")

After they authenticate, they'll be redirected to your +FACEBOOK_CALLBACK+ method with params like:

?flickr[token]=q2jf89ojq.j32f|FQf9j23la&facebook[user_id]=

• or, more legibly: - {:flickr => {:token => "3215562516a046266-919fd54999d6e104", :user_id => "27934656@N00"}}

Notes:

• nothing to note

== Contributing to meal_ticket

• Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
• Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
• Fork the project
• Start a feature/bugfix branch
• Commit and push until you are happy with your contribution
• Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
• Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

== Copyright

Copyright (c) 2011 Chris Doyle. See LICENSE.txt for further details.