Merge 17130 from trunk.
[rails.git] / 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