Net::Facebook::Oauth2(3pm)

1Net::Facebook::Oauth2(3U)ser Contributed Perl DocumentatiNoent::Facebook::Oauth2(3)
2
3
4

NAME

6       Net::Facebook::Oauth2 - a simple Perl wrapper around Facebook OAuth 2.0
7       protocol
8

FACEBOOK GRAPH API VERSION

10       This module complies to Facebook Graph API version 4.0, the latest at
11       the time of publication, scheduled for deprecation not sooner than
12       August 3rd, 2021.
13

SYNOPSIS

15       Somewhere in your application's login process:
16
17           use Net::Facebook::Oauth2;
18
19           my $fb = Net::Facebook::Oauth2->new(
20               application_id     => 'your_application_id',
21               application_secret => 'your_application_secret',
22               callback           => 'http://yourdomain.com/facebook/callback'
23           );
24
25           # get the authorization URL for your application
26           my $url = $fb->get_authorization_url(
27               scope   => [ 'email' ],
28               display => 'page'
29           );
30
31       Now redirect the user to this $url.
32
33       Once the user authorizes your application, Facebook will send him/her
34       back to your application, on the "callback" link provided above. PLEASE
35       NOTE THAT YOU MUST PRE-AUTHORIZE YOUR CALLBACK URI ON FACEBOOK'S APP
36       DASHBOARD.
37
38       Inside that callback route, use the verifier code parameter that
39       Facebook sends to get the access token:
40
41           # param() below is a bogus function. Use whatever your web framework
42           # provides (e.g. $c->req->param('code'), $cgi->param('code'), etc)
43           my $code = param('code');
44
45           use Try::Tiny;  # or eval {}, or whatever
46
47           my ($unique_id, $access_token);
48           try {
49               $access_token = $fb->get_access_token(code => $code); # <-- could die!
50
51               # Facebook tokens last ~2h, but you may upgrade them to ~60d if you want:
52               $access_token = $fb->get_long_lived_token( access_token => $access_token );
53
54               my $access_data = $fb->debug_token( input => $access_token );
55               if ($access_data && $access_data->{is_valid}) {
56                   $unique_id = $access_data->{user_id};
57                   # you could also check here for what scopes were granted to you
58                   # by inspecting $access_data->{scopes}->@*
59               }
60           } catch {
61               # handle errors here!
62           };
63
64       If you got so far, your user is logged! Save the access token in your
65       database or session. As shown in the example above, Facebook also
66       provides a unique user_id for this token so you can associate it with a
67       particular user of your app.
68
69       Later on you can use that access token to communicate with Facebook on
70       behalf of this user:
71
72           my $fb = Net::Facebook::Oauth2->new(
73               access_token => $access_token
74           );
75
76           my $info = $fb->get(
77               'https://graph.facebook.com/v4.0/me'   # Facebook API URL
78           );
79
80           print $info->as_json;
81
82       NOTE: if you skipped the call to "debug_token()" you can still find the
83       unique user id value with a call to the 'me' endpoint shown above,
84       under "$info->{id}"
85

DESCRIPTION

87       Net::Facebook::Oauth2 gives you a way to simply access FaceBook Oauth
88       2.0 protocol.
89
90       The example folder contains some snippets you can look at, or for more
91       information just keep reading :)
92

USAGE

101   "Net::Facebook::Oauth->new( %args )"
102       Returns a new object to handle user authentication.  Pass arguments as
103       a hash. The following arguments are REQUIRED unless you're passing an
104       access_token (see optional arguments below):
105
106       •   "application_id"
107
108           Your application id as you get from facebook developers platform
109           when you register your application
110
111       •   "application_secret"
112
113           Your application secret id as you get from facebook developers
114           platform when you register your application
115
116       The following arguments are OPTIONAL:
117
118       •   "access_token"
119
120           If you want to instantiate an object to an existing access token,
121           you may do so by passing it to this argument.
122
123       •   "browser"
124
125           The user agent that will handle requests to Facebook's API.
126           Defaults to LWP::UserAgent, but can be any method that implements
127           the methods "get", "post" and "delete" and whose response to such
128           methods implements "is_success" and "content".
129
130       •   "display"
131
132           See "display" under the "get_authorization_url" method below.
133
134       •   "api_version"
135
136           Use this to replace the API version on all endpoints. The default
137           value is 'v4.0'. Note that defining an api_version parameter
138           together with "authorize_url", "access_token_url" or
139           "debug_token_url" is a fatal error.
140
141       •   "authorize_url"
142
143           Overrides the default (4.0) API endpoint for Facebook's oauth.
144           Used mostly for testing new versions.
145
146       •   "access_token_url"
147
148           Overrides the default (4.0) API endpoint for Facebook's access
149           token.  Used mostly for testing new versions.
150
151       •   "debug_token_url"
152
153           Overrides the default (4.0) API endpoint for Facebook's token
154           information.  Used mostly for testing new versions.
155
156   "$fb->get_authorization_url( %args )"
157       Returns an authorization URL for your application. Once you receive
158       this URL, redirect your user there in order to authorize your
159       application.
160
161       The following argument is REQUIRED:
162
163       •   "callback"
164
165               callback => 'http://example.com/login/facebook/success'
166
167           The callback URL, where Facebook will send users after they
168           authorize your application. YOU MUST CONFIRM THIS URL ON FACEBOOK'S
169           APP DASHBOARD.
170
171           To do that, go to the App Dashboard, click Facebook Login in the
172           right-hand menu, and check the Valid OAuth redirect URIs in the
173           Client OAuth Settings section.
174
175       This method also accepts the following OPTIONAL arguments:
176
177       •   "scope"
178
179               scope => ['user_birthday','user_friends', ...]
180
181           Array of Extended permissions as described by the Facebook Oauth
182           API.  You can get more information about scope/Extended Permission
183           from
184
185           <https://developers.facebook.com/docs/facebook-login/permissions/>
186
187           Please note that requesting information other than "name", "email"
188           and "profile_picture" will require your app to be reviewed by
189           Facebook!
190
191       •   "state"
192
193               state => '123456abcde'
194
195           An arbitrary unique string provided by you to guard against Cross-
196           site Request Forgery. This value will be returned to you by
197           Facebook, unchanged. Note that, as of Facebook API v3.0, this
198           argument is mandatory, so if you don't provide a 'state' argument,
199           we will default to "time()".
200
201       •   "auth_type"
202
203           When a user declines a given permission, you must reauthorize them.
204           But when you do so, any previously declined permissions will not be
205           asked again by Facebook. Set this argument to 'rerequest' to
206           explicitly tell the dialog you're re-asking for a declined
207           permission.
208
209       •   "display"
210
211               display => 'page'
212
213           How to display Facebook Authorization page. Defaults to "page".
214           Can be any of the following:
215
216           •   "page"
217
218               This will display facebook authorization page as full page
219
220           •   "popup"
221
222               This option is useful if you want to popup authorization page
223               as this option tell facebook to reduce the size of the
224               authorization page
225
226           •   "wab"
227
228               From the name, for wab and mobile applications this option is
229               the best, as the facebook authorization page will fit there :)
230
231       •   "response_type"
232
233               response_type => 'code'
234
235           When the redirect back to the app occurs, determines whether the
236           response data is in URL parameters or fragments. Defaults to
237           "code", which is Facebook's default and useful for cases where the
238           server handles the token (which is most likely why you are using
239           this module), but can be also be "token", "code%20token", or
240           "granted_scopes". Note that changing this to anything other than
241           'code' might change the login flow described in this documentation,
242           rendering calls to "get_access_token()" pointless.  Please see
243           Facebook's login documentation
244           <https://developers.facebook.com/docs/facebook-login/manually-
245           build-a-login-flow> for more information.
246
247   "$fb->get_access_token( %args )"
248       This method issues a GET request to Facebook's API to retrieve the
249       access token string for the specified code (passed as an argument).
250
251       Returns the access token string or raises an exception in case of
252       errors (make sure to trap calls with eval blocks or a try/catch
253       module). Note that Facebook's access tokens are short-lived, around 2h
254       of idle time before expiring. If you want to "upgrade" the token to a
255       long lived one (with around 60 days of idle time), use this token to
256       feed the "get_long_lived_token()" method.
257
258       You should call this method inside the route for the callback URI
259       defined in the "get_authorization_url" method. It receives the
260       following arguments:
261
262       •   "code"
263
264           This is the verifier code that Facebook sends back to your callback
265           URL once user authorize your app, you need to capture this code and
266           pass to this method in order to get the access token.
267
268           Verifier code will be presented with your callback URL as code
269           parameter as the following:
270
271           http://your-call-back-url.com?code=234er7y6fdgjdssgfsd...
272
273           Note that if you have fiddled with the "response_type" argument,
274           you might not get this parameter properly.
275
276       When the access token is returned you need to save it in a secure place
277       in order to use it later in your application. The token indicates that
278       a user has authorized your site/app, meaning you can associate that
279       token to that user and issue API requests to Facebook on their behalf.
280
281       To know WHICH user has granted you the authorization (e.g. when
282       building a login system to associate that token with a unique user on
283       your database), you must make a request to fetch Facebook's own unique
284       identifier for that user, and then associate your own user's unique id
285       to Facebook's.
286
287       This was usually done by making a GET request to the "me" API endpoint
288       and looking for the 'id' field. However, Facebook has introduced a new
289       endpoint for that flow that returns the id (this time as 'user_id') and
290       some extra validation data, like whether the token is valid, to which
291       app it refers to, what scopes the user agreed to, etc, so now you are
292       encouraged to call the "debug_token()" method as shown in the SYNOPSIS.
293
294       IMPORTANT: Expect that the length of all access token types will change
295       over time as Facebook makes changes to what is stored in them and how
296       they are encoded. You can expect that they will grow and shrink over
297       time.  Please use a variable length data type without a specific
298       maximum size to store access tokens.
299
300   "$fb->get_long_lived_token( access_token => $access_token )"
301       Asks facebook to retrieve the long-lived (~60d) version of the provided
302       short-lived (~2h) access token retrieved from "get_access_token()". If
303       successful, this method will return the long-lived token, which you can
304       use to replace the short-lived one. Otherwise, it croaks with an error
305       message, in which case you can continue to use the short-lived version.
306
307       See here <https://developers.facebook.com/docs/facebook-login/access-
308       tokens/refreshing> for the gory details.
309
310   "$fb->debug_token( input => $access_token )"
311       This method should be called right after "get_access_token()". It will
312       query Facebook for details about the given access token and validate
313       that it was indeed granted to your app (and not someone else's).
314
315       It requires a single argument, "input", containing the access code
316       obtained from calling "get_access_token".
317
318       It croaks on HTTP/connection/Facebook errors, returns nothing if for
319       whatever reason the response is invalid without errors (e.g. no app_id
320       and no user_id), and also if the returned app_id is not the same as
321       your own application_id (pass a true value to "skip_check" to skip this
322       validation).
323
324       If all goes well, it returns a hashref with the JSON structure returned
325       by Facebook.
326
327   "$fb->get( $url, $args )"
328       Sends a GET request to Facebook and stores the response in the given
329       object.
330
331       •   "url"
332
333           Facebook Graph API URL as string. You must provide the full URL.
334
335       •   $args
336
337           hashref of parameters to be sent with graph API URL if required.
338
339       You can access the response using the following methods:
340
341       •   "$response>as_json"
342
343           Returns response as json object
344
345       •   "$response>as_hash"
346
347           Returns response as perl hashref
348
349       For more information about facebook graph API, please check
350       http://developers.facebook.com/docs/api
351
352   "$fb->post( $url, $args )"
353       Send a POST request to Facebook and stores the response in the given
354       object.  See the "as_hash" and "as_json" methods above for how to
355       retrieve the response.
356
357       •   "url"
358
359           Facebook Graph API URL as string
360
361       •   $args
362
363           hashref of parameters to be sent with graph API URL
364
365       For more information about facebook graph API, please check
366       <http://developers.facebook.com/docs/api>
367
368   "$fb->delete( $url, $args )"
369       Send a DELETE request to Facebook and stores the response in the given
370       object.  See the "as_hash" and "as_json" methods above for how to
371       retrieve the response.
372
373       •   "url"
374
375           Facebook Graph API URL as string
376
377       •   $args
378
379           hashref of parameters to be sent with graph API URL
380

AUTHOR

382       Mahmoud A. Mehyar, <mamod.mehyar@gmail.com>
383

CONTRIBUTORS

385       Big Thanks To
386
387       •   Takatsugu Shigeta @comewalk <https://github.com/comewalk>
388
389       •   Breno G. de Oliveira @garu <https://github.com/garu>
390
391       •   squinker @squinker <https://github.com/squinker>
392
393       •   Valcho Nedelchev @valchonedelchev
394           <https://github.com/valchonedelchev>
395

COPYRIGHT AND LICENSE

397       Copyright (C) 2012-2019 by Mahmoud A. Mehyar
398
399       This library is free software; you can redistribute it and/or modify it
400       under the same terms as Perl itself, either Perl version 5.10.1 or, at
401       your option, any later version of Perl 5 you may have available.
402
403
404
405perl v5.32.1                      2021-01-27          Net::Facebook::Oauth2(3)