Provided by: libnet-oauth2-perl_0.64-1_all bug

NAME

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

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->new(%options)
            -Option           --Defined in          --Default
             auto_save                                <set token's changed flag>
             client_id          Net::OAuth2::Profile  <required>
             client_secret      Net::OAuth2::Profile  <required>
             grant_type         Net::OAuth2::Profile  'authorization_code'
             hd                 Net::OAuth2::Profile  undef
             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
           hd => 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->auto_save()
       $obj->bearer_token_scheme()
           Inherited, see "Accessors" in Net::OAuth2::Profile

       $obj->grant_type()
           Inherited, see "Accessors" in Net::OAuth2::Profile

       $obj->hd()
           Inherited, see "Accessors" in Net::OAuth2::Profile

       $obj->id()
           Inherited, see "Accessors" in Net::OAuth2::Profile

       $obj->redirect_uri()
       $obj->referer( [$uri] )
       $obj->scope()
           Inherited, see "Accessors" in Net::OAuth2::Profile

       $obj->secret()
           Inherited, see "Accessors" in Net::OAuth2::Profile

       $obj->site()
           Inherited, see "Accessors" in Net::OAuth2::Profile

       $obj->state()
           Inherited, see "Accessors" in Net::OAuth2::Profile

       $obj->user_agent()
           Inherited, see "Accessors" in Net::OAuth2::Profile

   Actions
       Extends "Actions" in Net::OAuth2::Profile.

       $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

   Helpers
       Extends "Helpers" in Net::OAuth2::Profile.

       $obj->add_token($request, $token, $scheme)
           Inherited, see "Helpers" in Net::OAuth2::Profile

       $obj->build_request($method, $uri, $params)
           Inherited, see "Helpers" in Net::OAuth2::Profile

       $obj->params_from_response($response, $reason)
           Inherited, see "Helpers" in Net::OAuth2::Profile

       $obj->site_url( <$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", "state", and "hd" 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.64, built on March 21, 2018.
       Website: http://perl.overmeer.net/CPAN/.

COPYRIGHTS

       Copyrights 2013-2018-2018 on the perl code and the related documentation
        by [Mark Overmeer <markov@cpan.org>] for SURFnet bv, The Netherlands.  For other
       contributors see ChangeLog.

       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://dev.perl.org/licenses/