Oauth and OpenId made Dead Simple.
Note: This is a refactoring and abstraction of AuthlogicConnect and it is not yet complete. The goal is to make it as low level as possible while still making it extremely simple to setup. It will abstract away all Oauth/OpenID complexities and be pluggable into any existing authentication framework.
Passport is your single interface to Oauth 1.0, Oauth 2.0, and OpenID.
Allow your users to login with Github, Facebook, Twitter, Google, LinkedIn, MySpace, Vimeo, and Yahoo Oauth providers (complete list), and all the OpenID providers. Simple, Clean, Fast.
sudo gem install passport
In a yaml file, say
config/passport.yml, write your keys and secrets for each service you would like to support. You have to manually go to the websites and register with the service provider.
adapter: active_record services: twitter: key: "my_key" secret: "my_secret" label: "Twitter" facebook: key: "my_key" secret: "my_secret" label: "Facebook" google: key: "my_key" secret: "my_secret" label: "Google" yahoo: key: "my_key" secret: "my_secret" label: "Yahoo" myspace: key: "my_key" secret: "my_secret" vimeo: key: "my_key" secret: "my_secret" linked_in: key: "my_key" secret: "my_secret"
Then in your application's initialization process:
config/passport.yml, you can specify an
adapter. The adapter tells Passport what kind of class we want the
AccessToken to be. The choices are:
By default, if an
adapter is not specified,
AccessToken will be a plain-old Ruby
Object. This means the framework does not have any large dependencies by default, which is useful if you're making a quick and dirty Sinatra app for example, and just want super-simple Oauth support without a database.
If you want to use this with ActiveRecord, setting up migrations is easy. Check out the Rails 3 AuthlogicConnect example for an authlogic example with user/session/access_token migrations. The migrations table we have been using so far look like this:
class CreateAccessTokens < ActiveRecord::Migration def self.up create_table :access_tokens do |t| t.integer :user_id t.string :type, :limit => 30 #=> service as a class name t.string :key # how we identify the user, in case they logout and log back in (e.g. email) t.string :token, :limit => 1024 t.string :secret t.boolean :active # whether or not it's associated with the account t.timestamps end add_index :access_tokens, :key, :unique end def self.down drop_table :access_tokens end end
MongoDB doesn't require any migrations so it's a simple setup. Just specify the mongo adapter in
There's a lot of functionality packed into Passport. All you need to know is that every service out there (Facebook, Twitter, Github, Foursquare, etc.) is treated as a
OauthToken (most of this is Oauth right now) has these key methods and attributes:
Token.authorize(callback_url, headers): get the authorize url from the oauth provider
Token.access(hash): get the access token from the oauth provider
key: the unique identifier for this user (optional, but definitely recommended)
token: oauth token from service
secret: oauth secret from service
get(url, options): authenticated api GET to the service; pass in headers, params, etc.
post(url, body, options): authenticated api POST to the service
This means that instead of having to write lots of code to setup even a simple oauth handler in your app, you can do this (sinatra example):
require 'rubygems' require 'passport' Passport.configure("tokens.yml") get "/" do "<a href='/authenticate?oauth_provider=facebook'>Login with Facebook</a>" end get "/authenticate" do Passport.authenticate end
This also means that if you wanted to do your own oauth setup, with or without any framework, you can easily do that. Say you want to programmatically setup Facebook Oauth with Mechanize (!):
def facebook_oauth authorize_hash = FacebookToken.authorize("http://some-real-or-fake-callback-url/") # mechanically submit forms access_hash = FacebookToken.access(authorize_hash) # boom, you have the access token (token, key, and secret), now go exploring end
You can accomplish everything oauth in Passport without using a server. All you need to do is call these two methods:
If you want to use a server (Sinatra, Rails, etc.), then Passport uses Rack. It keeps track of the state of the handshake using the
You can easily add your own services to Passport by creating an
OauthToken subclass. This is the
class FacebookToken < OauthToken version 2.0 key do |access_token| user = JSON.parse(access_token.get("/me")) user["id"] end settings "https://graph.facebook.com", :authorize_url => "https://graph.facebook.com/oauth/authorize", :scope => "email, offline_access" end
There are 3 executable class methods that define the API to the Oauth provider:
version: defaults to
1.0, can also be
blockor symbol that results in something that uniquely identifies the user (e.g
settings: the service domain, and a hash of the oauth urls and scopes