Mojolicious::Plugin::OAuth2(3pm)

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

NAME

6       Mojolicious::Plugin::OAuth2 - Auth against OAuth2 APIs including OpenID
7       Connect
8

SYNOPSIS

10   Example application
11         use Mojolicious::Lite;
12
13         plugin OAuth2 => {
14           providers => {
15             facebook => {
16               key    => 'some-public-app-id',
17               secret => $ENV{OAUTH2_FACEBOOK_SECRET},
18             },
19           },
20         };
21
22         get '/connect' => sub {
23           my $c         = shift;
24           my %get_token = (redirect_uri => $c->url_for('connect')->userinfo(undef)->to_abs);
25
26           return $c->oauth2->get_token_p(facebook => \%get_token)->then(sub {
27             # Redirected to Facebook
28             return unless my $provider_res = shift;
29
30             # Token received
31             $c->session(token => $provider_res->{access_token});
32             $c->redirect_to('profile');
33           })->catch(sub {
34             $c->render('connect', error => shift);
35           });
36         };
37
38       See "register" for more details about the configuration this plugin
39       takes.
40
41   Testing
42       Code using this plugin can perform offline testing, using the "mocked"
43       provider:
44
45         $app->plugin(OAuth2 => {mocked => {key => 42}});
46         $app->routes->get('/profile' => sub {
47           my $c = shift;
48
49           state $mocked = $ENV{TEST_MOCKED} && 'mocked';
50           return $c->oauth2->get_token_p($mocked || 'facebook')->then(sub {
51             ...
52           });
53         });
54
55       See Mojolicious::Plugin::OAuth2::Mock for more details.
56
57   Connect button
58       You can add a "connect link" to your template using the
59       "oauth2.auth_url" helper. Example template:
60
61         Click here to log in:
62         <%= link_to 'Connect!', $c->oauth2->auth_url('facebook', scope => 'user_about_me email') %>
63

DESCRIPTION

65       This Mojolicious plugin allows you to easily authenticate against a
66       OAuth2 <http://oauth.net> or OpenID Connect
67       <https://openid.net/connect/> provider. It includes configurations for
68       a few popular providers, but you can add your own as well.
69
70       See "register" for a full list of bundled providers.
71
72       To support "OpenID Connect", the following optional modules must be
73       installed manually: Crypt::OpenSSL::Bignum, Crypt::OpenSSL::RSA and
74       Mojo::JWT.  The modules can be installed with App::cpanminus:
75
76         $ cpanm Crypt::OpenSSL::Bignum Crypt::OpenSSL::RSA Mojo::JWT
77

HELPERS

79   oauth2.auth_url
80         $url = $c->oauth2->auth_url($provider_name => \%args);
81
82       Returns a Mojo::URL object which contain the authorize URL. This is
83       useful if you want to add the authorize URL as a link to your webpage
84       instead of doing a redirect like "oauth2.get_token" does. %args is
85       optional, but can contain:
86
87       • host
88
89         Useful if your provider uses different hosts for accessing different
90         accounts.  The default is specified in the provider configuration.
91
92           $url->host($host);
93
94       • authorize_query
95
96         Either a hash-ref or an array-ref which can be used to give extra
97         query params to the URL.
98
99           $url->query($authorize_url);
100
101       • redirect_uri
102
103         Useful if you want to go back to a different page than what you came
104         from.  The default is:
105
106           $c->url_for->to_abs->to_string
107
108       • scope
109
110         Scope to ask for credentials to. Should be a space separated list.
111
112       • state
113
114         A string that will be sent to the identity provider. When the user
115         returns from the identity provider, this exact same string will be
116         carried with the user, as a GET parameter called "state" in the URL
117         that the user will return to.
118
119   oauth2.get_refresh_token_p
120         $promise = $c->oauth2->get_refresh_token_p($provider_name => \%args);
121
122       When Mojolicious::Plugin::OAuth2 is being used in OpenID Connect mode
123       this helper allows for a token to be refreshed by specifying a
124       "refresh_token" in %args. Usage is similar to "oauth2.get_token_p".
125
126   oauth2.get_token_p
127         $promise = $c->oauth2->get_token_p($provider_name => \%args)
128                      ->then(sub { my $provider_res = shift })
129                      ->catch(sub { my $err = shift; });
130
131       "oauth2.get_token_p" is used to either fetch an access token from an
132       OAuth2 provider, handle errors or redirect to OAuth2 provider.  $err in
133       the rejection handler holds a error description if something went
134       wrong.  $provider_res is a hash-ref containing the access token from
135       the OAauth2 provider or "undef" if this plugin performed a 302 redirect
136       to the provider's connect website.
137
138       In more detail, this method will do one of two things:
139
140       1.
141         When called from an action on your site, it will redirect you to the
142         provider's "authorize_url". This site will probably have some sort of
143         "Connect" and "Reject" button, allowing the visitor to either connect
144         your site with his/her profile on the OAuth2 provider's page or not.
145
146       2.
147         The OAuth2 provider will redirect the user back to your site after
148         clicking the "Connect" or "Reject" button. $provider_res will then
149         contain a key "access_token" on "Connect" and a false value on
150         "Reject".
151
152       The method takes these arguments: $provider_name need to match on of
153       the provider names under "Configuration" or a custom provider defined
154       when registering the plugin.
155
156       %args can have:
157
158       • host
159
160         Useful if your provider uses different hosts for accessing different
161         accounts.  The default is specified in the provider configuration.
162
163       • redirect
164
165         Set "redirect" to 0 to disable automatic redirect.
166
167       • scope
168
169         Scope to ask for credentials to. Should be a space separated list.
170
171   oauth2.jwt_decode
172         $claims = $c->oauth2->jwt_decode($provider, sub { my $jwt = shift; ... });
173         $claims = $c->oauth2->jwt_decode($provider);
174
175       When Mojolicious::Plugin::OAuth2 is being used in OpenID Connect mode
176       this helper allows you to decode the response data encoded with the
177       JWKS discovered from "well_known_url" configuration.
178
179   oauth2.logout_url
180         $url = $c->oauth2->logout_url($provider_name => \%args);
181
182       When Mojolicious::Plugin::OAuth2 is being used in OpenID Connect mode
183       this helper creates the url to redirect to end the session. The OpenID
184       Connect Provider will redirect to the "post_logout_redirect_uri"
185       provided in %args.  Additional keys for %args are "id_token_hint" and
186       "state".
187
188   oauth2.providers
189         $hash_ref = $c->oauth2->providers;
190
191       This helper allow you to access the raw providers mapping, which looks
192       something like this:
193
194         {
195           facebook => {
196             authorize_url => "https://graph.facebook.com/oauth/authorize",
197             token_url     => "https://graph.facebook.com/oauth/access_token",
198             key           => ...,
199             secret        => ...,
200           },
201           ...
202         }
203

ATTRIBUTES

205   providers
206         $hash_ref = $oauth2->providers;
207
208       Holds a hash of provider information. See "oauth2.providers".
209

METHODS

211   register
212         $app->plugin(OAuth2 => \%provider_config);
213         $app->plugin(OAuth2 => {providers => \%provider_config, proxy => 1, ua => Mojo::UserAgent->new});
214
215       Will register this plugin in your application with a given
216       %provider_config.  The keys in %provider_config are provider names and
217       the values are configuration for each provider. Note that the value
218       will be merged with the predefined providers below.
219
220       Instead of just passing in %provider_config, it is possible to pass in
221       a more complex config, with these keys:
222
223       • providers
224
225         The %provider_config must be present under this key.
226
227       • proxy
228
229         Setting this to a true value will automatically detect proxy settings
230         using "detect" in Mojo::UserAgent::Proxy.
231
232       • ua
233
234         A custom Mojo::UserAgent, in case you want to change proxy settings,
235         timeouts or other attributes.
236
237       Instead of just passing in %provider_config, it is possible to pass in
238       a hash-ref "providers" (%provider_config) and "ua" (a custom
239       Mojo::UserAgent object).
240
241       Here is an example to add adddition information like "key" and
242       "secret":
243
244         $app->plugin(OAuth2 => {
245           providers => {
246             custom_provider => {
247               key           => 'APP_ID',
248               secret        => 'SECRET_KEY',
249               authorize_url => 'https://provider.example.com/auth',
250               token_url     => 'https://provider.example.com/token',
251             },
252             github => {
253               key    => 'APP_ID',
254               secret => 'SECRET_KEY',
255             },
256           },
257         });
258
259       For OpenID Connect <https://openid.net/connect/>, "authorize_url" and
260       "token_url" are configured from the "well_known_url" so these are
261       replaced by the "well_known_url" key.
262
263         $app->plugin(OAuth2 => {
264           providers => {
265             azure_ad => {
266               key            => 'APP_ID',
267               secret         => 'SECRET_KEY',
268               well_known_url => 'https://login.microsoftonline.com/tenant-id/v2.0/.well-known/openid-configuration',
269             },
270           },
271         });
272
273       To make it a bit easier the are already some predefined providers
274       bundled with this plugin:
275
276       dailymotion
277
278       Authentication for <https://www.dailymotion.com/> video site.
279
280       debian_salsa
281
282       Authentication for <https://salsa.debian.org/>.
283
284       eventbrite
285
286       Authentication for <https://www.eventbrite.com> event site.
287
288       See also <http://developer.eventbrite.com/docs/auth/>.
289
290       facebook
291
292       OAuth2 for Facebook's graph API, <http://graph.facebook.com/>. You can
293       find "key" (App ID) and "secret" (App Secret) from the app dashboard
294       here: <https://developers.facebook.com/apps>.
295
296       See also
297       <https://developers.facebook.com/docs/reference/dialogs/oauth/>.
298
299       instagram
300
301       OAuth2 for Instagram API. You can find "key" (Client ID) and "secret"
302       (Client Secret) from the app dashboard here:
303       <https://www.instagram.com/developer/clients/manage/>.
304
305       See also <https://www.instagram.com/developer/authentication/>.
306
307       github
308
309       Authentication with Github.
310
311       See also <https://developer.github.com/v3/oauth/>.
312
313       google
314
315       OAuth2 for Google. You can find the "key" (CLIENT ID) and "secret"
316       (CLIENT SECRET) from the app console here under "APIs & Auth" and
317       "Credentials" in the menu at
318       <https://console.developers.google.com/project>.
319
320       See also <https://developers.google.com/+/quickstart/>.
321
322       vkontakte
323
324       OAuth2 for Vkontakte. You can find "key" (App ID) and "secret" (Secure
325       key) from the app dashboard here: <https://vk.com/apps?act=manage>.
326
327       See also <https://vk.com/dev/authcode_flow_user>.
328

AUTHOR

330       Marcus Ramberg - "mramberg@cpan.org"
331
332       Jan Henning Thorsen - "jhthorsen@cpan.org"
333

LICENSE

335       This software is licensed under the same terms as Perl itself.
336