# NAME

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

# DESCRIPTION

[Plack::Middleware::OAuth](http://search.cpan.org/perldoc?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 you OAuth service is to setup your `consumer_key`, `consumer_secret` (OAuth1) or `client_id`, `client_secret`, `scope` (OAuth2).

[Plack::Middleware::OAuth](http://search.cpan.org/perldoc?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](http://search.cpan.org/perldoc?Plack::Middleware::OAuth) on `/oauth`, then you can access [http://youdomain.com/oauth/twitter](http://youdomain.com/oauth/twitter) to authorize,
[Plack::Middleware::OAuth](http://search.cpan.org/perldoc?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](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_signin => sub  { 
                    my ($self,$env,$oauth_data) = @_;
                    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 Signin Callback

    enable 'OAuth', 
        providers => { .... },
        on_signin => sub  { 
            my ($self,$env,$oauth_data) = @_;
            return [  200 , [ 'Content-type' => 'text/html' ] , 'Signin!' ];
        };

Without specify `on_signin`, OAuth middleware will use YAML to dump the response data to page.

# Handle Error

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

        };

# Reference

- *

OAuth Workflow 
[http://hueniverse.com/oauth/guide/workflow/](http://hueniverse.com/oauth/guide/workflow/)

- *

OAuth 2.0 Protocal Draft
[http://tools.ietf.org/html/draft-ietf-oauth-v2](http://tools.ietf.org/html/draft-ietf-oauth-v2)

- * 

Github OAuth 
[https://github.com/account/applications/2739](https://github.com/account/applications/2739)

- *

Github - Create A New Client
[https://github.com/account/applications](https://github.com/account/applications)

- *

Twitter OAuth
[https://dev.twitter.com/apps/1225208/show](https://dev.twitter.com/apps/1225208/show)

- *

Twitter - Create A New App
[https://dev.twitter.com/apps](https://dev.twitter.com/apps)



- *

Facebook OAuth
[http://developers.facebook.com/docs/authentication/](http://developers.facebook.com/docs/authentication/)

- *

Facebook - Create A New App
[https://developers.facebook.com/apps](https://developers.facebook.com/apps)

- *

Facebook - Permissions
[http://developers.facebook.com/docs/reference/api/permissions/](http://developers.facebook.com/docs/reference/api/permissions/)

- *

Facebook - How to handle expired access_token
[https://developers.facebook.com/blog/post/500/](https://developers.facebook.com/blog/post/500/)

- *

Google OAuth
[http://code.google.com/apis/accounts/docs/OAuth2.html](http://code.google.com/apis/accounts/docs/OAuth2.html)

- *

Google OAuth Scope:
[http://code.google.com/apis/gdata/faq.html#AuthScopes](http://code.google.com/apis/gdata/faq.html#AuthScopes)