1Mojolicious::Plugin::OAUustehr2(C3o)ntributed Perl DocumMeonjtoaltiicoinous::Plugin::OAuth2(3)
2
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 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 $ mojo version
18 References
20 • <http://oauth.net/documentation/>
21 • <http://aaronparecki.com/articles/2012/07/29/1/oauth2-simplified>
23 • <http://homakov.blogspot.jp/2013/03/oauth1-oauth2-oauth.html>
25 • <http://en.wikipedia.org/wiki/OAuth#OAuth_2.0>
27
29 Example non-blocking application
30 use Mojolicious::Lite;
31 plugin "OAuth2" => {
33 facebook => {
34 key => "some-public-app-id",
35 secret => $ENV{OAUTH2_FACEBOOK_SECRET},
36 },
37 };
38 get "/connect" => sub {
40 my $c = shift;
41 my $get_token_args = {redirect_uri => $c->url_for("connect")->userinfo(undef)->to_abs};
42 $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 Custom connect button
53 You can add a "connect link" to your template using the
54 "oauth2.auth_url" helper. Example template:
55 Click here to log in:
57 <%= link_to "Connect!", $c->oauth2->auth_url("facebook", scope => "user_about_me email") %>
58 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 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 To make it a bit easier, Mojolicious::Plugin::OAuth2 has already values
74 for "authorize_url" and "token_url" for the following providers:
75 • dailymotion
77 Authentication for Dailymotion video site.
79 • eventbrite
81 Authentication for <https://www.eventbrite.com> event site.
83 See also <http://developer.eventbrite.com/docs/auth/>.
85 • facebook
87 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 See also
93 <https://developers.facebook.com/docs/reference/dialogs/oauth/>.
94 = item * instagram
96 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 See also <https://www.instagram.com/developer/authentication/>.
102 • github
104 Authentication with Github.
106 See also <https://developer.github.com/v3/oauth/>.
108 • google
110 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 See also <https://developers.google.com/+/quickstart/>.
117 = item * vkontakte
119 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 See also <https://vk.com/dev/authcode_flow_user>.
125 Testing
127 THIS API IS EXPERIMENTAL AND CAN CHANGE WITHOUT NOTICE.
128 To enable a "mocked" OAuth2 api, you need to give the special "mocked"
130 provider a "key":
131 plugin "OAuth2" => { mocked => {key => 42} };
133 The code above will add two new routes to your application:
135 • GET /mocked/oauth/authorize
137 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 $c->app->oauth2->providers->{mocked}{return_code} = "...";
143 The route it self can also be customized:
145 plugin "OAuth2" => { mocked => {authorize_url => '...'} };
147 • POST /mocked/oauth/token
149 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 $c->app->oauth2->providers->{mocked}{return_token} = "...";
155 The route it self can also be customized:
157 plugin "OAuth2" => { mocked => {token_url => '...'} };
159
161 oauth2.auth_url
162 $url = $c->oauth2->auth_url($provider => \%args);
163 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 • host
170 Useful if your provider uses different hosts for accessing
172 different accounts. The default is specified in the provider
173 configuration.
174 $url->host($host);
176 • authorize_query
178 Either a hash-ref or an array-ref which can be used to give extra
180 query params to the URL.
181 $url->query($authorize_url);
183 • redirect_uri
185 Useful if you want to go back to a different page than what you
187 came from. The default is:
188 $c->url_for->to_abs->to_string
190 • scope
192 Scope to ask for credentials to. Should be a space separated list.
194 • state
196 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 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 "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 In more detail, this method will do one of two things:
218 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 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 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 %args can have:
235 • host
237 Useful if your provider uses different hosts for accessing
239 different accounts. The default is specified in the provider
240 configuration.
241 • redirect
243 Set "redirect" to 0 to disable automatic redirect.
245 • scope
247 Scope to ask for credentials to. Should be a space separated list.
249 oauth2.get_token_p
251 $promise = $c->oauth2->get_token_p($provider_name => \%args);
252 Same as "oauth2.get_token", but returns a Mojo::Promise. See "SYNOPSIS"
254 for example usage.
255 oauth2.providers
257 This helper allow you to access the raw providers mapping, which looks
258 something like this:
259 {
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
271 providers
272 Holds a hash of provider information. See "oauth2.providers".
273
275 register
276 Will register this plugin in your application. See "SYNOPSIS".
277
279 Marcus Ramberg - "mramberg@cpan.org"
280 Jan Henning Thorsen - "jhthorsen@cpan.org"
282
284 This software is licensed under the same terms as Perl itself.
285perl v5.32.1 2021-01-27 Mojolicious::Plugin::OAuth2(3)