houston-oauth-plugin 0.5.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 7a59ec2d81c1b9a493f85885c0b33615ce0e46f7
+  data.tar.gz: e6ed0f0f02d9db8b66c51bab808bb000f7744af3
+SHA512:
+  metadata.gz: c5061e6bd05ae4e54964c10d34b999e77a365bccdec6e36f20cb8b8bbe272374b1519f34b3fc7bfe5c1459bdbfa9d842a3b5a1fd1a9b1313e1704e383cd3a920
+  data.tar.gz: 0a3b902aad77dc5959074926843b42ca9f6c21264761ee7e82b31b7bcabdfdcfecd9f726a33aa501a2404b050956935cf56d9328994ab5c934386c100b0735f2

data/.gitignore

@@ -0,0 +1,12 @@
+doc
+pkg
+*.log
+.DS_Store
+.svn
+*.gem
+.bundle
+.swp
+.idea
+.rvmrc
+
+Gemfile.lock

data/CHANGELOG

@@ -0,0 +1,187 @@
+0.5.1
+  - Support slim templates for consumer [pelle]
+  - Add via argument to match routes to support 4.0 [pelle]
+0.5.0
+  - Make compatible with Rails 4 [tomhughes]
+  - Added support for RefreshTokens [RubenHoms]
+  - allow? should return false when token is not found [thetizzo]
+  - add license to gemspec [jordimassaguerpla]
+  - update documentation for Rails 2.x [yann]
+0.4.1
+  - Security fix for OAuth1 provider. Please upgrade if you're using any 0.4 version. Thanks to [tomhughes]
+  - Limit index size in ConsumerToken migration to deal with very large tokens [devainandor]
+  - Accept ancient OAuth2 Token token=asfavasd like tokens. Just for complete compatibility. [pelle]
+  - oauth2 errors should return http 400 [pelle]
+0.4.0
+  - fix migrations to use expires_at instead of valid_to [pelle]
+  - add force parameter for forcing token refresh [afeld]
+  - make it work in rails 2x [Kimtaro]
+  - Use 0.5+ OAuth2 gem [kookster]
+  - prevent addition of ? marks to callback url when not needed [kookster]
+  - make .credentials accessible to TwitterToken [afeld]
+0.4.0-rc2
+  - Better OAuth2 support.
+  - Refactored authorizer into a Authorizer object which is now better tested
+0.4.0-rc1
+  PLEASE help test this so we can mark it as final
+  - Update to OAuth2 draft 22 which is likely the final release. [pelle] ACTION REQUIRED BY YOU, see README.
+  - Update forms to work with rails 3.1 [morgz]
+  - Allow nil callbacks for oob in OAuth 1.0a [Shaliko Usubov]
+  - OAuthFilter:oauth2_token to rejects headers that explicitly state oauth_version="1.0" [KentonWhite]
+0.4.0-pre7
+  - OAuth 1 requests using query or form encoded parameters where being interpreted as OAuth2 [pelleb]
+  - OAuth 2 requests were not checking for invalidated tokens. Please upgrade for this if you offer OAuth 2 [rymai]
+  - Handle case where credentials[:options] in consumer plugin was nil [marnen]
+  - Better facebook example [marnen]
+0.4.0-pre6
+  - fixes issue with erb generator in rails 3 [pelleb]
+  - various cleanups in generators [akonan]
+0.4.0-pre5
+  - protect oauth consumer relay with :expose configuration option. It's off by default. [pelle]
+  - Reenable twitter client. It is now configurable for twitter tokens. :client=>:twitter_gem or :oauth_gem [pelle]
+  - fix issues with new consumer tokens [afeld]
+  - More forgiving about oob callback values[chrisrhoden]
+  - Update Twitter consumer to use latest Twitter Gem [afeld]
+  - removed portable_contacts client from Google Token [p8]
+  - Fixes various mongoid issues [3en]
+  - Adds oauth2 consumer support
+  - Fixes oauth2 provider. parameter should be redirect_uri not redirect_url [Kimtaro]
+  - Most core OAuth functionality is being put into OAuthFilter. This means Rails 2.3 and above only
+  0.4.0-pre4
+  - Fixed bug when creating a new user from a new consumer token
+  - Fix typo in consumer token [krasio]
+  - Fix issue with mongoid not supporting find_by_x style queries. [3en]
+  0.4.0-pre3
+  - Experimental rack filter for OAuth 1.0a:
+    see lib/oauth/rack/oauth_filter.rb for details
+  0.4.0-pre2
+  - mongoid defaults to being embedded
+  - new :auto_login option in oauth_config.rb which lets you use eg. twitter as a primary authentication method
+  0.4.0-pre1
+	- mongoid support in rails 3 [Alexander Semyonov]
+	- OAUTH 2.0 authorization_code and password grant types
+	- Supports OAuth 2.0 draft 10 (Note this is incompatible with previous drafts)
+	- Refactored application_controller_methods to be a lot less intrusive
+	- Increased default token and key size in anticipation of OAuth2 support
+	- Rails 3 support
+	- Rails 3 generators [Paul Rosiana] and patches by [Alexander Flatter]
+	- Modularized Rails 3 generators [Alexander Semyonov]
+	- Callback urls now allow query parameters. Multiple patches but I used [Unk]'s.
+10/08/2009
+  0.3.14
+  - Fixed the class generation when you have a custom token defined. [Brian Morearty]
+10/05/2009
+  0.3.13
+  - Got rid of yahoo token. To support it correctly requires way too much work. Let them suffer the consequences of their decissions.
+  - GoogleToken now uses portablecontacts gem
+9/30/2009
+  0.3.12
+  - Added a simple PortableContacts adapter for GoogleToken
+  - Added a SimpleClient wrapper to provide really simple wrapper for OAuth based json web services
+  - Increased token size in consumer_tokens table because of Yahoo's oversized tokens
+  - Added support for Yahoo
+  - Added support for Google (Boon Low)
+9/26/2009
+  0.3.11
+  - Moved twitter tokens dependency back to regular twitter gem
+7/29/2009
+  0.3.10
+  - Closed blocks in erb template (jcrosby) while pelle is hiding under his desk
+  - Handled error case on authorize with non existent token
+  - Fixed Agree2 token
+  - Security Fix: Only skip verify_authenticity_token for specific oauth token requests in provider controller
+7/25/2009
+  0.3.9
+  - Added an Index to oauth consumers controller. Rerun generator to create index template
+  - Added invalidate action to provider, which allows a token to invalidate itself /oauth/invalidate
+  - Added capabilities action to provider. Lets you expand to allow auto discovery of permissions and services that token provides.
+  - Can override how authorize form indicates an authorization. To get around ugly checkbox
+
+    def user_authorizes_token?
+      params[:commit] == 'Authorize'
+    end
+
+7/23/2009
+  0.3.8
+  - Fixed Gem Plugins Loading
+7/21/2009
+  0.3.7
+  - A blushing Pelle adds a missing file
+  0.3.6
+  - Twitter, Agree2 and FireEagle tokens are working in consumer.
+  0.3.5
+  - made it a gem
+  - more thorough tests of OAuth 1.0 consumer
+  - Add support for a OAUTH_10_SUPPORT constant to switch on support for OAuth 1.0 in provider
+7/19/2009
+  - Added support for OAuth 1.0 consumers (nov)
+7/17/2009
+  - Added back support for OAuth 1.0 for providers (nov)
+7/14/2009
+  - Added OAuth Consumer generator
+  - Moved oauth controller code to a module to make it easier to upgrade in the future
+7/11/2009
+  - Added support for OAuth version 1.0a
+  - Added haml support
+  - Improved OAuth Client Controller gui (alec-c4)
+2/11/2009
+- Fixed escaping error and file path error in the generator simultaneously reported and fixed by Ivan Valdes and Mike Demers thanks
+
+2/9/2009
+- Fixed compatibility issue with OAuth Gem 3.1 (wr0ngway and aeden)
+- Added Test:Unit tests to generator (Ed Hickey)
+- added missing oauth_clients/edit.html.erb view template (Ed Hickey)
+- added missing :oauth_clients resource route in USAGE (Ed Hickey)
+- Don't throw NPE it token is not in db (Haruska)
+- Cleaned up whitespace (bricolage, Nicholas Nam)
+- Fixed bug in default verify_oauth_signature (igrigorik)
+- Doc fixes (skippy)
+
+6/23/2008
+
+- Split OAuth controller into two parts: OAuth and OAuth clients. [jcrosby]
+
+revision 31
+
+- patch that fixes a problem in oauth_required from Hannes Tyden and Sean Treadway from SoundCloud. Thanks.
+
+revision 30
+
+- updated to use oauth gem 0.2.1
+
+
+revision 23
+
+- removed all core libraries from plugin. They are now in the oauth gem.
+
+# oauth-plugin-pre-gem Branch created
+
+revision 18
+- added a generator for creation oauth_providers
+
+revision 12
+- the bug with post and put has now been fixed.
+- better documentation
+
+revision 9
+- added a test helper. Include OAuth::TestHelper in your tests or specs to mock incoming requests
+
+revision: 8
+- moved tests into oauth folder and renamed them to make them work with autotest by default
+- Refactored the request methods to make them more flexible and ready for integrating with ActiveResource
+- There are a few tests that fail. All of them to do with put and post requests with payload data. I decided to commit anyway, to get the new api out.
+
+revision: 7
+
+- Done a lot of work on the Server side of things. The Server class has changed a lot and is likely to be incompatible with previous versions
+
+revision: 6
+
+- Throws InsecureSignatureMethod exception if attempting to use straight sha1 or md5.
+- Disables plaintext signature over http (throws an InsecureSignatureMethod)
+- Better testing of signature methods - the prior tests were seriously flawed.
+
+revision: 5
+
+- Removed support for sha1 and md5
+- Implemented draft 6 support of OAuth removing secrets from base string

data/Gemfile

@@ -0,0 +1,27 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in oauth-plugin.gemspec
+gemspec
+
+require 'rbconfig'
+
+platforms :ruby do
+  if RbConfig::CONFIG['target_os'] =~ /darwin/i
+    gem 'rb-fsevent'
+    gem 'growl'
+  end
+  if RbConfig::CONFIG['target_os'] =~ /linux/i
+    gem 'rb-inotify', '>= 0.5.1'
+    gem 'libnotify',  '~> 0.1.3'
+  end
+end
+
+platforms :jruby do
+  if RbConfig::CONFIG['target_os'] =~ /darwin/i
+    gem 'growl'
+  end
+  if RbConfig::CONFIG['target_os'] =~ /linux/i
+    gem 'rb-inotify', '>= 0.5.1'
+    gem 'libnotify',  '~> 0.1.3'
+  end
+end

data/Guardfile

@@ -0,0 +1,8 @@
+# A sample Guardfile
+# More info at http://github.com/guard/guard#readme
+
+guard 'rspec', :version => 2, :cli => '-c' do
+  watch(%r{^spec/(.*)_spec.rb})
+  watch(%r{^lib/oauth/(.+)\.rb}) { |m| "spec/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')   { "spec" }
+end

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2007 Pelle Braendgaard
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,542 @@
+= OAuth Plugin
+
+This is a plugin for implementing OAuth Providers and Consumers in Rails applications.
+
+We support the revised OAuth 1.0a specs at:
+
+http://tools.ietf.org/html/rfc5849
+
+As well as support for OAuth 2.0:
+
+http://tools.ietf.org/html/draft-ietf-oauth-v2-22
+
+Find out more on the OAuth site at:
+
+http://oauth.net
+
+== IMPORTANT note for people upgrading the provider
+
+There are several changes to the latest OAuth 2.0 spec which requires a couple of changes to 2 models which you are REQUIRED to update manually if you are supporting OAuth2.
+
+https://github.com/pelle/oauth-plugin/blob/master/lib/generators/active_record/oauth_provider_templates/oauth2_token.rb
+
+  class Oauth2Token < AccessToken
+    attr_accessor :state
+    def as_json(options={})
+      d = {:access_token=>token, :token_type => 'bearer'}
+      d[:expires_in] = expires_in if expires_at
+      d
+    end
+
+    def to_query
+      q = "access_token=#{token}&token_type=bearer"
+      q << "&state=#{URI.escape(state)}" if @state
+      q << "&expires_in=#{expires_in}" if expires_at
+      q << "&scope=#{URI.escape(scope)}" if scope
+      q
+    end
+
+    def expires_in
+      expires_at.to_i - Time.now.to_i
+    end
+  end
+
+
+https://github.com/pelle/oauth-plugin/blob/master/lib/generators/active_record/oauth_provider_templates/oauth2_verifier.rb
+
+  class Oauth2Verifier < OauthToken
+    validates_presence_of :user
+    attr_accessor :state
+
+    def exchange!(params={})
+      OauthToken.transaction do
+        token = Oauth2Token.create! :user=>user,:client_application=>client_application, :scope => scope
+        invalidate!
+        token
+      end
+    end
+
+    def code
+      token
+    end
+
+    def redirect_url
+      callback_url
+    end
+
+    def to_query
+      q = "code=#{token}"
+      q << "&state=#{URI.escape(state)}" if @state
+      q
+    end
+
+    protected
+
+    def generate_keys
+      self.token = OAuth::Helper.generate_key(20)[0,20]
+      self.expires_at = 10.minutes.from_now
+      self.authorized_at = Time.now
+    end
+
+  end
+
+There are matching specs for these which you may want to move into your project as well.
+
+== Requirements
+
+You need to install the oauth gem (0.4.4) which is the core OAuth ruby library. It will likely NOT work on any previous version of the gem.
+
+  gem install oauth
+
+== Installation (Rails 3.0)
+
+Add the plugin to your Gemfile:
+
+  gem "oauth-plugin", "~> 0.4.0"
+
+And install it:
+
+  bundle install
+
+== Installation (Rails 2.x)
+
+The plugin can now be installed as an gem from github, which is the easiest way to keep it up to date.
+
+  gem install oauth-plugin --pre
+
+You should add the following in the gem dependency section of environment.rb
+
+  config.gem "oauth"
+  config.gem "oauth-plugin"
+
+Alternatively you can install it in vendors/plugin:
+
+  script/plugin install git://github.com/pelle/oauth-plugin.git
+
+The Generator currently creates code (in particular views) that only work in Rails 2 and 3.
+
+It should not be difficult to manually modify the code to work on Rails 1.2.x
+
+I think the only real issue is that the views have .html.erb extensions. So these could theoretically just be renamed to .rhtml.
+
+Please let me know if this works and I will see if I can make the generator conditionally create .rhtml for pre 2.0 versions of RAILS.
+
+== OAuth Provider generator (Rails 3)
+
+This currently supports rspec, test_unit, haml, erb, active_record and mongoid:
+
+  rails g oauth_provider
+
+This generates OAuth and OAuth client controllers as well as the required models.
+
+It requires an authentication framework such as acts_as_authenticated, restful_authentication or restful_open_id_authentication. It also requires Rails 2.0.
+
+=== INSTALL RACK FILTER (NEW)
+
+A big change over previous versions is that we now use a rack filter. You have to install this in your application.rb file:
+
+  require 'oauth/rack/oauth_filter'
+  config.middleware.use OAuth::Rack::OAuthFilter
+
+
+=== Generator Options
+
+The generator supports the defaults you have created in your application.rb file. eg:
+
+  config.generators do |g|
+    g.orm             :mongoid
+    g.template_engine :haml
+    g.test_framework  :rspec
+  end
+
+=== User Model
+
+Add the following lines to your user model:
+
+  has_many :client_applications
+  has_many :tokens, :class_name => "OauthToken", :order => "authorized_at desc", :include => [:client_application]
+
+== OAuth Provider generator (Rails 2)
+
+While it isn't very flexible at the moment there is an oauth_provider generator which you can use like this:
+
+  ./script/generate oauth_provider
+
+This generates OAuth and OAuth client controllers as well as the required models.
+
+It requires an authentication framework such as acts_as_authenticated, restful_authentication or restful_open_id_authentication. It also requires Rails 2.0.
+
+=== INSTALL RACK FILTER (NEW)
+
+A big change over previous versions is that we now use a rack filter. You have to install this in your config/environment.rb file:
+
+  require 'oauth/rack/oauth_filter'
+  config.middleware.use OAuth::Rack::OAuthFilter
+
+=== Generator Options
+
+By default the generator generates RSpec and ERB templates. The generator can instead create Test::Unit and/or HAML templates. To do this use the following options:
+
+  ./script/generate oauth_provider --test-unit --haml
+
+These can of course be used individually as well.
+
+=== User Model
+
+Add the following lines to your user model:
+
+  has_many :client_applications
+  has_many :tokens, :class_name => "OauthToken", :order => "authorized_at desc", :include => [:client_application]
+
+=== Migrate database
+
+The database is defined in:
+
+  db/migrate/XXX_create_oauth_tables.rb
+
+Run them as any other normal migration in rails with:
+
+  rake db:migrate
+
+== Upgrading from OAuth 1.0 to OAuth 1.0a
+
+As the flow has changed slightly and there are a couple of database changes it isn't as simple as just updating the plugin. Please follow these steps closely:
+
+=== Add a migration
+
+You need to add a migration:
+
+  script/generate migration upgrade_oauth
+
+Make it look like this:
+
+  class UpgradeOauth < ActiveRecord::Migration
+    def self.up
+      add_column :oauth_tokens, :callback_url, :string
+      add_column :oauth_tokens, :verifier, :string, :limit => 20
+    end
+
+    def self.down
+      remove_column :oauth_tokens, :callback_url
+      remove_column :oauth_tokens, :verifier
+    end
+  end
+
+=== Change code
+
+There are changes to the following files:
+
+  app/models/client_application.rb
+  app/models/request_token.rb
+  app/controllers/oauth_controller.rb
+
+=== Changes in client_application.rb
+
+Add the following towards the top of the model class
+
+  attr_accessor :token_callback_url
+
+Then change the create_request_token method to the following:
+
+  def create_request_token
+    RequestToken.create :client_application => self, :callback_url => token_callback_url
+  end
+
+=== Changes in request_token.rb
+
+The RequestToken contains the bulk of the changes so it's easiest to list it in it's entirety. Mainly we need to add support for the oauth_verifier parameter and also tell the client that we support OAuth 1.0a.
+
+Make sure it looks like this:
+
+  class RequestToken < OauthToken
+
+    attr_accessor :provided_oauth_verifier
+
+    def authorize!(user)
+      return false if authorized?
+      self.user = user
+      self.authorized_at = Time.now
+      self.verifier=OAuth::Helper.generate_key(16)[0,20] unless oauth10?
+      self.save
+    end
+
+    def exchange!
+      return false unless authorized?
+      return false unless oauth10? || verifier == provided_oauth_verifier
+
+      RequestToken.transaction do
+        access_token = AccessToken.create(:user => user, :client_application => client_application)
+        invalidate!
+        access_token
+      end
+    end
+
+    def to_query
+      if oauth10?
+        super
+      else
+        "#{super}&oauth_callback_confirmed = true"
+      end
+    end
+
+    def oob?
+      self.callback_url == 'oob'
+    end
+
+    def oauth10?
+      (defined? OAUTH_10_SUPPORT) && OAUTH_10_SUPPORT && self.callback_url.blank?
+    end
+
+  end
+
+=== Changes in oauth_controller
+
+All you need to do here is the change the authorize action to use the request_token callback url and add the oauth_verifier to the callback url.
+
+  def authorize
+    @token = ::RequestToken.find_by_token params[:oauth_token]
+    unless @token.invalidated?
+      if request.post?
+        if params[:authorize] == '1'
+          @token.authorize!(current_user)
+          if @token.oauth10?
+            @redirect_url = params[:oauth_callback] || @token.client_application.callback_url
+          else
+            @redirect_url = @token.oob? ? @token.client_application.callback_url : @token.callback_url
+          end
+
+          if @redirect_url
+            if @token.oauth10?
+              redirect_to "#{@redirect_url}?oauth_token=#{@token.token}"
+            else
+              redirect_to "#{@redirect_url}?oauth_token=#{@token.token}&oauth_verifier=#{@token.verifier}"
+            end
+          else
+            render :action => "authorize_success"
+          end
+        elsif params[:authorize] == "0"
+          @token.invalidate!
+          render :action => "authorize_failure"
+        end
+      end
+    else
+      render :action => "authorize_failure"
+    end
+  end
+
+Alternatively if you haven't customized your controller you can replace the full controller with this:
+
+  require 'oauth/controllers/provider_controller'
+  class OauthController < ApplicationController
+    include OAuth::Controllers::ProviderController
+  end
+
+This way the controller will automatically include bug fixes in future versions of the plugin.
+
+The rest of the changes are in the plugin and will be automatically be included.
+
+*Note* OAuth 1.0a removes support for callback url's passed to the authorize page, clients must either define a callback url in their client application or pass one on the token request page.
+
+=== Supporting old OAuth 1.0 clients
+
+If you absolutely have to support older OAuth 1.0 clients on an optional basis, we now include a switch to turn it back on.
+
+For legacy OAUTH 1.0 support add the following constant in your environment.rb
+
+  OAUTH_10_SUPPORT = true
+
+Note, you should only do this if you really positively require to support old OAuth1.0 clients. There is a serious security issue with this.
+
+== Protecting your actions
+
+I recommend that you think about what your users would want to provide access to and limit oauth for those only. For example in a CRUD controller you may think about if you want to let consumer applications do the create, update or delete actions. For your application this might make sense, but for others maybe not.
+
+If you want to give oauth access to everything a registered user can do, just replace the filter you have in your controllers with:
+
+  before_filter :login_or_oauth_required
+
+If you want to restrict consumers to the index and show methods of your controller do the following:
+
+  before_filter :login_required, :except => [:show,:index]
+  before_filter :login_or_oauth_required, :only => [:show,:index]
+
+If you have an action you only want used via oauth:
+
+  before_filter :oauth_required
+
+You can also use this method in your controller:
+
+  oauthenticate :strategies => :token , :interactive => false
+
+All of these places the tokens user in current_user as you would expect. It also exposes the following methods:
+
+* current_token - for accessing the token used to authorize the current request
+* current_client_application - for accessing information about which consumer is currently accessing your request
+
+You could add application specific information to the OauthToken and ClientApplication model for such things as object level access control, billing, expiry etc. Be creative and you can create some really cool applications here.
+
+== OAuth Consumer generator
+
+The oauth_consumer generator creates a controller to manage the authentication flow between your application and any number of external OAuth secured applications that you wish to connect to.
+
+To run it in Rails 3 simply run:
+
+  rails g oauth_consumer
+
+In previous versions:
+
+  ./script/generate oauth_consumer
+
+This generates the OauthConsumerController as well as the ConsumerToken model.
+
+=== Generator Options (Rails 2)
+
+By default the generator generates ERB templates. The generator can instead create HAML templates. To do this use the following options:
+
+  ./script/generate oauth_consumer --haml
+
+Rails 3 respects your application defaults, see the oauth provider generator section above for more info.
+
+=== Configuration
+
+All configuration of applications is done in
+
+  config/initializers/oauth_consumers.rb
+
+Add entries to OAUTH_CREDENTIALS for all OAuth Applications you wish to connect to. Get this information by registering your application at the particular applications developer page.
+
+  OAUTH_CREDENTIALS = {
+    :twitter => {
+      :key => "key",
+      :secret => "secret",
+      :client => :twitter_gem, # :twitter_gem or :oauth_gem (defaults to :twitter_gem)
+      :expose => false, # set to true to expose client via the web
+    },
+    :agree2 => {
+      :key => "key",
+      :secret => "secret",
+      :expose => false, # set to true to expose client via the web
+    },
+    :hour_feed => {
+      :key => "",
+      :secret => "",
+      :options = {
+        :site => "http://hourfeed.com"
+      }
+    },
+    :nu_bux => {
+      :key => "",
+      :secret => "",
+      :super_class => "OpenTransactToken",  # if a OAuth service follows a particular standard
+                                          # with a token implementation you can set the superclass
+                                          # to use
+      :options => {
+        :site => "http://nubux.heroku.com"
+      }
+    }
+  }
+
+You can add any of the options that the OAuth::Consumer.new accepts to the options hash: http://oauth.rubyforge.org/rdoc/classes/OAuth/Consumer.html
+
+:key, :secret are required as well as :options[:site] etc. for non custom ConsumerToken services.
+
+=== ConsumerToken models
+
+For each site setup in the OAUTH_CREDENTIALS hash the plugin goes through and loads or creates a new model class that subclasses ConsumerToken.
+
+eg. If you connect to Yahoo's FireEagle you would add the :fire_eagle entry to OAUTH_CREDENTIALS and a new FireEagleToken model class will be created on the fly.
+
+This allows you to add a has_one association in your user model:
+
+  has_one  :fire_eagle, :class_name => "FireEagleToken", :dependent => :destroy
+
+And you could do:
+
+  @location = @user.fire_eagle.client.location
+
+The client method gives you a OAuth::AccessToken which you can use to perform rest operations on the client site - see http://oauth.rubyforge.org/rdoc/classes/OAuth/AccessToken.html
+
+If you are using Mongoid you want to add an embeds_many association in your user model:
+
+  embeds_many :consumer_tokens
+
+=== Custom ConsumerToken models
+
+Before creating the FireEagleToken model the plugin checks if a class already exists by that name or if we provide an api wrapper for it. This allows you to create a better token model that uses an existing ruby gem.
+
+Currently we provide the following semi tested tokens wrappers:
+
+* FireEagle
+* Twitter
+* Agree2
+
+These can be found in lib/oauth/models/consulers/services. Contributions will be warmly accepted for your favorite OAuth service.
+
+=== The OauthConsumerController
+
+To connect a user to an external service link or redirect them to:
+
+  /oauth_consumers/[SERVICE_NAME]
+
+Where SERVICE_NAME is the name you set in the OAUTH_CREDENTIALS hash. This will request the request token and redirect the user to the services authorization screen. When the user accepts the get redirected back to:
+
+  /oauth_consumers/[SERVICE_NAME]/callback
+
+You can specify this url to the service you're calling when you register, but it will automatically be sent along anyway.
+
+=== Expose client
+
+This is designed to let your local javascript apps access remote OAuth apis. You have to specifically enable this by adding the expose flag to your oauth config file. eg:
+
+  OAUTH_CREDENTIALS = {
+    :twitter => {
+      :key => "key",
+      :secret => "secret",
+      :client => :oauth_gem, # :twitter_gem or :oauth_gem (defaults to :twitter_gem)
+      :expose => true      # set to true to expose client via the web
+    }
+
+Once the user has authorized your application, you can access the client APIs via:
+
+  /oauth_consumers/[SERVICE_NAME]/client/[ENDPOINT]
+
+For example to get the user's Google Calendars in JSON (documented in their API as "https://www.google.com/calendar/feeds/default?alt=jsonc"), you would append that path as the ENDPOINT above, i.e.
+
+  /oauth_consumers/google/client/calendar/feeds/default?alt=jsonc
+
+As another example, to get my Twitter info as XML (available at "https://api.twitter.com/1/users/show.xml?screen_name=pelleb"), use:
+
+  /oauth_consumers/twitter/client/1/users/show.xml?screen_name=pelleb
+
+=== Migrate database
+
+The database is defined in:
+
+  db/migrate/XXX_create_oauth_consumer_tokens.rb
+
+Run them as any other normal migration in rails with:
+
+  rake db:migrate
+
+== Contribute and earn OAuth Karma
+
+Anyone who has a commit accepted into the official oauth-plugin git repo is awarded OAuthKarma:
+
+https://picomoney.com/oauth-karma/accounts
+
+
+== More
+
+The Mailing List for all things OAuth in Ruby is:
+
+http://groups.google.com/group/oauth-ruby
+
+The Mailing list for everything else OAuth is:
+
+http://groups.google.com/group/oauth
+
+The OAuth Ruby Gem home page is http://oauth.rubyforge.org
+
+Please help documentation, patches and testing.
+
+Copyright (c) 2007-2011 Pelle Braendgaard and contributors, released under the MIT license