.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" 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 >0, 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 "WWW::OAuth 3pm"
.TH WWW::OAuth 3pm "2022-12-06" "perl v5.36.0" "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"
WWW::OAuth \- Portable OAuth 1.0 authentication
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use WWW::OAuth;
\& 
\& my $oauth = WWW::OAuth\->new(
\&   client_id => $client_id,
\&   client_secret => $client_secret,
\&   token => $token,
\&   token_secret => $token_secret,
\& );
\& 
\& # Just retrieve authorization header
\& my $auth_header = $oauth\->authorization_header($http_request, { oauth_callback => $url });
\& $http_request\->header(Authorization => $auth_header);
\& 
\& # HTTP::Tiny
\& use HTTP::Tiny;
\& my $res = $oauth\->authenticate(Basic => { method => \*(AqGET\*(Aq, url => $url })
\&   \->request_with(HTTP::Tiny\->new);
\& 
\& # HTTP::Request
\& use HTTP::Request::Common;
\& use LWP::UserAgent;
\& my $res = $oauth\->authenticate(GET $url)\->request_with(LWP::UserAgent\->new);
\& 
\& # Mojo::Message::Request
\& use Mojo::UserAgent;
\& my $tx = $ua\->build_tx(get => $url);
\& $tx = $oauth\->authenticate($tx\->req)\->request_with(Mojo::UserAgent\->new);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
WWW::OAuth implements OAuth 1.0 request authentication according to
\&\s-1RFC 5849\s0 <http://tools.ietf.org/html/rfc5849> (sometimes referred to as OAuth
1.0A). It does not implement the user agent requests needed for the complete
OAuth 1.0 authorization flow; it only prepares and signs requests, leaving the
rest up to your application. It can authenticate requests for
LWP::UserAgent, Mojo::UserAgent, HTTP::Tiny, and can be extended to
operate on other types of requests.
.PP
Some user agents can be configured to automatically authenticate each request
with a WWW::OAuth object.
.PP
.Vb 3
\& # LWP::UserAgent
\& my $ua = LWP::UserAgent\->new;
\& $ua\->add_handler(request_prepare => sub { $oauth\->authenticate($_[0]) });
\& 
\& # Mojo::UserAgent
\& my $ua = Mojo::UserAgent\->new;
\& $ua\->on(start => sub { $oauth\->authenticate($_[1]\->req) });
.Ve
.SH "RETRIEVING ACCESS TOKENS"
.IX Header "RETRIEVING ACCESS TOKENS"
The process of retrieving access tokens and token secrets for authorization on
behalf of a user may differ among various APIs, but it follows this general
format (error checking is left as an exercise to the reader):
.PP
.Vb 8
\& use WWW::OAuth;
\& use WWW::OAuth::Util \*(Aqform_urldecode\*(Aq;
\& use HTTP::Tiny;
\& my $ua = HTTP::Tiny\->new;
\& my $oauth = WWW::OAuth\->new(
\&   client_id => $client_id,
\&   client_secret => $client_secret,
\& );
\& 
\& # Request token request
\& my $res = $oauth\->authenticate({ method => \*(AqPOST\*(Aq, url => $request_token_url },
\&   { oauth_callback => $callback_url })\->request_with($ua);
\& my %res_data = @{form_urldecode $res\->{content}};
\& my ($request_token, $request_secret) = @res_data{\*(Aqoauth_token\*(Aq,\*(Aqoauth_token_secret\*(Aq};
.Ve
.PP
Now, the returned request token must be used to construct a \s-1URL\s0 for the user to
go to and authorize your application. The exact method differs by \s-1API.\s0 The user
will usually be redirected to the \f(CW$callback_url\fR passed earlier after
authorizing, with a verifier token that can be used to retrieve the access
token and secret.
.PP
.Vb 7
\& # Access token request
\& $oauth\->token($request_token);
\& $oauth\->token_secret($request_secret);
\& my $res = $oauth\->authenticate({ method => \*(AqPOST\*(Aq, url => $access_token_url },
\&   { oauth_verifier => $verifier_token })\->request_with($ua);
\& my %res_data = @{form_urldecode $res\->{content}};
\& my ($access_token, $access_secret) = @res_data{\*(Aqoauth_token\*(Aq,\*(Aqoauth_token_secret\*(Aq};
.Ve
.PP
Finally, the access token and secret can now be stored and used to authorize
your application on behalf of this user.
.PP
.Vb 2
\& $oauth\->token($access_token);
\& $oauth\->token_secret($access_secret);
.Ve
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
WWW::OAuth implements the following attributes.
.SS "client_id"
.IX Subsection "client_id"
.Vb 2
\& my $client_id = $oauth\->client_id;
\& $oauth        = $oauth\->client_id($client_id);
.Ve
.PP
Client \s-1ID\s0 used to identify application (sometimes called an \s-1API\s0 key or consumer
key). Required for all requests.
.SS "client_secret"
.IX Subsection "client_secret"
.Vb 2
\& my $client_secret = $oauth\->client_secret;
\& $oauth            = $oauth\->client_secret($client_secret);
.Ve
.PP
Client secret used to authenticate application (sometimes called an \s-1API\s0 secret
or consumer secret). Required for all requests.
.SS "token"
.IX Subsection "token"
.Vb 2
\& my $token = $oauth\->token;
\& $oauth    = $oauth\->token($token);
.Ve
.PP
Request or access token used to identify resource owner. Leave undefined for
temporary credentials requests (request token requests).
.SS "token_secret"
.IX Subsection "token_secret"
.Vb 2
\& my $token_secret = $oauth\->token_secret;
\& $oauth           = $oauth\->token_secret($token_secret);
.Ve
.PP
Request or access token secret used to authenticate on behalf of resource
owner. Leave undefined for temporary credentials requests (request token
requests).
.SS "signature_method"
.IX Subsection "signature_method"
.Vb 2
\& my $method = $oauth\->signature_method;
\& $oauth     = $oauth\->signature_method($method);
.Ve
.PP
Signature method, can be \f(CW\*(C`PLAINTEXT\*(C'\fR, \f(CW\*(C`HMAC\-SHA1\*(C'\fR, \f(CW\*(C`RSA\-SHA1\*(C'\fR, or a custom
signature method. For \f(CW\*(C`RSA\-SHA1\*(C'\fR or custom signature methods, a \*(L"signer\*(R"
must be provided. Defaults to \f(CW\*(C`HMAC\-SHA1\*(C'\fR.
.SS "signer"
.IX Subsection "signer"
.Vb 6
\& my $signer = $oauth\->signer;
\& $oauth     = $oauth\->signer(sub {
\&   my ($base_str, $client_secret, $token_secret) = @_;
\&   ...
\&   return $signature;
\& });
.Ve
.PP
Coderef which implements the \*(L"signature_method\*(R". A default signer is
provided for signature methods \f(CW\*(C`PLAINTEXT\*(C'\fR and \f(CW\*(C`HMAC\-SHA1\*(C'\fR; this attribute is
required for other signature methods. For signature method \f(CW\*(C`RSA\-SHA1\*(C'\fR, this
attribute may also be an object which has a \f(CW\*(C`sign\*(C'\fR method like
Crypt::OpenSSL::RSA.
.PP
The signer is passed the computed signature base string, the client secret, and
(if present) the token secret, and must return the signature string.
.SH "METHODS"
.IX Header "METHODS"
WWW::OAuth implements the following methods.
.SS "authenticate"
.IX Subsection "authenticate"
.Vb 3
\& $container = $oauth\->authenticate($container, \e%oauth_params);
\& my $container = $oauth\->authenticate($http_request, \e%oauth_params);
\& my $container = $oauth\->authenticate(Basic => { method => \*(AqGET\*(Aq, url => $url }, \e%oauth_params);
.Ve
.PP
Wraps the \s-1HTTP\s0 request in a container with \*(L"oauth_request\*(R" in WWW::OAuth::Util,
then sets the Authorization header using \*(L"authorization_header\*(R" to sign the
request for OAuth 1.0. An optional hashref of OAuth parameters will be passed
through to \*(L"authorization_header\*(R". Returns the container object.
.SS "authorization_header"
.IX Subsection "authorization_header"
.Vb 3
\& my $auth_header = $oauth\->authorization_header($container, \e%oauth_params);
\& my $auth_header = $oauth\->authorization_header($http_request, \e%oauth_params);
\& my $auth_header = $oauth\->authorization_header(Basic => { method => \*(AqGET\*(Aq, url => $url }, \e%oauth_params);
.Ve
.PP
Forms an OAuth 1.0 signed Authorization header for the passed request. As in
\&\*(L"authenticate\*(R", the request may be specified in any form accepted by
\&\*(L"oauth_request\*(R" in WWW::OAuth::Util. OAuth protocol parameters (starting with
\&\f(CW\*(C`oauth_\*(C'\fR or the special parameter \f(CW\*(C`realm\*(C'\fR) may be optionally specified in a
hashref and will override any generated protocol parameters of the same name
(they should not be present in the request \s-1URL\s0 or body parameters). Returns the
signed header value.
.SH "HTTP REQUEST CONTAINERS"
.IX Header "HTTP REQUEST CONTAINERS"
Request containers provide a unified interface for \*(L"authenticate\*(R" to parse
and update \s-1HTTP\s0 requests. They must perform the Role::Tiny role
WWW::OAuth::Request. Custom container classes can be instantiated
directly or via \*(L"oauth_request\*(R" in WWW::OAuth::Util.
.SS "Basic"
.IX Subsection "Basic"
WWW::OAuth::Request::Basic contains the request attributes directly, for
user agents such as HTTP::Tiny that do not use request objects.
.SS "HTTP_Request"
.IX Subsection "HTTP_Request"
WWW::OAuth::Request::HTTP_Request wraps a HTTP::Request object, which
is compatible with several user agents including LWP::UserAgent,
HTTP::Thin, and Net::Async::HTTP.
.SS "Mojo"
.IX Subsection "Mojo"
WWW::OAuth::Request::Mojo wraps a Mojo::Message::Request object,
which is used by Mojo::UserAgent via Mojo::Transaction.
.SH "BUGS"
.IX Header "BUGS"
Report any issues on the public bugtracker.
.SH "AUTHOR"
.IX Header "AUTHOR"
Dan Book <dbook@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is Copyright (c) 2015 by Dan Book.
.PP
This is free software, licensed under:
.PP
.Vb 1
\&  The Artistic License 2.0 (GPL Compatible)
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Net::OAuth, Mojolicious::Plugin::OAuth2