1Mojolicious::Plugin::OAUustehr2(C3o)ntributed Perl DocumMeonjtoaltiicoinous::Plugin::OAuth2(3)
2
3
4
6 Mojolicious::Plugin::OAuth2 - Auth against OAuth2 APIs
7
9 This Mojolicious plugin allows you to easily authenticate against a
10 OAuth2 <http://oauth.net> provider. It includes configurations for a
11 few popular providers, but you can add your own easily as well.
12
13 Note that OAuth2 requires https, so you need to have the optional
14 Mojolicious dependency required to support it. Run the command below to
15 check if IO::Socket::SSL is installed.
16
17 $ mojo version
18
19 References
20 · <http://oauth.net/documentation/>
21
22 · <http://aaronparecki.com/articles/2012/07/29/1/oauth2-simplified>
23
24 · <http://homakov.blogspot.jp/2013/03/oauth1-oauth2-oauth.html>
25
26 · <http://en.wikipedia.org/wiki/OAuth#OAuth_2.0>
27
29 Example non-blocking application
30 use Mojolicious::Lite;
31
32 plugin "OAuth2" => {
33 facebook => {
34 key => "some-public-app-id",
35 secret => $ENV{OAUTH2_FACEBOOK_SECRET},
36 },
37 };
38
39 get "/connect" => sub {
40 my $c = shift;
41 my $get_token_args = {redirect_uri => $c->url_for("connect")->userinfo(undef)->to_abs};
42
43 $c->oauth2->get_token_p(facebook => $get_token_args)->then(sub {
44 return unless my $provider_res = shift; # Redirct to Facebook
45 $c->session(token => $provider_res->{access_token});
46 $c->redirect_to("profile");
47 })->catch(sub {
48 $c->render("connect", error => shift);
49 });
50 };
51
52 Custom connect button
53 You can add a "connect link" to your template using the
54 "oauth2.auth_url" helper. Example template:
55
56 Click here to log in:
57 <%= link_to "Connect!", $c->oauth2->auth_url("facebook", scope => "user_about_me email") %>
58
59 Configuration
60 This plugin takes a hash as config, where the keys are provider names
61 and the values are configuration for each provider. Here is a complete
62 example:
63
64 plugin "OAuth2" => {
65 custom_provider => {
66 key => "APP_ID",
67 secret => "SECRET_KEY",
68 authorize_url => "https://provider.example.com/auth",
69 token_url => "https://provider.example.com/token",
70 },
71 };
72
73 To make it a bit easier, Mojolicious::Plugin::OAuth2 has already values
74 for "authorize_url" and "token_url" for the following providers:
75
76 · dailymotion
77
78 Authentication for Dailymotion video site.
79
80 · eventbrite
81
82 Authentication for <https://www.eventbrite.com> event site.
83
84 See also <http://developer.eventbrite.com/docs/auth/>.
85
86 · facebook
87
88 OAuth2 for Facebook's graph API, <http://graph.facebook.com/>. You
89 can find "key" (App ID) and "secret" (App Secret) from the app
90 dashboard here: <https://developers.facebook.com/apps>.
91
92 See also
93 <https://developers.facebook.com/docs/reference/dialogs/oauth/>.
94
95 · github
96
97 Authentication with Github.
98
99 See also <https://developer.github.com/v3/oauth/>
100
101 · google
102
103 OAuth2 for Google. You can find the "key" (CLIENT ID) and "secret"
104 (CLIENT SECRET) from the app console here under "APIs & Auth" and
105 "Credentials" in the menu at
106 <https://console.developers.google.com/project>.
107
108 See also <https://developers.google.com/+/quickstart/>.
109
110 Testing
111 THIS API IS EXPERIMENTAL AND CAN CHANGE WITHOUT NOTICE.
112
113 To enable a "mocked" OAuth2 api, you need to give the special "mocked"
114 provider a "key":
115
116 plugin "OAuth2" => { mocked => {key => 42} };
117
118 The code above will add two new routes to your application:
119
120 · GET /mocked/oauth/authorize
121
122 This route is a web page which contains a link that takes you back
123 to "redirect_uri", with a "code". The "code" default to
124 "fake_code", but can be configured:
125
126 $c->app->oauth2->providers->{mocked}{return_code} = "...";
127
128 The route it self can also be customized:
129
130 plugin "OAuth2" => { mocked => {authorize_url => '...'} };
131
132 · POST /mocked/oauth/token
133
134 This route is will return a "access_token" which is available in
135 your "oauth2.get_token" callback. The default is "fake_token", but
136 it can be configured:
137
138 $c->app->oauth2->providers->{mocked}{return_token} = "...";
139
140 The route it self can also be customized:
141
142 plugin "OAuth2" => { mocked => {token_url => '...'} };
143
145 oauth2.auth_url
146 $url = $c->oauth2->auth_url($provider => \%args);
147
148 Returns a Mojo::URL object which contain the authorize URL. This is
149 useful if you want to add the authorize URL as a link to your webpage
150 instead of doing a redirect like "oauth2.get_token" does. %args is
151 optional, but can contain:
152
153 · host
154
155 Useful if your provider uses different hosts for accessing
156 different accounts. The default is specified in the provider
157 configuration.
158
159 $url->host($host);
160
161 · authorize_query
162
163 Either a hash-ref or an array-ref which can be used to give extra
164 query params to the URL.
165
166 $url->query($authorize_url);
167
168 · redirect_uri
169
170 Useful if you want to go back to a different page than what you
171 came from. The default is:
172
173 $c->url_for->to_abs->to_string
174
175 · scope
176
177 Scope to ask for credentials to. Should be a space separated list.
178
179 · state
180
181 A string that will be sent to the identity provider. When the user
182 returns from the identity provider, this exact same string will be
183 carried with the user, as a GET parameter called "state" in the URL
184 that the user will return to.
185
186 oauth2.get_token
187 $data = $c->oauth2->get_token($provider_name => \%args);
188 $c = $c->oauth2->get_token($provider_name => \%args, sub {
189 my ($c, $err, $data) = @_;
190 # do stuff with $data->{access_token} if it exists.
191 });
192
193 "oauth2.get_token" is used to either fetch access token from OAuth2
194 provider, handle errors or redirect to OAuth2 provider. This method can
195 be called in either blocking or non-blocking mode. $err holds a error
196 description if something went wrong. Blocking mode will "die($err)"
197 instead of returning it to caller. $data is a hash-ref containing the
198 access token from the OAauth2 provider. $data in blocking mode can
199 also be "undef" if a redirect has been issued by this module.
200
201 In more detail, this method will do one of two things:
202
203 1. If called from an action on your site, it will redirect you to the
204 $provider_name's "authorize_url". This site will probably have some
205 sort of "Connect" and "Reject" button, allowing the visitor to
206 either connect your site with his/her profile on the OAuth2
207 provider's page or not.
208
209 2. The OAuth2 provider will redirect the user back to your site after
210 clicking the "Connect" or "Reject" button. $data will then contain
211 a key "access_token" on "Connect" and a false value (or die in
212 blocking mode) on "Reject".
213
214 The method takes these arguments: $provider_name need to match on of
215 the provider names under "Configuration" or a custom provider defined
216 when registering the plugin.
217
218 %args can have:
219
220 · host
221
222 Useful if your provider uses different hosts for accessing
223 different accounts. The default is specified in the provider
224 configuration.
225
226 · redirect
227
228 Set "redirect" to 0 to disable automatic redirect.
229
230 · scope
231
232 Scope to ask for credentials to. Should be a space separated list.
233
234 oauth2.get_token_p
235 $promise = $c->oauth2->get_token_p($provider_name => \%args);
236
237 Same as "oauth2.get_token", but returns a Mojo::Promise. See "SYNOPSIS"
238 for example usage.
239
240 oauth2.providers
241 This helper allow you to access the raw providers mapping, which looks
242 something like this:
243
244 {
245 facebook => {
246 authorize_url => "https://graph.facebook.com/oauth/authorize",
247 token_url => "https://graph.facebook.com/oauth/access_token",
248 key => ...,
249 secret => ...,
250 },
251 ...
252 }
253
255 providers
256 Holds a hash of provider information. See oauth2.providers.
257
259 register
260 Will register this plugin in your application. See "SYNOPSIS".
261
263 Marcus Ramberg - "mramberg@cpan.org"
264
265 Jan Henning Thorsen - "jhthorsen@cpan.org"
266
268 This software is licensed under the same terms as Perl itself.
269
270
271
272perl v5.28.1 2018-09-24 Mojolicious::Plugin::OAuth2(3)