Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Net::OAuth2::Profile::UsereContributed Perl Net::OAuth2::Profile::WebServer(3)

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.66, built on
       October 01, 2019. Website: http://perl.overmeer.net/CPAN/.

COPYRIGHTS
       Copyrights 2013-2019-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/

perl v5.32.0			  2019-10-01Net::OAuth2::Profile::WebServer(3)

NAME | INHERITANCE | SYNOPSIS | DESCRIPTION | METHODS | DETAILS | SEE ALSO | COPYRIGHTS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Net::OAuth2::Profile::WebServer&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help