Provided by: liblwp-authen-oauth2-perl_0.20-1_all bug

NAME

       LWP::Authen::OAuth2::ServiceProvider - ServiceProvider base class

VERSION

       version 0.20

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
       LWP::Authen::OAuth2::ServiceProvider::Withings
       LWP::Authen::OAuth2::ServiceProvider::Yahoo

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. If you
           explicitly provide these lists of required parameters, and a user fails to provide one
           (or more) of the parameters, the generated error message can tell the user which
           parameters are missing.

       "{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.

AUTHORS

       •   Ben Tilly, <btilly at gmail.com>

       •   Thomas Klausner <domm@plix.at>

COPYRIGHT AND LICENSE

       This software is copyright (c) 2013 - 2022 by Ben Tilly, Rent.com, Thomas Klausner.

       This is free software; you can redistribute it and/or modify it under the same terms as
       the Perl 5 programming language system itself.