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 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 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/) and set the Callback URL to <your root url>/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"}}