NAME

Plack::Middleware::DoormanTwitter - The OAuth-based Twitter login middleware.

SYNOPSIS

    use Plack::Builder;

    builder {
        enable "Session::Cookie";
        enable "DoormanTwitter", root_url => 'http://localhost:5000', scope => 'users',
            consumer_key    => "XXXX",
            consumer_secret => "YYYY";

        # The app code.
        sub {
            my $env = shift;

            # Retrive the Plack::Middleware::DoormanTwitter object
            my $doorman = $env->{'doorman.users.twitter'};
            my @out;

            # Check sign-in status, and provide sign-out link or sign-in link in the output.
            if ($doorman->is_sign_in) {
                push @out, qq{Hi, @{[ $doorman->twitter_screen_name ]}, <a href="@{[ $doorman->sign_out_path ]}">Logout</a>}
            }
            else {
                push @out, qq{ <a href="@{[ $doorman->sign_in_path ]}">Login</a>}
            }

            ...
        }
    };

DESCRIPTION

This middleware module implements the OAuth Twitter login flow depicted here: http://dev.twitter.com/pages/sign_in_with_twitter.

Before you use it, you need to register your application at http://dev.twitter.com/ in order to get the consumer key and secret. Also, this middleware requires you to specify `callback url` of your app to be, for example, the root url of you application. Basically in need something other then blank string or "oob".

Second, the middleware requires you to specify the root URL in the app builder in order to properly build the real callback URL and many other URLs as the parameter for api.twitter.com.

Third, you need to name your authentication scope like "users". This may sound awkward and unnecessary but it allows the flexibility to allow multiple set of login. For example, you app can have a "users" scope for whoever sign-in from from twitter, and a "admin" scope from password-based authentication.

Last, and the most important, you need to enable "Session" middleware. The implementation requires Plack::Middleware::Session and stores relevant authentication information under $env-{psgi.session}{doorman.${scope}.twitter}>, where $scope is the scope name given by you. You may inspect this variable at runtime to get the basic idea of how the middleware stores relevant information.

After that, you can invoke several methods listed down below on the object stored in $env-{'doorman.users.twitter'}>, which is of this <Plack::Middleware::DoormanTwitter> class.

METHODS

• is_sign_in

  Return true if the current session is considered signed in.

• twitter_screen_name

  Return the twitter screen name of the authenticated user.

• twitter_access

  Returns a hash reference with keys: "access_token" and "access_token_secret", which is the token you can use to act as the current authenticated twitter user.

  If the user did not authorize your request yet, this method returns undef.

• twitter

  Returns a Net::Twitter::Lite object that you can use to perform api calls, like posting a new status update.