/ 
LWP-Authen-OAuth2-0.19
River stage one • 4 direct dependents • 4 total dependents
⭐ Starred 5 GitHub stars
/ README.md

NAME

LWP::Authen::OAuth2 - Make requests to OAuth2 APIs.

VERSION

version 0.19

SYNOPSIS

OAuth 2 is a protocol that lets a user tell a service provider that a consumer has permission to use the service provider's APIs to do things that require access to the user's account. This module tries to make life easier for someone who wants to write a consumer in Perl.

Specifically it provides convenience methods for all of the requests that are made to the service provider as part of the permission handshake, and after that will proxy off of LWP::UserAgent to let you send properly authenticated requests to the API that you are trying to use. When possible, this will include transparent refresh/retry logic for access tokens expiration.

For a full explanation of OAuth 2, common terminology, the requests that get made, and the necessary tasks that this module does not address, please see LWP::Authen::OAuth2::Overview

This module will not help with OAuth 1. See the similarly named but unrelated LWP::Authen::OAuth for a module that can help with that.

Currently LWP::Authen::OAuth2 provides ready-to-use classes to use OAuth2 with

You can also access any other OAuth2 service by setting up a plain LWP::Authen::OAuth2 object. If you do, and the service provider might be of interest to other people, please submit a patch so we can include it in this distribution, or release it as a standalone package.

Here are examples of simple usage.

use LWP::Authen::OAuth2;

# Constructor
my $oauth2 = LWP::Authen::OAuth2->new(
                 client_id => "Public from service provider",
                 client_secret => "s3cr3t fr0m svc prov",
                 service_provider => "Google",
                 redirect_uri => "https://your.url.com/",

                 # Optional hook, but recommended.
                 save_tokens => \&save_tokens,
                 save_tokens_args => [ $dbh ],

                 # This is for when you have tokens from last time.
                 token_string => $token_string.
             );

# URL for user to go to to start the process.
my $url = $oauth2->authorization_url();

# The authorization_url sends the user to the service provider to
# say that you want to be authorized.  After the user confirms that
# request, the service provider sends the user back to you with a
# code.  This might be a CGI parameter, something that the user is
# supposed to paste to you - that's between you and the service
# provider.

# Assuming that you have your code, get your tokens from the service
# provider.
$oauth2->request_tokens(code => $code);

# Get your token as a string you can easily store, pass around, etc.
# If you have a save_tokens callback, that gets passed this string
# whenever the tokens change.
#
# This string bears a suspicious resemblance to serialized JSON.
my $token_string = $oauth2->token_string,

# Access the API.  Consult the service_provider's documentation for when
# to use which type of request.  Note that argument processing is the
# same as in LWP.  Thus the parameters array and headers hash are both
# optional.
$oauth2->get($url, %header);
$oauth2->post($url, \@parameters, %header);
$oauth2->put($url, %header);
$oauth2->delete($url, %header);
$oauth2->head($url, %header);

# And if you need more flexibility, you can use LWP::UserAgent's request
# method
$oauth2->request($http_request, $content_file);

# In some flows you can refresh tokens, in others you have to go through
# the handshake yourself.  This method lets you know whether a refresh
# looks possible.
$oauth2->can_refresh_tokens();

# This method lets you know when it is time to reauthorize so that you
# can find out in a nicer way than failing an API call.
$oauth2->should_refresh();

CONSTRUCTOR

When you call LWP::Authen::OAuth2->new(...), arguments are passed as a key/value list. They are processed in the following phases:

Here are those phases in more detail.

METHODS

Once you have an object, the following methods may be useful for writing a consumer.

$oauth2->authorization_url(%opts)

Generate a URL for the user to go to to request permissions. By default the response_type and client_id are defaulted, and all of redirect_uri, state and scope are optional but not required. However in practice this all varies by service provider and client type, so look for documentation on that for the actual list that you need.

$oauth2->request_tokens(%opts)

Request tokens from the service provider (if possible). By default the grant_type, client_id and client_secret are defaulted, and the scope is required. However in practice this all varies by service provider and client type, so look for documentation on that for the actual list that you need.

$oauth2->get(...)

Issue a get request to an OAuth 2 protected URL, just like you would using LWP::UserAgent to a normal URL.

$oauth2->head(...)

Issue a head request to an OAuth 2 protected URL, just like you would using LWP::UserAgent to a normal URL.

$oauth2->post(...)

Issue a post request to an OAuth 2 protected URL, just like you would using LWP::UserAgent to a normal URL.

$oauth2->delete(...)

Issue a delete request to an OAuth 2 protected URL, similar to the previous examples. (This shortcut is not by default available with LWP::UserAgent.)

$oauth2->put(...)

Issue a put request to an OAuth 2 protected URL, similar to the previous examples. (This shortcut is not by default available with LWP::UserAgent.)

$oauth2->request(...)

Issue any request that you could issue with LWP::UserAgent, except that it will be properly signed to go to an OAuth 2 protected URL.

$oauth2->make_api_call($uri, $params, $headers)

This is a convenience method which makes a call to an OAuth2 API endpoint given by $uri, and returns the JSON response decoded to a hash. If the $params hashref arg is set, its contents will be JSON encoded and sent as POST request content; otherwise it will make a GET request. Optional $headers may be sent which will be passed through to $oauth->get() or $oauth->post().

If the call succeeds, it will return the response's JSON content decoded as hash, or if no response body was returned, a value of 1 to indicate success. On failure returns undef, and error message is available from $oauth2->api_call_error().

$oauth2->api_call_error()

If an error occurred in $oauth2->make_api_call(), this method will return it. The error message comes from HTTP::Response->error_as_HTML().

$oauth2->api_url_base()

Returns the base URL of the service provider, which is sometimes useful to be used in the content of OAuth2 API calls.

$oauth2->can_refresh_tokens

Is sufficient information available to try to refresh tokens?

$oauth2->should_refresh()

Is it time to refresh tokens?

$oauth2->set_early_refresh_time($seconds)

Set how many seconds before the end of token expiration the method should_refresh will start turning true. Values over half the initial expiration time of access tokens will be ignored to avoid refreshing too often. This defaults to 300.

$oauth2->expires_time()

Returns the raw epoch expiration time of the current access token. Typically this is 3600 seconds greater than the time of token creation.

$oauth2->set_is_strict($mode)

Set strict mode on/off. See the discussion of is_strict in the constructor for an explanation of what it does.

$oauth2->set_error_handler(\&error_handler)

Set the error handler. See the discussion of error_handler in the constructor for an explanation of what it does.

$oauth2->set_prerefresh(\&prerefresh)

Set the prerefresh handler. See the discussion of prerefresh_handler in the constructor for an explanation of what it does.

$oauth2->set_save_tokens($ua)

Set the save tokens handler. See the discussion of save_tokens in the constructor for an explanation of what it does.

$oauth2->set_user_agent($ua)

Set the user agent. This should respond to the same methods that a LWP::UserAgent responds to.

$oauth2->user_agent()

Get the user agent. The default if none was explicitly set is a new LWP::UserAgent object.

Contributors

ACKNOWLEDGEMENTS

Thanks to 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.

Thanks to

AUTHORS

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.