view release on metacpan or  search on metacpan

lib/Dancer/Plugin/Auth/Facebook.pm  view on Meta::CPAN

  };
  if ($@ || !$me) {
     error "error fetching facebook user: '$@' on response '$fb_response'";
     return redirect $cb_fail;
  }
  else {
    session fb_user => $me;
    return redirect $cb_success;
  }
};

register_plugin;

1;

__END__

=pod

=head1 NAME

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

=head1 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;
    

=head1 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
C<session('fb_user')>. You should probably associate the C<id> field to that
user, so you know which of your users just completed the login.

The information under C<fb_user> is returned by the current user's basic
endpoint, known on Facebook's API as C</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 C<fields> setting in your plugin
configuration as shown below.

Please refer to L<< Facebook's documentation | https://developers.facebook.com/docs/graph-api/reference/v4.0/user >>
for all available data.

=head1 FACEBOOK GRAPH API VERSION

This module complies to Facebook Graph API version 4.0, the latest
at the time of publication, B<< 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 C<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".

=head1 PREREQUISITES

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

=over 4

=item * Facebook application

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

=item * Configuration

You need to configure the plugin first: copy your C<application_id> and C<application_secret>
(provided by Facebook) to your Dancer's configuration under
C<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"

C<callback_success> , C<callback_fail>, C<scope> and C<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.

=item * 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