.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Net::OAuth2::Profile::WebServer 3pm" .TH Net::OAuth2::Profile::WebServer 3pm "2016-01-21" "perl v5.22.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Net::OAuth2::Profile::WebServer \- OAuth2 for web\-server use .SH "INHERITANCE" .IX Header "INHERITANCE" .Vb 2 \& Net::OAuth2::Profile::WebServer \& is a Net::OAuth2::Profile .Ve .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 12 \& # See examples/psgi/ \& my $auth = Net::OAuth2::Profile::WebServer\->new \& ( name => \*(AqGoogle Contacts\*(Aq \& , client_id => $id \& , client_secret => $secret \& , site => \*(Aqhttps://accounts.google.com\*(Aq \& , scope => \*(Aqhttps://www.google.com/m8/feeds/\*(Aq \& , authorize_path => \*(Aq/o/oauth2/auth\*(Aq \& , access_token_path => \*(Aq/o/oauth2/token\*(Aq \& , protected_resource_url \& => \*(Aqhttps://www.google.com/m8/feeds/contacts/default/full\*(Aq \& ); \& \& # 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 \*(Aqcode\*(Aq value. \& my $access_token = $auth\->get_access_token($info\->{code}); \& \& # communicate with the resource serve \& my $response = $access_token\->get(\*(Aq/me\*(Aq); \& $response\->is_success \& or die "error: " . $response\->status_line; \& \& print "Yay, it worked: " . $response\->decoded_content; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" Use OAuth2 in a WebServer context. Read the \s-1DETAILS\s0 section, far below this man-page before you start implementing this interface. .PP Extends \*(L"\s-1DESCRIPTION\*(R"\s0 in Net::OAuth2::Profile. .SH "METHODS" .IX Header "METHODS" Extends \*(L"\s-1METHODS\*(R"\s0 in Net::OAuth2::Profile. .SS "Constructors" .IX Subsection "Constructors" Extends \*(L"Constructors\*(R" in Net::OAuth2::Profile. .IP "Net::OAuth2::Profile::WebServer\->\fBnew\fR(%options)" 4 .IX Item "Net::OAuth2::Profile::WebServer->new(%options)" .Vb 10 \& \-Option \-\-Defined in \-\-Default \& auto_save \& client_id Net::OAuth2::Profile \& client_secret Net::OAuth2::Profile \& grant_type Net::OAuth2::Profile \*(Aqauthorization_code\*(Aq \& redirect_uri undef \& referer undef \& scope Net::OAuth2::Profile undef \& secrets_in_params Net::OAuth2::Profile \& site Net::OAuth2::Profile undef \& state Net::OAuth2::Profile undef \& token_scheme Net::OAuth2::Profile \*(Aqauth\-header:Bearer\*(Aq \& user_agent Net::OAuth2::Profile .Ve .RS 4 .IP "auto_save => \s-1CODE\s0" 2 .IX Item "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 \*(L"\s-1DETAILS\*(R"\s0 section below. .IP "client_id => \s-1STRING\s0" 2 .IX Item "client_id => STRING" .PD 0 .IP "client_secret => \s-1STRING\s0" 2 .IX Item "client_secret => STRING" .IP "grant_type => \s-1STRING\s0" 2 .IX Item "grant_type => STRING" .IP "redirect_uri => \s-1URI\s0" 2 .IX Item "redirect_uri => URI" .IP "referer => \s-1URI\s0" 2 .IX Item "referer => URI" .PD Adds a \f(CW\*(C`Referer\*(C'\fR header to each request. Some servers check whether provided redirection uris point to the same server the page where the link was found. .IP "scope => \s-1STRING\s0" 2 .IX Item "scope => STRING" .PD 0 .IP "secrets_in_params => \s-1BOOLEAN\s0" 2 .IX Item "secrets_in_params => BOOLEAN" .IP "site => \s-1URI\s0" 2 .IX Item "site => URI" .IP "state => \s-1STRING\s0" 2 .IX Item "state => STRING" .IP "token_scheme => \s-1SCHEME\s0" 2 .IX Item "token_scheme => SCHEME" .IP "user_agent => LWP::UserAgent object" 2 .IX Item "user_agent => LWP::UserAgent object" .RE .RS 4 .RE .PD .SS "Accessors" .IX Subsection "Accessors" Extends \*(L"Accessors\*(R" in Net::OAuth2::Profile. .ie n .IP "$obj\->\fBauto_save\fR()" 4 .el .IP "\f(CW$obj\fR\->\fBauto_save\fR()" 4 .IX Item "$obj->auto_save()" .PD 0 .ie n .IP "$obj\->\fBbearer_token_scheme\fR()" 4 .el .IP "\f(CW$obj\fR\->\fBbearer_token_scheme\fR()" 4 .IX Item "$obj->bearer_token_scheme()" .PD Inherited, see \*(L"Accessors\*(R" in Net::OAuth2::Profile .ie n .IP "$obj\->\fBgrant_type\fR()" 4 .el .IP "\f(CW$obj\fR\->\fBgrant_type\fR()" 4 .IX Item "$obj->grant_type()" Inherited, see \*(L"Accessors\*(R" in Net::OAuth2::Profile .ie n .IP "$obj\->\fBid\fR()" 4 .el .IP "\f(CW$obj\fR\->\fBid\fR()" 4 .IX Item "$obj->id()" Inherited, see \*(L"Accessors\*(R" in Net::OAuth2::Profile .ie n .IP "$obj\->\fBredirect_uri\fR()" 4 .el .IP "\f(CW$obj\fR\->\fBredirect_uri\fR()" 4 .IX Item "$obj->redirect_uri()" .PD 0 .ie n .IP "$obj\->\fBreferer\fR( [$uri] )" 4 .el .IP "\f(CW$obj\fR\->\fBreferer\fR( [$uri] )" 4 .IX Item "$obj->referer( [$uri] )" .ie n .IP "$obj\->\fBscope\fR()" 4 .el .IP "\f(CW$obj\fR\->\fBscope\fR()" 4 .IX Item "$obj->scope()" .PD Inherited, see \*(L"Accessors\*(R" in Net::OAuth2::Profile .ie n .IP "$obj\->\fBsecret\fR()" 4 .el .IP "\f(CW$obj\fR\->\fBsecret\fR()" 4 .IX Item "$obj->secret()" Inherited, see \*(L"Accessors\*(R" in Net::OAuth2::Profile .ie n .IP "$obj\->\fBsite\fR()" 4 .el .IP "\f(CW$obj\fR\->\fBsite\fR()" 4 .IX Item "$obj->site()" Inherited, see \*(L"Accessors\*(R" in Net::OAuth2::Profile .ie n .IP "$obj\->\fBstate\fR()" 4 .el .IP "\f(CW$obj\fR\->\fBstate\fR()" 4 .IX Item "$obj->state()" Inherited, see \*(L"Accessors\*(R" in Net::OAuth2::Profile .ie n .IP "$obj\->\fBuser_agent\fR()" 4 .el .IP "\f(CW$obj\fR\->\fBuser_agent\fR()" 4 .IX Item "$obj->user_agent()" Inherited, see \*(L"Accessors\*(R" in Net::OAuth2::Profile .SS "Actions" .IX Subsection "Actions" Extends \*(L"Actions\*(R" in Net::OAuth2::Profile. .ie n .IP "$obj\->\fBauthorize\fR(%options)" 4 .el .IP "\f(CW$obj\fR\->\fBauthorize\fR(%options)" 4 .IX Item "$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. .Sp Only the most common \f(CW%options\fR are listed... there may be more: read the docs on what your server expects. .Sp .Vb 5 \& \-Option \-\-Default \& client_id new(client_id) \& response_type \*(Aqcode\*(Aq \& scope undef \& state undef .Ve .RS 4 .IP "client_id => \s-1STRING\s0" 2 .IX Item "client_id => STRING" .PD 0 .IP "response_type => \s-1STRING\s0" 2 .IX Item "response_type => STRING" .IP "scope => \s-1STRING\s0" 2 .IX Item "scope => STRING" .IP "state => \s-1STRING\s0" 2 .IX Item "state => STRING" .RE .RS 4 .PD .Sp example: .Sp .Vb 1 \& my $auth = Net::OAuth2::Profile::WebServer\->new(...); \& \& # From the Plack demo, included in this distribution (on CPAN) \& get \*(Aq/get\*(Aq => sub { redirect $auth\->authorize }; \& \& # In generic HTTP, see method authorize_response \& use HTTP::Status \*(AqHTTP_TEMPORARY_REDIRECT\*(Aq; # 307 \& print HTTP::Response\->new \& ( HTTP_TEMPORARY_REDIRECT => \*(AqGet authorization grant\*(Aq \& , [ Location => $auth\->authorize ] \& )\->as_string; .Ve .RE .ie n .IP "$obj\->\fBauthorize_response\fR( [$request] )" 4 .el .IP "\f(CW$obj\fR\->\fBauthorize_response\fR( [$request] )" 4 .IX Item "$obj->authorize_response( [$request] )" Convenience wrapper around \fIauthorize()\fR, to produce a complete HTTP::Response object to be sent back. .ie n .IP "$obj\->\fBget_access_token\fR(\s-1CODE,\s0 %options)" 4 .el .IP "\f(CW$obj\fR\->\fBget_access_token\fR(\s-1CODE,\s0 \f(CW%options\fR)" 4 .IX Item "$obj->get_access_token(CODE, %options)" .Vb 3 \& \-Option \-\-Default \& client_id new(client_id) \& client_secret new(client_secret) .Ve .RS 4 .IP "client_id => \s-1STRING\s0" 2 .IX Item "client_id => STRING" .PD 0 .IP "client_secret => \s-1STRING\s0" 2 .IX Item "client_secret => STRING" .RE .RS 4 .RE .ie n .IP "$obj\->\fBupdate_access_token\fR($token, %options)" 4 .el .IP "\f(CW$obj\fR\->\fBupdate_access_token\fR($token, \f(CW%options\fR)" 4 .IX Item "$obj->update_access_token($token, %options)" .PD Ask the server for a new token. You may pass additional \f(CW%options\fR as pairs. However, this method is often triggered automatically, in which case you can to use the \f(CW\*(C`refresh_token_params\*(C'\fR option of \fInew()\fR. .Sp example: .Sp .Vb 2 \& $auth\->update_access_token($token); \& $token\->refresh; # nicer .Ve .SS "Helpers" .IX Subsection "Helpers" Extends \*(L"Helpers\*(R" in Net::OAuth2::Profile. .ie n .IP "$obj\->\fBadd_token\fR($request, $token, $scheme)" 4 .el .IP "\f(CW$obj\fR\->\fBadd_token\fR($request, \f(CW$token\fR, \f(CW$scheme\fR)" 4 .IX Item "$obj->add_token($request, $token, $scheme)" Inherited, see \*(L"Helpers\*(R" in Net::OAuth2::Profile .ie n .IP "$obj\->\fBbuild_request\fR($method, $uri, $params)" 4 .el .IP "\f(CW$obj\fR\->\fBbuild_request\fR($method, \f(CW$uri\fR, \f(CW$params\fR)" 4 .IX Item "$obj->build_request($method, $uri, $params)" Inherited, see \*(L"Helpers\*(R" in Net::OAuth2::Profile .ie n .IP "$obj\->\fBparams_from_response\fR($response, $reason)" 4 .el .IP "\f(CW$obj\fR\->\fBparams_from_response\fR($response, \f(CW$reason\fR)" 4 .IX Item "$obj->params_from_response($response, $reason)" Inherited, see \*(L"Helpers\*(R" in Net::OAuth2::Profile .ie n .IP "$obj\->\fBsite_url\fR( <$uri|$path>, $params )" 4 .el .IP "\f(CW$obj\fR\->\fBsite_url\fR( <$uri|$path>, \f(CW$params\fR )" 4 .IX Item "$obj->site_url( <$uri|$path>, $params )" Inherited, see \*(L"Helpers\*(R" in Net::OAuth2::Profile .SH "DETAILS" .IX Header "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. .SS "The process" .IX Subsection "The process" The client side of the process has three steps, nicely described in .IP "1. Send an authorization request to resource owner" 4 .IX Item "1. Send an authorization request to resource owner" It needs a \f(CW\*(C`client_id\*(C'\fR: usually the name of the service where you want get access to. The answer is a redirect, based on the \f(CW\*(C`redirection_uri\*(C'\fR which you usually pass on. Additional \f(CW\*(C`scope\*(C'\fR and \f(CW\*(C`state\*(C'\fR parameters can be needed or useful. The redirect will provide you with (amongst other things) a \f(CW\*(C`code\*(C'\fR parameter. .IP "2. Translate the code into an access token" 4 .IX Item "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. .IP "3. Address the protected resource" 4 .IX Item "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. .SS "Saving the token" .IX Subsection "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. .PP Let's discuss the three approaches. .PP \fIno saving\fR .IX Subsection "no saving" .PP The Plack example contained in the \s-1CPAN\s0 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. .PP \fIautomatic saving\fR .IX Subsection "automatic saving" .PP When your own code is imperative: .PP .Vb 4 \& my $auth = Net::OAuth2::Profile::WebServer\->new \& ( ... \& , auto_save => \e&save_session \& ); \& \& sub save_session($$) \& { my ($profile, $token) = @_; \& ... \& } .Ve .PP When your own code is object oriented: .PP .Vb 7 \& sub init(...) \& { my ($self, ...) = @_; \& my $auth = Net::OAuth2::Profile::WebServer\->new \& ( ... \& , auto_save => sub { $self\->save_session(@_) } \& ); \& } \& \& sub save_session($$) \& { my ($self, $profile, $token) = @_; \& ... \& } .Ve .PP \fIexplicit saving\fR .IX Subsection "explicit saving" .PP In this case, do not use new(auto_save). .SH "SEE ALSO" .IX Header "SEE ALSO" This module is part of Net\-OAuth2 distribution version 0.63, built on January 18, 2016. Website: \fIhttp://perl.overmeer.net\fR. .SH "COPYRIGHTS" .IX Header "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. .PP Copyrights 2011\-12 by Keith Grennan. .PP This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See \fIhttp://www.perl.com/perl/misc/Artistic.html\fR