Google-OAuth
view release on metacpan or search on metacpan
lib/Google/OAuth.pm view on Meta::CPAN
The Google Apps API provides a mechanism to access the private and personal
information in Google accounts. Naturally, there's a significant amount of
complexity to authorize and authenticate an integration process. Although
the Google::OAuth package handles all this complexity, the following describes
the background activity.
=head2 Credentials
The first part of the authorization process requires establishing, and then
presenting, your credentials for authorization. These credentials start
out with a personal Google account, followed by a registration process
that describes your integration project. When registration is complete,
Google will generate and display several string values that will be used later
in the installation process. These string values are refered to as I<client
credentials>.
Create a Google account if necessary, log in, then visit Google's developer
site:
http://developers.google.com/
At the bottom of the page (as of April 2013) there is a link to the API
Console. Use the API Console to register an application. The information
in your registration will be visible to users when they authorize your
access. When the registration is complete, Google assigns three credential
lib/Google/OAuth.pm view on Meta::CPAN
=over 8
=item 1. A I<Client ID>
=item 2. A I<Client Secret>
=item 3. One or more I<Redirect URIs>
=back 8
A fourth value, the "Email address" is not used to establish credentials.
=head2 User Authorization
Once you've established credentials, you request that Google users
authorize your application to access their account information. Your
request is in the form of a URL link. For example, during the installation
(described below), you'll email yourself a request link in order to test
your installation.
Google uses three values as part of the authorization/authentication process:
=over 8
=item 1. A I<Grant Code>: The Grant Code is a ticket that can only be used once.
lib/Google/OAuth.pm view on Meta::CPAN
appropriate for the larger, more complex data persistence needs.
=head1 INSTALLATION
After building this package using Make or CPAN, additional installation
tasks are required:
=over 8
=item 1. Define the application credentials
=item 2. Set up the data persistence component
=back 8
These tasks are divided into five additional steps that must be peformed
before this package is ready to use:
=over 8
lib/Google/OAuth.pm view on Meta::CPAN
=item I<drive>
=back 8
The C<token_request()> method output is a legal, functional URL. The
caller is responsible for wrapping the HTML.
=head2 Acquire the Grant Code
Google transmits the I<Grant Code> via HTTP using the redirect_uri defined in
the client credentials. Google provides the option to define multiple
redirects, but Google::OAuth's installation process requires only one.
There are two approaches to using an alternative I<redirect_uri> definition.
In either case the definition must match one of the values in Google's API
registration. First, the I<redirect_uri> element in the client credentials
can be redefined, as with any element, using the C<setclient()> method as
follows:
my @redirect = ( ... ) ;
Google::OAuth->setclient( redirect_uri => $redirect[1] ) ;
Second, in each specific instance, any component to the token request url can
be modified by overriding C<token_request>'s defaults. The resulting code is
fairly elaborate (and not illustrated here) because I<all> of the internal
values must be defined in the Google::OAuth::Client constructor when
lib/Google/OAuth.pm view on Meta::CPAN
=over 8
=item google => refresh_token
=item facebook => fb_exchange_token
=back 8
=head2 Google::OAuth::Client
Methods that need to access the client credentials are defined under
the C<Google::OAuth::Client> module. In the context of this package,
the methods are independent of token object data.
=head3 setclient()
C<< Google::OAuth->setclient() >> is called automatically. It must be
explicitly called again to manually set the client_secret in secure
installations:
Google::OAuth->setclient( client_secret => 'xAtN' ) ;
lib/Google/OAuth.pm view on Meta::CPAN
URL consists of the following definitions:
=over 8
=item 1. Overrides passed as arguments to the Google::OAuth::Client constructor.
=item 2. Default values defined within the C<token_request()> method.
=item 3. Scope definitions defined by the C<scope()> method.
=item 4. Client credentials defined in C<Google::OAuth::Config>.
=item 5. Client credentials defined by C<< Google::OAuth->setclient() >>.
=back 8
=head3 get_token()
C<get_token()> retrieves a token from Google using a HTTP::Request based on
the following definitions:
C<< $client->get_token() >> If this method is invoked with an object,
definitions are passed to the object's constructor and override any internal
lib/Google/OAuth.pm view on Meta::CPAN
=item test()
=item install()
=back 8
=head2 Google::OAuth::Config
C<Google::OAuth::Config> is generated during the installation process, and
contains the definitions of the client credentials and DSN.
C<Google::OAuth::Config::setclient()> is its only defined method.
=head1 SECURE INSTALLATION
Since the client credentials are built into the installation, some
tweaking is required to use Google::OAuth in a shared environment.
The easiest would be a simple launch script as follows:
use Google::OAuth ;
$dsn = define_a_dsn() ;
Google::OAuth->setclient(
client_id => '...',
lib/Google/OAuth.pm view on Meta::CPAN
the adventurous can subclass Google::OAuth and override the
Google::OAuth::Client methods. mod_perl has a variety of configuration
strategies that could be applied, but not an obvious universal solution.
For the time being, the foremost concern of this initial release is simplicity.
A more urgent concern is restricting access to Google::OAuth data in a
multi-user environment. There are basically two concerns:
=over 8
=item 1. Access to the client credentials
=item 2. Access to user tokens in the DSN
=back 8
The solution is to simply leave those definitions incomplete in the
configuration file. Define the DSN in the config file, but leave the DSN
unconnected until run-time. Then, during run-time, load the missing
configuration definitions and connect the data source as follows:
lib/Google/OAuth/Install.pm view on Meta::CPAN
# #
###############################################################################
## Step 1 - Specify a NoSQL::PL2SQL database driver
# use NoSQL::PL2SQL::DBI::MySQL ; ## Uncomment
###############################################################################
# #
# Step 2 - Specify Google API credentials #
# #
# If you haven't already, you must register an application to access the #
# Google API. Here is the link to register: #
# https://code.google.com/apis/console/ #
# #
# Once you've registered, the values required below can be displayed by #
# clicking the "API Access" tab in the upper left navigation. #
# #
# Warning: The client_secret and dsn access will be available to #
# everyone in a shared environment. Refer to "SECURE INSTALLATION"
# in the manual. #
# #
###############################################################################
## Step 2 - Specify Google API credentials
$client{redirect_uri} = '' ;
$client{client_id} = '' ;
$client{client_secret} = '' ; ## May be left blank
###############################################################################
# #
# Step 3 - Define the NoSQL::PLSQL dsn #
# #
samples/Facebook/OAuth.pm view on Meta::CPAN
$fbo = Facebook::OAuth->token( $email )->content( $url ) ;
=head1 DESCRIPTION
Facebooks's OAuth implementation is much simpler than Google's, so this
interface may be over-generalized. The advantage lies in code reuse, and
a consistent interface that ultimately provides an effective general
purpose OAuth client.
The Google::OAuth setup includes a Facebook configuration to establish
Facebook credentials. The configuration assumes a single data source
for all OAuth tokens that can support a variety of web services.
Additionally, the L<SYNOPSIS> demonstrates an API showing the 3 phases
of data access:
=head2 Acquire a Grant Code
In order to generate a I<Grant Code>, users log into Facebook and the grant
code is transmitted to a I<redirect_uri> defined in the credentials. All the
credentials are passed as query parameters in a single URI link.
Facebook uses quite a few permission settings, any number of which can be
passed as arguments to the C<scope()> method. This interface always requests
the I<email> permisssion.
## Get Grant Code
$link = Facebook::OAuth->token_request ;
=head2 Acquire a Token
t/Google-OAuth.t view on Meta::CPAN
my $t ;
my $ok ;
is( Google::OAuth->dsn->table, 'googletokens', 'DSN name' ) ;
is( ref Google::OAuth->dsn->db, 'NoSQL::PL2SQL::DBI::Null', 'DSN source' ) ;
$t = Google::OAuth::Client->new->scope(
'calendar.readonly'
)->token_request ;
ok( linkcompare( $t, $test[0] ), 'Default credentials' ) ;
$t = Google::OAuth::Client->new->scope(
'm8.feeds', 'calendar', 'calendar.readonly', 'drive.readonly',
)->token_request ;
ok( linkcompare( $t, $test[1] ), 'Expanded scope' ) ;
my @credentials = qw(
client_id
FTNmkFXfh6OZH5jXsW7qLe3bgsnl7ZObPfsuscNy
client_secret
Op6MR5gl73VY2yJkrb86dT4iySguvM8HhSqC2dEm
) ;
is( Google::OAuth->setclient( @credentials ), undef, 'setclient' ) ;
$t = Google::OAuth::Client->new->scope(
'calendar.readonly'
)->token_request ;
ok( linkcompare( $t, $test[2] ), 'Modified credentials' ) ;
$t = Google::OAuth::Client->new(
'client_id', { foo => 'client_secret' }
)->scope(
'calendar.readonly'
)->token_request ;
ok( linkcompare( $t, $test[3] ), 'token_request override' ) ;
is( ref $token, 'Google::OAuth', 'Test token found' ) ;
is( $Google::OAuth::Config::test{grantcode},
( run in 0.259 second using v1.01-cache-2.11-cpan-4d50c553e7e )