NAME

Dancer::Plugin::Auth::Twitter - Authenticate with Twitter

VERSION

version 0.07

SYNOPSIS

    package SomeDancerApp;
    use Dancer ':syntax';
    use Dancer::Plugin::Auth::Twitter;

    auth_twitter_init();

    before sub {
        if (not session('twitter_user')) {
            redirect auth_twitter_authenticate_url;
        }
    };

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

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

    ...

CONCEPT

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

PREREQUESITES

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

• Twitter application

  Anyone can register a Twitter application at http://developer.twitter.com/. When done, make sure to configure the application as a Web application.

• Configuration

  You need to configure the plugin first: copy your consumer_key and consumer_secret (provided by Twitter) to your Dancer's configuration under plugins/Auth::Twitter:

      # config.yml
      ...
      plugins:
        "Auth::Twitter":
          consumer_key:     "insert your comsumer key here"
          consumer_secret:  "insert your consumer secret here"
          callback_url:     "http://localhost:3000/auth/twitter/callback"
          callback_success: "/"
          callback_fail:    "/fail"

  callback_url is the URL in your app that Twitter will call after authentication. Unless you really know what you're doing, it should always be your app url + /auth/twitter/callback, like the example above. This route is implemented by this plugin to properly handle the necessary OAuth final steps and log your user.

  callback_success and callback_fail are optional and default to '/' and '/fail', respectively. Once the callback_url processes the authentication/authorization returned by Twitter, it will redirect the user to those routes.

  Before version 0.08, this module allowed the use of either Net::Twitter or Net::Twitter::Lite as backend engines. Those modules have been merged into the modern and up to date Twitter::API, by the same author. Because Twitter no longer supports the methods used in those modules, this plugin was updated to use Twitter::API as well.

• 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.

  However, please note that the user access token will be stored on the session, and that token may be used to query extra information from Twitter on behalf of your users! As such, please keep your user's privacy in mind and encrypt+secure your session data.

EXPORT

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

twitter

The plugin uses a Twitter::API object to do its job. You can access this object with the twitter symbol, exported by the plugin.

auth_twitter_init

This function should be called before your route handlers, in order to initialize the underlying Twitter::API object.

auth_twitter_authorize_url

This function returns an authorization URI to redirect unauthenticated users. You should use this in a before filter like the following:

    before sub {
        # we don't want to bounce for ever!
        return if request->path =~ m{/auth/twitter/callback};
    
        if (not session('twitter_user')) {
            redirect auth_twitter_authorize_url();
        }
    };

When the user authenticates with Twitter's OAuth interface, she's going to be bounced back to /auth/twitter/callback.

auth_twitter_authenticate_url

Similar to auth_twitter_authorize_url, but this function instead returns an authenticate instead of authorize URI for redirecting unauthenticated users, which results in a slightly different behaviour.

See https://dev.twitter.com/pages/sign_in_with_twitter|here to learn about the differences.

ROUTE HANDLERS

The plugin defines the following route handler automatically

/auth/twitter/callback

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

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

TIPS AND TRICKS

You should probably wrap your calls to auth_twitter_authorize_url and auth_twitter_authenticate_url under eval, as they make requests to the Twitter API and may fail.

ACKNOWLEDGEMENTS

This plugin has been written as a port of Catalyst::Authentication::Credential::Twitter written by Jesse Stay.

This plugin was part of the Perl Dancer Advent Calendar 2010.

AUTHORS

• Alexis Sukrieh <sukria@sukria.net>

• Dancer Core Developers

COPYRIGHT AND LICENSE

This software is copyright (c) 2010-18 by Alexis Sukrieh.

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

cpanm Dancer::Plugin::Auth::Twitter

perl -MCPAN -e shell
install Dancer::Plugin::Auth::Twitter