vendor/plugins/oauth-plugin/README.rdoc

   1 = OAuth Plugin
   2
   3 This is the beginning of a plugin for implementing OAuth Providers in Rails applications.
   4
   5 See the OAuth specs at:
   6
   7 http://oauth.net/core/1.0/
   8
   9 and the OAuth site at:
  10
  11 http://oauth.net
  12
  13 == Requirements
  14
  15 You need to install the oauth gem (0.2.1) which is the core OAuth ruby library. It will NOT work on any previous version of the gem.
  16
  17   sudo gem install oauth
  18
  19 The Generator currently creates code (in particular views) that only work in Rails 2.
  20
  21 It should not be difficult to manually modify the code to work on Rails 1.2.x
  22
  23 I think the only real issue is that the views have .html.erb extensions. So these could theoretically just be renamed to .rhtml.
  24
  25 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.
  26
  27 == OAuth Provider generator
  28
  29 While it isn't very flexible at the moment there is an oauth_provider generator which you can use like this:
  30
  31 ./script/generate oauth_provider
  32
  33 This generates OAuth and OAuth client controllers as well as the required models.
  34
  35 It requires an authentication framework such as acts_as_authenticated, restful_authentication or restful_open_id_authentication. It also requires Rails 2.0.
  36
  37 === Routes
  38
  39 You need to add the following to your routes (config/routes.rb)
  40
  41         map.resources :oauth_clients
  42         map.authorize '/oauth/authorize',:controller=>'oauth',:action=>'authorize'
  43         map.request_token '/oauth/request_token',:controller=>'oauth',:action=>'request_token'
  44         map.access_token '/oauth/access_token',:controller=>'oauth',:action=>'access_token'
  45         map.test_request '/oauth/test_request',:controller=>'oauth',:action=>'test_request'
  46
  47 === User Model
  48
  49 Add the following lines to your user model:
  50
  51   has_many :client_applications
  52   has_many :tokens, :class_name=>"OauthToken",:order=>"authorized_at desc",:include=>[:client_application]
  53
  54 === Migrate database
  55
  56 The database is defined in:
  57
  58         db/migrate/XXX_create_oauth_tables.rb
  59
  60 Run them as any other normal migration in rails with:
  61
  62   rake db:migrate
  63
  64 === RSpec
  65
  66 The generator installs a collection of RSpec (http://rspec.info) specs instead of normal unit_tests. If you don't use RSpec (and really why aren't you?) feel free to remove the spec folder.
  67
  68 If you would like to contribute regular unit tests I will accept them with a smile.
  69
  70 == Protecting your actions
  71
  72 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.
  73
  74 If you want to give oauth access to everything a registered user can do, just replace the filter you have in your controllers with:
  75
  76         before_filter :login_or_oauth_required
  77
  78 If you want to restrict consumers to the index and show methods of your controller do the following:
  79
  80         before_filter :login_required,:except=>[:show,:index]
  81         before_filter :login_or_oauth_required,:only=>[:show,:index]
  82
  83 If you have an action you only want used via oauth:
  84
  85         before_filter :oauth_required
  86
  87 All of these places the tokens user in current_user as you would expect. It also exposes the following methods:
  88
  89 * current_token - for accessing the token used to authorize the current request
  90 * current_client_application - for accessing information about which consumer is currently accessing your request
  91
  92 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.
  93
  94 == More
  95
  96 The Google Code project is http://code.google.com/p/oauth-plugin/
  97
  98 The Mailing List for all things OAuth in Ruby is:
  99
 100 http://groups.google.com/group/oauth-ruby
 101
 102 The Mailing list for everything else OAuth is:
 103
 104 http://groups.google.com/group/oauth
 105
 106 The OAuth Ruby Gem home page is http://oauth.rubyforge.org
 107
 108 Please help documentation, patches and testing.
 109
 110 Copyright (c) 2007-2008 Pelle Braendgaard, released under the MIT license