NAME

Plack::Middleware::OAuth - Plack middleware for OAuth1, OAuth2 and builtin provider configs.

DESCRIPTION

This module is still in **ALPHA VERSION** , DO NOT USE THIS FOR PRODUCTION!

Plack::Middleware::OAuth supports OAuth1 and OAuth2, and provides builtin configs for providers like Twitter, Github, Google, Facebook. The only one thing you need to mount your OAuth service is to setup your consumer_key, consumer_secret (OAuth1) or client_id, client_secret, scope (OAuth2).

Plack::Middleware::OAuth generates authorize url (mount_path/provider_id) and auththorize callback url (mount_path/provider_id/callback). If the authorize path matches, then user will be redirected to OAuth provider to authorize your application.

For example, if you mount Plack::Middleware::OAuth on /oauth, then you can access http://youdomain.com/oauth/twitter to authorize, Plack::Middleware::OAuth will redirect you to Twitter, after authorized, then Twitter will redirect you to your callback url http://youdomain.com/oauth/twitter/callback.

For more details, please check the example psgi in eg/ directory.

SYNOPSIS

        use Plack::Builder;

        builder {

        mount '/oauth' => builder {
            enable 'OAuth', 

                on_success => sub  { 
                    my ($self,$oauth_data) = @_;
                    my $env = $self->env;

                    return $self->render( '..html content..' );
                    return $self->redirect( .... URL ... );

                    return [  200 , [ 'Content-type' => 'text/html' ] , 'Signin!' ];


                },

                on_error => sub {  ...  },

                providers => {

                    # capital case implies Plack::Middleware::OAuth::Twitter
                    # authorize path: /oauth/twitter
                    # authorize callback path: /oauth/twitter/callback

                    'Twitter' =>
                    {
                        consumer_key      => ...
                        consumer_secret   => ...
                    },

                    # captical case implies Plack::Middleware::OAuth::Facebook
                    # authorize path: /oauth/facebook
                    # authorize callback path: /oauth/facebook/callback

                    'Facebook' =>
                    {
                        client_id        => ...
                        client_secret           => ...
                        scope            => 'email,read_stream',
                    },

                    'Github' => 
                    {
                        client_id => ...
                        client_secret => ...
                        scope => 'user,public_repo'
                    },

                    'Google' =>  { 
                        client_id     => '',
                        client_secret => '',
                        scope         => 'https://www.google.com/m8/feeds/'
                    },

                    # authorize path: /oauth/custom_provider
                    # authorize callback path: /oauth/custom_provider/callback
                    'custom_provider' => { 
                        version => 1,
                        ....
                    }
                        };
        };
                $app;
        };

The callback/redirect URL is set to {SCHEMA}://{HTTP_HOST}/{prefix}/{provider}/callback by default.

Sessions

You can get OAuth1 or OAuth2 access token from Session,

    my $session = Plack::Session->new( $env );
    $session->get( 'oauth.twitter.access_token' );
    $session->get( 'oauth.twitter.access_token_secret' );

    $session->get( 'oauth2.facebook.access_token' );
    $session->get( 'oauth2.custom_provider' );

Specify Success Callback

When access token is got, success handler will be called:

    enable 'OAuth', 
        providers => { .... },
        on_success => sub  { 
            my ($self,$oauth_data) = @_;

            # $self: Plack::Middleware::OAuth::Handler (isa Plack::Request) object

            return $self->render( .... );

            return $self->redirect( .... );

            return $self->to_yaml( .... );

            return $self->to_json( .... );

            # or just return a raw arrayref
            return [  200 , [ 'Content-type' => 'text/html' ] , 'Signin!' ];
        };

Without specifying on_success, OAuth middleware will use YAML to dump the response data to page.

Error Handler

An error handler should return a response data, it should be an array reference, for be finalized from Plack::Response:

    enable 'OAuth', 
        providers => { .... },
        on_error => sub {
            my ($self,$oauth_data) = @_;

            # $self: Plack::Middleware::OAuth::Handler (isa Plack::Request) object

        };

OAuth1 AccessToken Callback Data Structure

Twitter uses OAuth 1.0a, and the access token callback returns data like this:

    ---
    params:
        access_token: {{string}}
        access_token_secret: {{string}}
        extra_params:
            screen_name: {{screen name}}
            user_id: {{user id}}
    provider: Twitter
    version: 1

OAuth2 AccessToken Callback Data Structure

Github uses OAuth 2.0, and the access token callback returns data like this:

    ---
    params:
        code: {{string}}
        access_token: {{string}}
        token_type: bearer
    provider: Github
    version: 2

Google returns:

    ---
    params:
        access_token: {{string}}
        code: {{string}}
        expires_in: 3600
        refresh_token: {{string}}
        token_type: Bearer
    provider: Google
    version: 2

Supported Providers

• Google

• Twitter

• Facebook

• Github

See Also

Net::OAuth, Net::OAuth2

Reference

• OAuth Workflow http://hueniverse.com/oauth/guide/workflow/

• OAuth 2.0 Protocal Draft http://tools.ietf.org/html/draft-ietf-oauth-v2

• Github - Create A New Client https://github.com/account/applications

• Twitter - Using OAuth 1.0a https://dev.twitter.com/docs/auth/oauth

• Twitter - Moving from Basic Auth to OAuth https://dev.twitter.com/docs/auth/moving-from-basic-auth-to-oauth

• Single-user OAuth with Examples https://dev.twitter.com/docs/auth/oauth/single-user-with-examples

• Twitter - Create A New App https://dev.twitter.com/apps

• Facebook OAuth http://developers.facebook.com/docs/authentication/

• Facebook - Create A New App https://developers.facebook.com/apps

• Facebook - Permissions http://developers.facebook.com/docs/reference/api/permissions/

• Facebook - How to handle expired access_token https://developers.facebook.com/blog/post/500/

• Google OAuth http://code.google.com/apis/accounts/docs/OAuth2.html

• Google OAuth Scope: http://code.google.com/apis/gdata/faq.html#AuthScopes

cpanm Plack::Middleware::OAuth

perl -MCPAN -e shell
install Plack::Middleware::OAuth