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.
Install Now
PNG Icons