bionic (3) LWP::Authen::OAuth2::ServiceProvider.3pm.gz

NAME

       LWP::Authen::OAuth2::ServiceProvider - Understand OAuth2 Service Providers

VERSION

       Version 0.02

SYNOPSIS

       This is a base module for representing an OAuth 2 service provider.  It is implicitly constructed from
       the parameters to "LWP::Authen::OAuth2->new", and is automatically delegated to when needed.

       The first way to try to specify the service provider is with the parameters "service_provider" and
       possibly "client_type":

           LWP::Authen::OAuth2->new(
               ...
               service_provider => "Foo",
               client_type => "bar", # optional
               ...
           );

       The first parameter will cause LWP::Authen::OAuth2::ServiceProvider to look for either
       "LWP::Authen::OAuth2::ServiceProvider::Foo", or if that is not found, for "Foo".  (If neither is present,
       an exception will be thrown.)  The second parameter will be passed to that module which can choose to
       customize the service provider behavior based on the client_type.

       The other way to specify the service provider is by passing in sufficient parameters to create a custom
       one on the fly:

           LWP::Authen::OAuth2->new(
               ...
               authorization_endpoint => $authorization_endpoint,
               token_endpoint => $token_endpoint,

               # These are optional but let you get the typo checks of strict mode
               authorization_required_params => [...],
               authorization_optional_params => [...],
               ...
           );

       See LWP::Authen::OAuth2::Overview if you are uncertain how to figure out the Authorization Endpoint and
       Token Endpoint from the service provider's documentation.

KNOWN SERVICE PROVIDERS

       The following service providers are provided in this distribution, with hopefully useful configuration
       and documentation:

       LWP::Authen::OAuth2::ServiceProvider::Dwolla
       LWP::Authen::OAuth2::ServiceProvider::Google
       LWP::Authen::OAuth2::ServiceProvider::Line
       LWP::Authen::OAuth2::ServiceProvider::Strava

SUBCLASSING

       Support for new service providers can be added with subclasses.  To do that it is useful to understand
       how things get delegated under the hood.

       First LWP::Authen::OAuth2 asks LWP::Authen::OAuth2::ServiceProvider to construct a service provider.
       Based on the "service_provider" argument, it figures out that it needs to load and use your base class.
       A service provider might need different behaviors for different client types.  You are free to take the
       client type and dynamically decide which subclass of yours will be loaded instead to get the correct
       flow.  Should your subclass need to, it can decide that that a subclass of LWP::Authen::OAuth2 should be
       used that actually knows about request types that are specific to your service provider.  Hopefully most
       service providers do not need this, but some do.

       For all of the potential complexity that is supported, most service provider subclasses should be simple.
       Just state what fields differ from the specification for specific requests and client types, then include
       documentation.  However even crazy service providers should be supportable.

       Here are the methods that were designed to be useful to override.  See the source if you have a need that
       none of these address.  But if you can do what you need to do through these, please do.

       "authorization_endpoint"
           Takes no arguments, returns the URL for the Authorization Endpoint for the service provider.  Your
           subclass cannot function without this.

       "token_endpoint"
           Takes no arguments, returns the URL for the Token Endpoint for the service provider.  Your subclass
           cannot function without this.

       "client_type_class"
           This method receives your class name and the passed in "client_type".  It is supposed to make sure
           that the class that handles that "client_type" is loaded, and then return it.  This lets you handle
           service providers with different behavior for different types of clients.

           The base implementation just returns your class name.

           If the programmer does not pass an explicit "client_type" the value that is passed in is "default".
           So that should be mapped to a reasonable client type.  This likely is something along the line of
           "webserver".  That way your module can be used without specifying a "client_type".

       "init"
           After "new" has figured out the right class to load, it immediately calls "$self-e<gt"init($opts)>
           with $opts being a hashref of all options passed to "LWP::Authen::OAuth2->new(...)" that were not
           consumed in figuring out the service provider.  This method can then extract any parameters that it
           wants to before anything else happens.

           If you only want to require/allow a few parameters to be extracted into the service provider object,
           then there is no need to write your own "init".  But if you want additional logic depending on passed
           in parameters, you can.

           To consume options and copy them to $self please use the following methods:

               $self->copy_option($opts, $required_field);
               $self->copy_option($opts, $optional_field, $default);

           If you want to consume options and return them as values instead:

               my $value1 = $self->extract_option($opts, $required_field);
               my $value2 = $self->extract_option($opts, $optional_field, $default);

           These methods delete from the hash, so do not try to consume an option twice.

       "required_init"
           The parameters that must be passed into "LWP::Authen::OAuth2->new(...)"  to initialize the service
           provider object.  The default required parameters are "client_id" and "client_secret", which in turn
           get used as default arguments inside of methods that need them.  In general it is good to only
           require arguments that are needed to generate refreshed tokens.  If you will not get a
           "refresh_token" in your flow, then you should require nothing.

       "optional_init"
           The parameters that can be passed into "LWP::Authen::OAuth2->new(...)" to initialize the service
           provider object.  The default optional parameters are "redirect_uri" and "scope" which, if passed, do
           not have to be passed into other method calls.

           The "state" is not included as an explicit hint that you should not simply use a default value.

           Note that these lists are deduped, so there is no harm in parameters being both required and
           optional, or appearing multiple times.

       "{authorization,request,refresh}_required_params"
           These three methods list parameters that must be included in the authorization url, the post to
           request tokens, and the post to refresh tokens respectively.  Supplying these can give better error
           messages if they are left out.

       "{authorization,request,refresh}_optional_params"
           These three methods list parameters that can be included in the authorization url, the post to
           request tokens, and the post to refresh tokens respectively.  In strict mode, supplying any
           parameters not included in more or required params will be an error.  Otherwise this has little
           effect.

       "{authorization,request,refresh}_default_params"
           These three methods returns a list of key/value pairs mapping parameters to default values in the
           authorization url, the post to request tokens, and the post to get refreshed tokens respectively.
           Supplying these can stop people from having to supply the parameters themselves.

           An example where this could be useful is to support a flow that uses different types of requests than
           normal.  For example with some client types and service providers, you might use a type of request
           with a "grant_type" of "password" or "client_credentials".

       "post_to_token_endpoint"
           When a post to a token endpoint is constructed, this actually sends the request.  The specification
           allows service providers to require authentication beyond what the specification requires, which may
           require cookies, specific headers, etc.  This method allows you to address that case.

       "access_token_class"
           Given a "token_type", what class implements access tokens of that type?  If your provider creates a
           new token type, or implements an existing token type in a quirky way that requires a nonstandard
           model to handle, this method can let you add support for that.

           The specification says that all the "token_type" must be case insensitive, so all types are lower
           cased for you.

           If the return value does not look like a package name, it is assumed to be an error message.  As long
           as you have spaces in your error messages and normal looking class names, this should DWIM.

           See LWP::Authen::OAuth2::AccessToken for a description of the interface that your access token class
           needs to meet.  (You do not have to subclass that - just duck typing here.)

       "oauth2_class"
           Override this to cause "LWP::Authen::OAuth2->new(...)" to return an object in a custom class.  This
           would be appropriate if people using your service provider need methods exposed that are not in
           LWP::Authen::OAuth2.

           Few service provider classes should find a reason to do this, but it can be done if you need.

       "collect_action_params"
           This is the method that processes parameters for a given action.  Should your service provider
           support a new kind of request, you can use this along with the "*_{required,more,default}_params"
           functions to support it.

           The implementation of "request_tokens" in this module give an example of how to use it.

CONTRIBUTING

       Patches contributing new service provider subclasses to this distributions are encouraged.  Should you
       wish to do so, please submit a git pull request that does the following:

       Implement your provider
           The more completely implemented, the better.

       Name it properly
           The name should be of the form:

               LWP::Authen::OAuth2::ServiceProvider::$ServiceProvider

       List it
           It needs to be listed as a known service provider in this module.

       Test it
           It is impossible to usefully test a service provider module without client secrets.  However you can
           have public tests that it compiles, and private tests that will, if someone supplies the necessary
           secrets, run fuller tests that all works.  See the existing unit tests for examples.

       Include it
           Your files need to be included in the "MANIFEST" in the root directory.

       Document Client Registration
           A developer should be able to read your module and know how to register themselves as a client of the
           service provider.

       List Client Types
           Please list the client types that the service provider uses, with just enough detail that a developer
           can figure out which one to use.  Listed types should, of course, either be implemented or be
           documented as not implemented.

       Document important quirks
           If the service provider requires or allows useful parameters, try to mention them in your
           documentation.

       Document limitations
           If there are known limitations in your implementation, please state them.

       Link to official documentation
           If the service provider provides official OAuth 2 documentation, please link to it.  Ideally a
           developer will not need to refer to it, but should know how to find it.

AUTHOR

       Ben Tilly, "<btilly at gmail.com>"

BUGS

       Please report any bugs or feature requests to "bug-lwp-authen-oauth2 at rt.cpan.org", or through the web
       interface at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=LWP-Authen-OAuth2>.  I will be notified, and
       then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

       You can find documentation for this module with the perldoc command.

           perldoc LWP::Authen::OAuth2::ServiceProvider

       You can also look for information at:

       Github (submit patches here)
           <https://github.com/btilly/perl-oauth2>

       RT: CPAN's request tracker (report bugs here)
           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=LWP-Authen-OAuth2>

       AnnoCPAN: Annotated CPAN documentation
           <http://annocpan.org/dist/LWP-Authen-OAuth2>

       CPAN Ratings
           <http://cpanratings.perl.org/d/LWP-Authen-OAuth2>

       Search CPAN
           <http://search.cpan.org/dist/LWP-Authen-OAuth2/>

ACKNOWLEDGEMENTS

       Thanks to Rent.com <http://www.rent.com> for their generous support in letting me develop and release
       this module.  My thanks also to Nick Wellnhofer <wellnhofer@aevum.de> for Net::Google::Analytics::OAuth2
       which was very enlightening while I was trying to figure out the details of how to connect to Google with
       OAuth2.

LICENSE AND COPYRIGHT

       Copyright 2013 Rent.com.

       This program is free software; you can redistribute it and/or modify it under the terms of the the
       Artistic License (2.0). You may obtain a copy of the full license at:

       <http://www.perlfoundation.org/artistic_license_2_0>

       Any use, modification, and distribution of the Standard or Modified Versions is governed by this Artistic
       License. By using, modifying or distributing the Package, you accept this license. Do not use, modify, or
       distribute the Package, if you do not accept this license.

       If your Modified Version has been derived from a Modified Version made by someone other than you, you are
       nevertheless required to ensure that your Modified Version complies with the requirements of this
       license.

       This license does not grant you the right to use any trademark, service mark, tradename, or logo of the
       Copyright Holder.

       This license includes the non-exclusive, worldwide, free-of-charge patent license to make, have made,
       use, offer to sell, sell, import and otherwise transfer the Package with respect to any patent claims
       licensable by the Copyright Holder that are necessarily infringed by the Package. If you institute patent
       litigation (including a cross-claim or counterclaim) against any party alleging that the Package
       constitutes direct or contributory patent infringement, then this Artistic License to you shall terminate
       on the date that such litigation is filed.

       Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS' AND
       WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES.  THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
       PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS
       REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
       OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF ADVISED OF THE
       POSSIBILITY OF SUCH DAMAGE.