NAME

Catalyst::Authentication::Credential::Facebook::OAuth2 - Authenticate your Catalyst application's users using Facebook's OAuth 2.0

SYNOPSIS

package MyApp;

__PACKAGE__->config(
    'Plugin::Authentication' => {
        default => {
            credential => {
                class              => 'Facebook::OAuth2',
                application_id     => $app_id,
                application_secret => $app_secret,
            },
            store => { ... },
        },
    },
);

...

package MyApp::Controller::Foo;

sub some_action : Local {
    my ($self, $ctx) = @_;

    my $user = $ctx->authenticate({
        scope => ['offline_access', 'publish_stream'],
    });

    # ->authenticate set up a response that'll redirect to Facebook.
    #
    # Wait for the user to tell Facebook to authorise our application
    # by aborting our own request processing with ->detach and simply
    # sending the redirect.
    #
    # Once the user confirmed access for our application, Facebook will
    # redirect back to the URL of this action and ->authenticate will
    # return a valid user retrieved from the user store using the token
    # received from Facebook.
    $ctx->detach unless $user;

    ... # use your $user object (or $ctx->user, or whatever)
}

ATTRIBUTES

application_id

Your application's API key as retrieved from http://www.facebook.com/developers/.

application_secret

Your application's secret key as retrieved from http://www.facebook.com/developers/.

oauth_args

An array reference of additional options to pass to Facebook::Graph's constructor.

METHODS

authenticate

my $user = $ctx->authenticate({
    scope => ['offline_access', 'publish_stream'],
});

Attempts to authenticate a user by using Facebook's OAuth 2.0 interface. This works by generating an HTTP response that will redirect the user to a page on http://facebook.com that will ask the user to confirm our request to authenticate him. Once that has happened, Facebook will redirect back to use and authenticate will return a user instance.

Note how this is different from most other Catalyst authentication credentials. Successful authentication requires two requests to the Catalyst application - one is initiated by the user, the second one is caused by Facebook redirecting the user back to the application.

Because of that, special care has to be taken. If authenticate returns a false value, that means it set up the appropriate redirect response in $ctx->response. authenticate's caller should not manipulate with that response, but finish his request processing and send the response to the user, for example by doing $ctx->detach.

After being redirected back to from Facebook, authenticate will use the authentication code Facebook sent back to retrieve an access token from Facebook. This token will be used to look up a user instance from the authentication realm's store. That user, or undef if none has been found, will be returned.

If you're only interested in the access token, you might want to use Catalyst::Authentication::Store::Null as an authentication store and introspect the token attribute of the return user instance before logging the user out again immediately using $ctx->logout. You can then later use the access token you got to communicate with Facebook on behalf of the user that granted you access.

If access token retrieval fails, an exception will be thrown.

The scope key in the auth info hash reference passed as the first argument to authenticate will be passed along to Facebook::Graph::Authorize's extend_permissions method.

ACKNOWLEDGEMENTS

Thanks Reask Limited for funding the development of this module.

Thanks Shutterstock for funding bugfixing of and enhancements to this module.

AUTHOR

Florian Ragwitz <rafl@debian.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2011 by Florian Ragwitz, Reask Limited.

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