GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  NET::OAUTH2::PROFILE::WEBSERVER (3)

.ds Aq ’

NAME

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

CONTENTS

INHERITANCE



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



SYNOPSIS



  # See examples/psgi/
  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
  # The $info are the parameters from the callback to your service, it
  # will contain a code value.
  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.

Extends DESCRIPTION in Net::OAuth2::Profile.

METHODS

Extends METHODS in Net::OAuth2::Profile.

    Constructors

Extends Constructors in Net::OAuth2::Profile.
Net::OAuth2::Profile::WebServer-><B>newB>(%options)


 -Option           --Defined in          --Default
  auto_save                                <set tokens changed flag>
  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
  secrets_in_params  Net::OAuth2::Profile  <true>
  site               Net::OAuth2::Profile  undef
  state              Net::OAuth2::Profile  undef
  token_scheme       Net::OAuth2::Profile  auth-header:Bearer
  user_agent         Net::OAuth2::Profile  <created internally>



auto_save => CODE When a new token is received or refreshed, it usually needs to get save into a database or file. The moment you receive a new token is clear, but being aware of refreshes in your main program is a hassle. Read more about configuring this in the DETAILS section below.
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
secrets_in_params => BOOLEAN
site => URI
state => STRING
token_scheme => SCHEME
user_agent => LWP::UserAgent object

    Accessors

Extends Accessors in Net::OAuth2::Profile.
$obj-><B>auto_saveB>()
$obj-><B>bearer_token_schemeB>() Inherited, see Accessors in Net::OAuth2::Profile
$obj-><B>grant_typeB>() Inherited, see Accessors in Net::OAuth2::Profile
$obj-><B>idB>() Inherited, see Accessors in Net::OAuth2::Profile
$obj-><B>redirect_uriB>()
$obj-><B>refererB>( [$uri] )
$obj-><B>scopeB>() Inherited, see Accessors in Net::OAuth2::Profile
$obj-><B>secretB>() Inherited, see Accessors in Net::OAuth2::Profile
$obj-><B>siteB>() Inherited, see Accessors in Net::OAuth2::Profile
$obj-><B>stateB>() Inherited, see Accessors in Net::OAuth2::Profile
$obj-><B>user_agentB>() Inherited, see Accessors in Net::OAuth2::Profile

    Actions

Extends Actions in Net::OAuth2::Profile.
$obj-><B>authorizeB>(%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-><B>authorize_responseB>( [$request] ) Convenience wrapper around authorize(), to produce a complete HTTP::Response object to be sent back.
$obj-><B>get_access_tokenB>(CODE, %options)


 -Option       --Default
  client_id      new(client_id)
  client_secret  new(client_secret)



client_id => STRING
client_secret => STRING
$obj-><B>update_access_tokenB>($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



    Helpers

Extends Helpers in Net::OAuth2::Profile.
$obj-><B>add_tokenB>($request, $token, $scheme) Inherited, see Helpers in Net::OAuth2::Profile
$obj-><B>build_requestB>($method, $uri, $params) Inherited, see Helpers in Net::OAuth2::Profile
$obj-><B>params_from_responseB>($response, $reason) Inherited, see Helpers in Net::OAuth2::Profile
$obj-><B>site_urlB>( <$uri|$path>, $params ) Inherited, see Helpers in Net::OAuth2::Profile

DETAILS

OAuth2 is a server-server protocol, not the usual client-server set-up. The consequence is that the protocol handlers on both sides will not wait for another during the communication: the remote uses callback urls to pass on the response. Your side of the communication, your webservice, needs to re-group these separate processing steps into logical sessions.

    The process

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.

    Saving the token

Your application must implement a persistent session, probably in a database or file. The session information is kept in an Net::OAuth2::AccessToken object, and does contain more facts than just the access token.

Let’s discuss the three approaches.

no saving

The Plack example contained in the CPAN distribution of this module is a single process server. The tokens are administered in the memory of the process. It is nice to test your settings, but probably not realistic for any real-life application.

automatic saving

When your own code is imperative:



  my $auth = Net::OAuth2::Profile::WebServer->new
    ( ...
    , auto_save => \&save_session
    );

  sub save_session($$)
  {   my ($profile, $token) = @_;
      ...
  }



When your own code is object oriented:



  sub init(...)
  {  my ($self, ...) = @_;
     my $auth = Net::OAuth2::Profile::WebServer->new
       ( ...
       , auto_save => sub { $self->save_session(@_) }
       );
  }

  sub save_session($$)
  {   my ($self, $profile, $token) = @_;
      ...
  }



explicit saving

In this case, do not use new(auto_save).

SEE ALSO

This module is part of Net-OAuth2 distribution version 0.63, built on January 18, 2016. Website: http://perl.overmeer.net.

COPYRIGHTS

Copyrights 2013-2016 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

Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 NET::OAUTH2::PROFILE::WEBSERVER (3) 2016-01-18

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.