/ 
Dancer-Plugin-Auth-Facebook-0.08
River stage zero No dependents
/ Dancer::Plugin::Auth::Facebook

NAME

Dancer::Plugin::Auth::Facebook - Authenticate with Facebook OAuth

SYNOPSIS

package plugin::test;
use Dancer ':syntax';
use Dancer::Plugin::Auth::Facebook;

auth_fb_init();

hook before =>  sub {
  #we don't want a redirect loop here.
  return if request->path =~ m{/auth/facebook/callback};
  if (not session('fb_user')) {
     redirect auth_fb_authenticate_url;
  }
};

get '/' => sub {
  "welcome, " . session('fb_user')->{name};
};

get '/fail' => sub { "FAIL" };

true;

CONCEPT

This plugin provides a simple way to authenticate your users through Facebook's OAuth API. It provides you with a helper to build easily a redirect to the authentication URL, defines automatically a callback route handler and saves the authenticated user to your session when done.

The authenticated user information will be available as a hash reference under session('fb_user'). You should probably associate the id field to that user, so you know which of your users just completed the login.

The information under fb_user is returned by the current user's basic endpoint, known on Facebook's API as /me. You should note that Facebook has a habit of changing which fields are returned on that endpoint. To force any particular fields, please use the fields setting in your plugin configuration as shown below.

Please refer to Facebook's documentation for all available data.

FACEBOOK GRAPH API VERSION

This module complies to Facebook Graph API version 4.0, the latest at the time of publication, scheduled for deprecation on August 3rd, 2021.

One month prior to that, Net::Facebook::Oauth2 (which this module uses to access Facebook's API) will trigger a warning message during your Dancer app's startup.

If you want, you may override the default version by setting the api_version variable in your settings. This sets the Graph API version in both this module and the underlying Net::Facebook::Oauth2 objects. The default value is "v4.0".

PREREQUISITES

In order for this plugin to work, you need the following:

  • Facebook application

    Anyone can register a application at https://developers.facebook.com/. When done, make sure to configure the application as a Web application.

  • Configuration

    You need to configure the plugin first: copy your application_id and application_secret (provided by Facebook) to your Dancer's configuration under plugins/Auth::Facebook:

    # config.yml
...
plugins:
    'Auth::Facebook':
        application_id:     "1234"
        application_secret: "abcd"
        callback_url:       "http://localhost:3000/auth/facebook/callback"
        callback_success:   "/"
        callback_fail:      "/fail"
        scope:              "email friends"
        fields:             "id,name,email"

    callback_success , callback_fail, scope and fields are optional and default to '/' , '/fail', 'email' and (empty) respectively.

    Note that you also need to provide your callback url, whose route handler is automatically created by the plugin.

  • Session backend

    For the authentication process to work, you need a session backend, in order for the plugin to store the authenticated user's information.

    Use the session backend of your choice, it doesn't make a difference, see Dancer::Session for details about supported session engines, or search the CPAN for new ones.

EXPORT

The plugin exports the following symbols to your application's namespace:

facebook

The plugin uses a Net::Facebook::Oauth2 object to do its job. You can access this object with the facebook symbol, exported by the plugin.

auth_fb_init

This function should be called before your route handlers, in order to initialize the underlying Net::Facebook::Oauth2 object. It will read your configuration and create a new Net::Facebook::Oauth2 instance.

auth_fb_authenticate_url

this function returns an authentication URL for redirecting unauthenticated users.

hook before => sub { # we don't want a redirect loop here. return if request->path =~ m{/auth/facebook/callback}; if (not session('fb_user')) { redirect auth_fb_authenticate_url(); } };

ROUTE HANDLERS

The plugin defines the following route handler automatically

/auth/facebook/callback

This route handler is responsible for catching back a user that has just authenticated herself with Facebook's OAuth. The route handler saves tokens and user information such as email,username and name in the session and then redirects the user to the URI specified by callback_success.

If the validation of the token returned by Facebook failed or was denied, the user will be redirect to the URI specified by callback_fail.

ACKNOWLEDGEMENTS

This project is a port of Dancer::Plugin::Auth::Twitter written by Alexis Sukrieh which itself is a port of Catalyst::Authentication::Credential::Twitter written by Jesse Stay.

AUTHORS

  • Prajith Ndimensionz <prajith@ndimensionz>

COPYRIGHT AND LICENSE

This software is copyright (c) 2014-2019 by Prajith Ndimensionz.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.