-
Notifications
You must be signed in to change notification settings - Fork 9
/
README
159 lines (117 loc) · 5.38 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
NAME
Dancer::Plugin::Auth::Twitter - Authenticate with Twitter
VERSION
version 0.07
SYNOPSIS
package SomeDancerApp;
use Dancer ':syntax';
use Dancer::Plugin::Auth::Twitter;
auth_twitter_init();
before sub {
if (not session('twitter_user')) {
redirect auth_twitter_authenticate_url;
}
};
get '/' => sub {
"welcome, ".session('twitter_user')->{'screen_name'};
};
get '/fail' => sub { "FAIL" };
...
CONCEPT
This plugin provides a simple way to authenticate your users through
Twitter's OAuth API. It provides you with a helper to build easily a
redirect to the authentication URI, defines automatically a callback
route handler and saves the authenticated user to your session when
done.
PREREQUESITES
In order for this plugin to work, you need the following:
* Twitter application
Anyone can register a Twitter application at
<http://dev.twitter.com/>. When done, make sure to configure the
application as a *Web* application.
* Configuration
You need to configure the plugin first: copy your "consumer_key" and
"consumer_secret" (provided by Twitter) to your Dancer's
configuration under "plugins/Auth::Twitter":
# config.yml
...
plugins:
"Auth::Twitter":
consumer_key: "1234"
consumer_secret: "abcd"
callback_url: "http://localhost:3000/auth/twitter/callback"
callback_success: "/"
callback_fail: "/fail"
engine: Net::Twitter::Lite::WithAPIv1_1
"callback_success" and "callback_fail" are optional and default to
'/' and '/fail', respectively.
The engine is optional as well. The supported engines are
"Net::Twitter" and "Net::Twitter::Lite::WithAPIv1_1"
("Net::Twitter::Lite" can also be used as a synonym for the latter).
By default the plugin will use Net::Twitter::Lite::WithAPIv1_1.
Note that you also need to provide your callback url, whose route
handler is automatically created by the plugin.
* Session backend
For the authentication process to work, you need a session backend,
in order for the plugin to store the authenticated user's
information.
Use the session backend of your choice, it doesn't make a
difference, see Dancer::Session for details about supported session
engines, or search the CPAN for new ones
<http://search.cpan.org/search?query=Dancer-Session>.
EXPORT
The plugin exports the following symbols to your application's
namespace:
twitter
The plugin uses a Net::Twitter or Net::Twitter::Lite::WithAPIv1_1 object
to do its job. You can access this object with the "twitter" symbol,
exported by the plugin.
auth_twitter_init
This function should be called before your route handlers, in order to
initialize the underlying Net::Twitter or
Net::Twitter::Lite::WithAPIv1_1 object.
auth_twitter_authorize_url
This function returns an authorize URI for redirecting unauthenticated
users. You should use this in a before filter like the following:
before sub {
# we don't want to bounce for ever!
return if request->path =~ m{/auth/twitter/callback};
if (not session('twitter_user')) {
redirect auth_twitter_authorize_url();
}
};
When the user authenticate with Twitter's OAuth interface, she's going
to be bounced back to "/auth/twitter/callback".
auth_twitter_authenticate_url
Similar to auth_twitter_authorize_url, but this function instead returns
an authenticate instead of authorize URI for redirecting unauthenticated
users, which results in a slightly different behaviour.
See <https://dev.twitter.com/pages/sign_in_with_twitter|here> to learn
about the differences.
ROUTE HANDLERS
The plugin defines the following route handler automatically
/auth/twitter/callback
This route handler is responsible for catching back a user that has just
authenticated herself with Twitter's OAuth. The route handler saves
tokens and user information in the session and then redirects the user
to the URI specified by "callback_success".
If the validation of the token returned by Twitter failed or was denied,
the user will be redirect to the URI specified by "callback_fail".
TIPS AND TRICKS
If you get the error
Net::Twitter::Role::OAuth::get_authorization_url():
GET https://api.twitter.com/oauth/request_token failed: 500
Can't verify SSL peers without knowing which Certificate Authorities to trust
you can silence it by setting the environment variable
"PERL_LWP_SSL_VERIFY_HOSTNAME" to 0.
ACKNOWLEDGEMENTS
This plugin has been written as a port of
Catalyst::Authentication::Credential::Twitter written by Jesse Stay.
This plugin was part of the Perl Dancer Advent Calendar 2010.
AUTHORS
* Alexis Sukrieh <[email protected]>
* Dancer Core Developers
COPYRIGHT AND LICENSE
This software is copyright (c) 2010 by Alexis Sukrieh.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.