Filewatcher File Search File Search
Catalog
Content Search
» » » » » Plack-Middleware-OAuth-0.05.tar.gz » Content »
pkg://Plack-Middleware-OAuth-0.05.tar.gz:28813/Plack-Middleware-OAuth-0.05/  info  downloads

README.mkdn

# 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](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 your 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_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](http://search.cpan.org/perldoc?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

# Supported Providers

- Google
- Twitter
- Facebook
- Github

# See Also

[Net::OAuth](http://search.cpan.org/perldoc?Net::OAuth), [Net::OAuth2](http://search.cpan.org/perldoc?Net::OAuth2)

# 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 - Create A New Client
[https://github.com/account/applications](https://github.com/account/applications)
- Twitter - Using OAuth 1.0a
[https://dev.twitter.com/docs/auth/oauth](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](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](https://dev.twitter.com/docs/auth/oauth/single-user-with-examples)
- 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)
Results 1 - 1 of 1
Help - FTP Sites List - Software Dir.
Search over 15 billion files
© 1997-2017 FileWatcher.com