Skip to content
Newer
Older
100644 318 lines (222 sloc) 10.5 KB
2e7a08e @c9s Update readme
authored
1 # NAME
2
42abb5b @c9s Update description
authored
3 Plack::Middleware::OAuth - Plack middleware for OAuth1, OAuth2 and builtin provider configs.
2e7a08e @c9s Update readme
authored
4
5 # DESCRIPTION
6
2de2100 @c9s Add features to Makefile.PL
authored
7 This module is still in __**BETA**__ , __DO NOT USE THIS FOR PRODUCTION!__
3a84ec1 @c9s Handler classes.
authored
8
4a891d1 @c9s gen markdown readme
authored
9 [Plack::Middleware::OAuth](http://search.cpan.org/perldoc?Plack::Middleware::OAuth) supports OAuth1 and OAuth2, and provides builtin config for providers like Twitter, GitHub, Google, Facebook.
4323b61 @c9s Update README
authored
10 The only one thing you need to mount your OAuth service is to setup your `consumer_key`, `consumer_secret` (for OAuth1) or `client_id`, `client_secret`, `scope` (for OAuth2).
2e7a08e @c9s Update readme
authored
11
4323b61 @c9s Update README
authored
12 This middleware also generates authorize url (mount_path/provider_id) and auththorize callback url (mount_path/provider_id/callback).
75a9e59 @c9s Import files
authored
13 If the authorize path matches, then user will be redirected to OAuth provider to authorize your application.
2e7a08e @c9s Update readme
authored
14
eeae9b3 @c9s Remove register_env
authored
15 For example, if you mount [Plack::Middleware::OAuth](http://search.cpan.org/perldoc?Plack::Middleware::OAuth) on `/oauth`, then you can access [http://youdomain.com/oauth/twitter](http://youdomain.com/oauth/twitter) to authorize,
379a6d8 @c9s Update readme
authored
16 [Plack::Middleware::OAuth](http://search.cpan.org/perldoc?Plack::Middleware::OAuth) will redirect you to Twitter, after authorized, then Twitter will redirect you to your callback url
a4b9e4a @c9s Update readme
authored
17 [http://youdomain.com/oauth/twitter/callback](http://youdomain.com/oauth/twitter/callback).
d037c1c @c9s Update readme
authored
18
eeae9b3 @c9s Remove register_env
authored
19 For more details, please check the example psgi in `eg/` directory.
42abb5b @c9s Update description
authored
20
d037c1c @c9s Update readme
authored
21 # SYNOPSIS
22
c89cc02 @c9s Update readme
authored
23 use Plack::Builder;
24
25 builder {
26
a4b9e4a @c9s Update readme
authored
27 mount '/oauth' => builder {
28 enable 'OAuth',
eb2122c @c9s disable pod.t
authored
29
881bf67 @c9s bold text for warnings.
authored
30 on_success => sub {
e71e277 @c9s Update readme file
authored
31 my ($self,$token) = @_;
881bf67 @c9s bold text for warnings.
authored
32 my $env = $self->env;
33
e71e277 @c9s Update readme file
authored
34 my $config = $self->config; # provider config
35
36
37
881bf67 @c9s bold text for warnings.
authored
38 return $self->render( '..html content..' );
39 return $self->redirect( .... URL ... );
40
eae80bf @c9s Update readme
authored
41 return [ 200 , [ 'Content-type' => 'text/html' ] , 'Signin!' ];
881bf67 @c9s bold text for warnings.
authored
42
43
44
eae80bf @c9s Update readme
authored
45 },
eb2122c @c9s disable pod.t
authored
46
47 on_error => sub { ... },
48
7e69e12 @c9s Update markdown readme
authored
49 providers => 'providers.yml', # also works
50
a4b9e4a @c9s Update readme
authored
51 providers => {
52
53 # capital case implies Plack::Middleware::OAuth::Twitter
54 'Twitter' =>
55 {
56 consumer_key => ...
57 consumer_secret => ...
58 },
59
60 # captical case implies Plack::Middleware::OAuth::Facebook
61 'Facebook' =>
62 {
63 client_id => ...
64 client_secret => ...
65 scope => 'email,read_stream',
66 },
67
4a891d1 @c9s gen markdown readme
authored
68 'GitHub' =>
a4b9e4a @c9s Update readme
authored
69 {
70 client_id => ...
71 client_secret => ...
72 scope => 'user,public_repo'
73 },
74
e7d890e @c9s Add Google config to POD.
authored
75 'Google' => {
76 client_id => '',
77 client_secret => '',
78 scope => 'https://www.google.com/m8/feeds/'
79 },
daaa40a @c9s Checking in changes prior to tagging of version 0.10.
authored
80
81
82 'Live' => {
83 client_id => '',
84 client_secret => '',
85 scope => 'wl.basic'
86 },
e7d890e @c9s Add Google config to POD.
authored
87
a4b9e4a @c9s Update readme
authored
88 'custom_provider' => {
89 version => 1,
90 ....
91 }
92 };
93 };
c89cc02 @c9s Update readme
authored
94 $app;
95 };
d037c1c @c9s Update readme
authored
96
97 The callback/redirect URL is set to {SCHEMA}://{HTTP_HOST}/{prefix}/{provider}/callback by default.
98
7e69e12 @c9s Update markdown readme
authored
99 # OAuth URL and Callback URL
100
101 For a defined key in providers hashref, and you mounted OAuth middleware at `/oauth`,
102 the generated URLs will be like:
103
104 authorize path: /oauth/custom_provider
105 authorize callback path: /oauth/custom_provider/callback
106
107 The provider id (key) will be converted into lower-case.
108
4a891d1 @c9s gen markdown readme
authored
109 For example, GitHub's URLs will be like:
7e69e12 @c9s Update markdown readme
authored
110
111 /oauth/github
112 /oauth/github/callback
113
114 Facebook,
115
116 /oauth/facebook
117 /oauth/facebook/callback
379a6d8 @c9s Update readme
authored
118
7e69e12 @c9s Update markdown readme
authored
119 You can also specify custom callback URL in a provider config.
379a6d8 @c9s Update readme
authored
120
9f9e41f @c9s gen readme.mkdn
authored
121
122
881bf67 @c9s bold text for warnings.
authored
123 # Specify Success Callback
124
125 When access token is got, success handler will be called:
eae80bf @c9s Update readme
authored
126
127 enable 'OAuth',
128 providers => { .... },
881bf67 @c9s bold text for warnings.
authored
129 on_success => sub {
e71e277 @c9s Update readme file
authored
130 my ($self,$token) = @_;
881bf67 @c9s bold text for warnings.
authored
131
c1c72c4 @c9s Update README
authored
132 # $self: Plack::Middleware::OAuth::Handler (isa Plack::Request) object
881bf67 @c9s bold text for warnings.
authored
133
c1c72c4 @c9s Update README
authored
134 return $self->render( .... );
135
136 return $self->redirect( .... );
137
138 return $self->to_yaml( .... );
139
140 return $self->to_json( .... );
141
142 # or just return a raw arrayref
eae80bf @c9s Update readme
authored
143 return [ 200 , [ 'Content-type' => 'text/html' ] , 'Signin!' ];
144 };
145
881bf67 @c9s bold text for warnings.
authored
146 Without specifying `on_success`, OAuth middleware will use YAML to dump the response data to page.
7deaebf @c9s Oh my god i used $this in perl..!! wtf
authored
147
e71e277 @c9s Update readme file
authored
148 To use access token to get user information, the following example demonstracte how to get corresponding user information:
149
150 on_success => sub {
151 my ($self,$token) = @_;
152
153 if( $token->is_provider('Twitter') ) {
154 my $config = $self->config;
155
156 # return $self->to_yaml( $config );
157
158 # get twitter user infomation with (api)
159 my $twitter = Net::Twitter->new(
160 traits => [qw/OAuth API::REST/],
161 consumer_key => $config->{consumer_key},
162 consumer_secret => $config->{consumer_secret},
163 access_token => $token->access_token,
164 access_token_secret => $token->access_token_secret,
165 );
166
167 return $self->to_yaml( {
168 account_settings => $twitter->account_settings,
169 account_totals => $twitter->account_totals,
170 show_user => $twitter->show_user( $token->params->{extra_params}->{screen_name} )
171 } );
172 }
173 }
174
9f9e41f @c9s gen readme.mkdn
authored
175 # User Info Query Interface
176
177 To query user info from OAuth provider, you can use [Plack::Middleware::OAuth::UserInfo](http://search.cpan.org/perldoc?Plack::Middleware::OAuth::UserInfo) to help you.
178
179 my $userinfo = Plack::Middleware::OAuth::UserInfo->new(
180 token => $token ,
181 config => $provider_config
182 );
183 my $info_hash = $userinfo->ask( 'Twitter' ); # load Plack::Middleware::OAuth::UserInfo::Twitter
184
185 In you oauth success handler, it would be like:
186
187 on_success => sub {
188 my ($self,$token) = @_;
189
190 my $userinfo = Plack::Middleware::OAuth::UserInfo->new(
191 token => $token ,
192 config => $self->config
193 );
194 my $info_hash = $userinfo->ask( 'Twitter' ); # load Plack::Middleware::OAuth::UserInfo::Twitter
195 return $self->to_yaml( $info_hash );
196 };
197
7226f51 @c9s Remove YAML, JSON deps
authored
198 # Error Handler
199
200 An error handler should return a response data, it should be an array reference, for be finalized from [Plack::Response](http://search.cpan.org/perldoc?Plack::Response):
201
202 enable 'OAuth',
203 providers => { .... },
204 on_error => sub {
e71e277 @c9s Update readme file
authored
205 my ($self,$token) = @_;
206
207 $self->render( 'Error' ) unless $token;
7226f51 @c9s Remove YAML, JSON deps
authored
208
209 # $self: Plack::Middleware::OAuth::Handler (isa Plack::Request) object
210
211 };
212
ba24267 @c9s Update markdown readme
authored
213 # OAuth1 AccessToken Callback Data Structure
214
215 Twitter uses OAuth 1.0a, and the access token callback returns data like this:
216
217 ---
218 params:
219 access_token: {{string}}
220 access_token_secret: {{string}}
221 extra_params:
222 screen_name: {{screen name}}
223 user_id: {{user id}}
224 provider: Twitter
225 version: 1
226
227
228
229 # OAuth2 AccessToken Callback Data Structure
230
4a891d1 @c9s gen markdown readme
authored
231 GitHub uses OAuth 2.0, and the access token callback returns data like this:
ba24267 @c9s Update markdown readme
authored
232
233 ---
234 params:
235 code: {{string}}
236 access_token: {{string}}
237 token_type: bearer
4a891d1 @c9s gen markdown readme
authored
238 provider: GitHub
ba24267 @c9s Update markdown readme
authored
239 version: 2
240
73ea7fd @c9s Checking in changes prior to tagging of version 0.06.
authored
241 Google returns:
242
243 ---
244 params:
245 access_token: {{string}}
246 code: {{string}}
247 expires_in: 3600
248 refresh_token: {{string}}
249 token_type: Bearer
250 provider: Google
251 version: 2
252
e71e277 @c9s Update readme file
authored
253 # Sessions
254
17f1565 @c9s Rename Github to GitHub
authored
255 You can get OAuth1 or OAuth2 access token from [Plack::Session](http://search.cpan.org/perldoc?Plack::Session),
e71e277 @c9s Update readme file
authored
256
257 my $session = Plack::Session->new( $env );
258 $session->get( 'oauth.twitter.access_token' );
b03d5aa @c9s set session oauth.{provider} = 1
authored
259 $session->get( 'oauth.twitter.access_token_secret' ); # OAuth version
e71e277 @c9s Update readme file
authored
260
b03d5aa @c9s set session oauth.{provider} = 1
authored
261 $session->get( 'oauth.facebook.access_token' );
262 $session->get( 'oauth.facebook.version' ); # OAuth version
263
264 Custom provider:
265
266 $session->get( 'oauth.custom_provider.access_token' );
267 $session->get( 'oauth.custom_provider.version' );
e71e277 @c9s Update readme file
authored
268
269
270
c10b888 @c9s Update readme.mkd
authored
271 # Supported Providers
272
8a3c3ac @c9s A Generic Handler for refactoring.
authored
273 - Google
274 - Twitter
275 - Facebook
4a891d1 @c9s gen markdown readme
authored
276 - GitHub
daaa40a @c9s Checking in changes prior to tagging of version 0.10.
authored
277 - Live
c10b888 @c9s Update readme.mkd
authored
278
ba24267 @c9s Update markdown readme
authored
279 # See Also
280
281 [Net::OAuth](http://search.cpan.org/perldoc?Net::OAuth), [Net::OAuth2](http://search.cpan.org/perldoc?Net::OAuth2)
282
d037c1c @c9s Update readme
authored
283 # Reference
284
8a3c3ac @c9s A Generic Handler for refactoring.
authored
285 - OAuth Workflow
3230378 @c9s Add README.mkdn
authored
286 [http://hueniverse.com/oauth/guide/workflow/](http://hueniverse.com/oauth/guide/workflow/)
8a3c3ac @c9s A Generic Handler for refactoring.
authored
287 - OAuth 2.0 Protocal Draft
3230378 @c9s Add README.mkdn
authored
288 [http://tools.ietf.org/html/draft-ietf-oauth-v2](http://tools.ietf.org/html/draft-ietf-oauth-v2)
4a891d1 @c9s gen markdown readme
authored
289 - GitHub - Create A New Client
2e7a08e @c9s Update readme
authored
290 [https://github.com/account/applications](https://github.com/account/applications)
881bf67 @c9s bold text for warnings.
authored
291 - Twitter - Using OAuth 1.0a
292 [https://dev.twitter.com/docs/auth/oauth](https://dev.twitter.com/docs/auth/oauth)
ba24267 @c9s Update markdown readme
authored
293 - Twitter - Moving from Basic Auth to OAuth
294 [https://dev.twitter.com/docs/auth/moving-from-basic-auth-to-oauth](https://dev.twitter.com/docs/auth/moving-from-basic-auth-to-oauth)
295 - Single-user OAuth with Examples
296 [https://dev.twitter.com/docs/auth/oauth/single-user-with-examples](https://dev.twitter.com/docs/auth/oauth/single-user-with-examples)
8a3c3ac @c9s A Generic Handler for refactoring.
authored
297 - Twitter - Create A New App
2e7a08e @c9s Update readme
authored
298 [https://dev.twitter.com/apps](https://dev.twitter.com/apps)
8a3c3ac @c9s A Generic Handler for refactoring.
authored
299 - Facebook OAuth
2e7a08e @c9s Update readme
authored
300 [http://developers.facebook.com/docs/authentication/](http://developers.facebook.com/docs/authentication/)
8a3c3ac @c9s A Generic Handler for refactoring.
authored
301 - Facebook - Create A New App
2e7a08e @c9s Update readme
authored
302 [https://developers.facebook.com/apps](https://developers.facebook.com/apps)
8a3c3ac @c9s A Generic Handler for refactoring.
authored
303 - Facebook - Permissions
379a6d8 @c9s Update readme
authored
304 [http://developers.facebook.com/docs/reference/api/permissions/](http://developers.facebook.com/docs/reference/api/permissions/)
8a3c3ac @c9s A Generic Handler for refactoring.
authored
305 - Facebook - How to handle expired access_token
379a6d8 @c9s Update readme
authored
306 [https://developers.facebook.com/blog/post/500/](https://developers.facebook.com/blog/post/500/)
8a3c3ac @c9s A Generic Handler for refactoring.
authored
307 - Google OAuth
379a6d8 @c9s Update readme
authored
308 [http://code.google.com/apis/accounts/docs/OAuth2.html](http://code.google.com/apis/accounts/docs/OAuth2.html)
8a3c3ac @c9s A Generic Handler for refactoring.
authored
309 - Google OAuth Scope:
625046d @c9s Checking in changes prior to tagging of version 0.091.
authored
310 [http://code.google.com/apis/gdata/faq.html#AuthScopes](http://code.google.com/apis/gdata/faq.html#AuthScopes)
daaa40a @c9s Checking in changes prior to tagging of version 0.10.
authored
311 - Live OAuth
312 [http://msdn.microsoft.com/en-us/library/hh243647.aspx](http://msdn.microsoft.com/en-us/library/hh243647.aspx)
313 - Live OAuth Scope:
314 [http://msdn.microsoft.com/en-us/library/hh243646.aspx](http://msdn.microsoft.com/en-us/library/hh243646.aspx)
625046d @c9s Checking in changes prior to tagging of version 0.091.
authored
315
316 ## Contributors
317
318 RsrchBoy
Something went wrong with that request. Please try again.