1Mojolicious::Plugin::OAUustehr2(C3o)ntributed Perl DocumMeonjtoaltiicoinous::Plugin::OAuth2(3)
2
3
4

NAME

6       Mojolicious::Plugin::OAuth2 - Auth against OAuth2 APIs
7

DESCRIPTION

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

SYNOPSIS

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           = item * instagram
96
97           OAuth2 for Instagram API. You can find "key" (Client ID) and
98           "secret" (Client Secret) from the app dashboard here:
99           <https://www.instagram.com/developer/clients/manage/>.
100
101           See also <https://www.instagram.com/developer/authentication/>.
102
103       ·   github
104
105           Authentication with Github.
106
107           See also <https://developer.github.com/v3/oauth/>.
108
109       ·   google
110
111           OAuth2 for Google. You can find the "key" (CLIENT ID) and "secret"
112           (CLIENT SECRET) from the app console here under "APIs & Auth" and
113           "Credentials" in the menu at
114           <https://console.developers.google.com/project>.
115
116           See also <https://developers.google.com/+/quickstart/>.
117
118           = item * vkontakte
119
120           OAuth2 for Vkontakte. You can find "key" (App ID) and "secret"
121           (Secure key) from the app dashboard here:
122           <https://vk.com/apps?act=manage>.
123
124           See also <https://vk.com/dev/authcode_flow_user>.
125
126   Testing
127       THIS API IS EXPERIMENTAL AND CAN CHANGE WITHOUT NOTICE.
128
129       To enable a "mocked" OAuth2 api, you need to give the special "mocked"
130       provider a "key":
131
132         plugin "OAuth2" => { mocked => {key => 42} };
133
134       The code above will add two new routes to your application:
135
136       ·   GET /mocked/oauth/authorize
137
138           This route is a web page which contains a link that takes you back
139           to "redirect_uri", with a "code". The "code" default to
140           "fake_code", but can be configured:
141
142             $c->app->oauth2->providers->{mocked}{return_code} = "...";
143
144           The route it self can also be customized:
145
146             plugin "OAuth2" => { mocked => {authorize_url => '...'} };
147
148       ·   POST /mocked/oauth/token
149
150           This route is will return a "access_token" which is available in
151           your "oauth2.get_token" callback. The default is "fake_token", but
152           it can be configured:
153
154             $c->app->oauth2->providers->{mocked}{return_token} = "...";
155
156           The route it self can also be customized:
157
158             plugin "OAuth2" => { mocked => {token_url => '...'} };
159

HELPERS

161   oauth2.auth_url
162         $url = $c->oauth2->auth_url($provider => \%args);
163
164       Returns a Mojo::URL object which contain the authorize URL. This is
165       useful if you want to add the authorize URL as a link to your webpage
166       instead of doing a redirect like "oauth2.get_token" does. %args is
167       optional, but can contain:
168
169       ·   host
170
171           Useful if your provider uses different hosts for accessing
172           different accounts.  The default is specified in the provider
173           configuration.
174
175             $url->host($host);
176
177       ·   authorize_query
178
179           Either a hash-ref or an array-ref which can be used to give extra
180           query params to the URL.
181
182             $url->query($authorize_url);
183
184       ·   redirect_uri
185
186           Useful if you want to go back to a different page than what you
187           came from.  The default is:
188
189             $c->url_for->to_abs->to_string
190
191       ·   scope
192
193           Scope to ask for credentials to. Should be a space separated list.
194
195       ·   state
196
197           A string that will be sent to the identity provider. When the user
198           returns from the identity provider, this exact same string will be
199           carried with the user, as a GET parameter called "state" in the URL
200           that the user will return to.
201
202   oauth2.get_token
203         $data = $c->oauth2->get_token($provider_name => \%args);
204         $c    = $c->oauth2->get_token($provider_name => \%args, sub {
205                   my ($c, $err, $data) = @_;
206                   # do stuff with $data->{access_token} if it exists.
207                 });
208
209       "oauth2.get_token" is used to either fetch access token from OAuth2
210       provider, handle errors or redirect to OAuth2 provider. This method can
211       be called in either blocking or non-blocking mode. $err holds a error
212       description if something went wrong. Blocking mode will "die($err)"
213       instead of returning it to caller.  $data is a hash-ref containing the
214       access token from the OAauth2 provider.  $data in blocking mode can
215       also be "undef" if a redirect has been issued by this module.
216
217       In more detail, this method will do one of two things:
218
219       1.  If called from an action on your site, it will redirect you to the
220           $provider_name's "authorize_url". This site will probably have some
221           sort of "Connect" and "Reject" button, allowing the visitor to
222           either connect your site with his/her profile on the OAuth2
223           provider's page or not.
224
225       2.  The OAuth2 provider will redirect the user back to your site after
226           clicking the "Connect" or "Reject" button. $data will then contain
227           a key "access_token" on "Connect" and a false value (or die in
228           blocking mode) on "Reject".
229
230       The method takes these arguments: $provider_name need to match on of
231       the provider names under "Configuration" or a custom provider defined
232       when registering the plugin.
233
234       %args can have:
235
236       ·   host
237
238           Useful if your provider uses different hosts for accessing
239           different accounts.  The default is specified in the provider
240           configuration.
241
242       ·   redirect
243
244           Set "redirect" to 0 to disable automatic redirect.
245
246       ·   scope
247
248           Scope to ask for credentials to. Should be a space separated list.
249
250   oauth2.get_token_p
251         $promise = $c->oauth2->get_token_p($provider_name => \%args);
252
253       Same as "oauth2.get_token", but returns a Mojo::Promise. See "SYNOPSIS"
254       for example usage.
255
256   oauth2.providers
257       This helper allow you to access the raw providers mapping, which looks
258       something like this:
259
260         {
261           facebook => {
262             authorize_url => "https://graph.facebook.com/oauth/authorize",
263             token_url     => "https://graph.facebook.com/oauth/access_token",
264             key           => ...,
265             secret        => ...,
266           },
267           ...
268         }
269

ATTRIBUTES

271   providers
272       Holds a hash of provider information. See "oauth2.providers".
273

METHODS

275   register
276       Will register this plugin in your application. See "SYNOPSIS".
277

AUTHOR

279       Marcus Ramberg - "mramberg@cpan.org"
280
281       Jan Henning Thorsen - "jhthorsen@cpan.org"
282

LICENSE

284       This software is licensed under the same terms as Perl itself.
285
286
287
288perl v5.30.0                      2019-07-28    Mojolicious::Plugin::OAuth2(3)
Impressum