/ 
Net-OAuth2-0.51
River stage one • 5 direct dependents • 8 total dependents
/ Net::OAuth2::Profile::WebServer

NAME

Net::OAuth2::Profile::WebServer - OAuth2 for web-server use

INHERITANCE

Net::OAuth2::Profile::WebServer
  is a Net::OAuth2::Profile

SYNOPSIS

my $auth = Net::OAuth2::Profile::WebServer->new
  ( name           => 'Google Contacts'
  , client_id      => $id
  , client_secret  => $secret
  , site           => 'https://accounts.google.com'
  , scope          => 'https://www.google.com/m8/feeds/'
  , authorize_path    => '/o/oauth2/auth'
  , access_token_path => '/o/oauth2/token'
  , protected_resource_url
      =>  'https://www.google.com/m8/feeds/contacts/default/full'
  );

# Let user ask for a grant from the resource owner
print $auth->authorize_response->as_string;
# or, in Plack:   redirect $auth->authorize;

# Prove your identity at the authorization server
my $access_token  = $auth->get_access_token($info->{code});

# communicate with the resource serve
my $response      = $access_token->get('/me');
$response->is_success
    or die "error: " . $response->status_line;

print "Yay, it worked: " . $response->decoded_content;

DESCRIPTION

Use OAuth2 in a WebServer context. Read the DETAILS section, far below this man-page before you start implementing this interface.

METHODS

Constructors

Net::OAuth2::Profile::WebServer->new(OPTIONS)
-Option       --Defined in          --Default
 client_id      Net::OAuth2::Profile  <required>
 client_secret  Net::OAuth2::Profile  <required>
 grant_type     Net::OAuth2::Profile  'authorization_code'
 redirect_uri                         undef
 referer                              undef
 scope          Net::OAuth2::Profile  undef
 site           Net::OAuth2::Profile  undef
 token_scheme   Net::OAuth2::Profile  'auth-header:OAuth'
 user_agent     Net::OAuth2::Profile  <created internally>
client_id => STRING
client_secret => STRING
grant_type => STRING
redirect_uri => URI
referer => URI

Adds a Referer header to each request. Some servers check whether provided redirection uris point to the same server the page where the link was found.

scope => STRING
site => URI
token_scheme => SCHEME
user_agent => LWP::UserAgent object

Accessors

$obj->bearer_token_scheme()

See "Accessors" in Net::OAuth2::Profile

$obj->grant_type()

See "Accessors" in Net::OAuth2::Profile

$obj->id()

See "Accessors" in Net::OAuth2::Profile

$obj->redirect_uri()
$obj->referer([URI])
$obj->scope()

See "Accessors" in Net::OAuth2::Profile

$obj->secret()

See "Accessors" in Net::OAuth2::Profile

$obj->site()

See "Accessors" in Net::OAuth2::Profile

$obj->user_agent()

See "Accessors" in Net::OAuth2::Profile

Actions

$obj->authorize(OPTIONS)

On initial contact of a new user, you have to redirect to the resource owner. Somewhere in the near future, your application will be contacted again by the same user but then with an authorization grant code.

Only the most common OPTIONS are listed... there may be more: read the docs on what your server expects.

-Option       --Default
 client_id      new(client_id)
 response_type  'code'
 scope          undef
 state          undef
client_id => STRING
response_type => STRING
scope => STRING
state => STRING

example:

my $auth = Net::OAuth2::Profile::WebServer->new(...);

# From the Plack demo, included in this distribution (on CPAN)
get '/get' => sub { redirect $auth->authorize };

# In generic HTTP, see method authorize_response
use HTTP::Status 'HTTP_TEMPORARY_REDIRECT';   # 307
print HTTP::Response->new
  ( HTTP_TEMPORARY_REDIRECT => 'Get authorization grant'
  , [ Location => $auth->authorize ]
  )->as_string;
$obj->authorize_response([REQUEST])

Convenience wrapper around authorize(), to produce a complete HTTP::Response object to be sent back.

$obj->get_access_token(CODE, OPTIONS)
-Option       --Default
 client_id      new(client_id)
 client_secret  new(client_secret)
client_id => STRING
client_secret => STRING
$obj->update_access_token(TOKEN, OPTIONS)

Ask the server for a new token. You may pass additional OPTIONS as pairs. However, this method is often triggered automatically, in which case you can to use the refresh_token_params option of new().

example:

$auth->update_access_token($token);
$token->refresh;   # nicer

HTTP

$obj->request(REQUEST, [MORE])

See "HTTP" in Net::OAuth2::Profile

$obj->request_auth(TOKEN, (REQUEST | (METHOD, URI, [HEADER, CONTENT])))

See "HTTP" in Net::OAuth2::Profile

Helpers

$obj->add_token(REQUEST, TOKEN, SCHEME)

See "Helpers" in Net::OAuth2::Profile

$obj->build_request(METHOD, URI, PARAMS)

See "Helpers" in Net::OAuth2::Profile

$obj->params_from_response(RESPONSE, REASON)

See "Helpers" in Net::OAuth2::Profile

$obj->site_url((URI|PATH), PARAMS)

See "Helpers" in Net::OAuth2::Profile

DETAILS

The process

The main complication does not show in the example in the SYNOPSIS, not in the plack example included in the distribution: your client session can not survive the shown steps: your application behaves like a server, not a client. You need to implement losely coupled server-server communication, which is less straight-forward.

First, your application must implement a persistent session (in a database or file), which may get called on any weird moment to pass on information. Your application must be visible from "outside" and use https. More than enough complications. Full example needed ;-)

The client side of the process has three steps, nicely described in https://tools.ietf.org/html/rfc6749|RFC6749

1. Send an authorization request to resource owner

It needs a client_id: usually the name of the service where you want get access to. The answer is a redirect, based on the redirection_uri which you usually pass on. Additional scope and state parameters can be needed or useful. The redirect will provide you with (amongst other things) a code parameter.

2. Translate the code into an access token

With the code, you go to an authorization server which will validate your existence. An access token (and sometimes a refresh token) are returned.

3. Address the protected resource

The access token, usually a 'bearer' token, is added to each request to the resource you want to address. The token may refresh itself when needed.

SEE ALSO

This module is part of Net-OAuth2 distribution version 0.51, built on January 08, 2013. Website: http://perl.overmeer.net.

COPYRIGHTS

Copyrights 2013 on the perl code and the related documentation by [Mark Overmeer] for SURFnet bv, The Netherlands. For other contributors see Changes.

Copyrights 2011-12 by Keith Grennan.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See http://www.perl.com/perl/misc/Artistic.html