| Current Path : /usr/OAuth-Lite-1.32/blib/man3/ |
| Current File : //usr/OAuth-Lite-1.32/blib/man3/OAuth::Lite::Server::mod_perl2.3pm |
.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.13)
.\"
.\" 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" ''
'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.
.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.el \{\
. de IX
..
.\}
.\" ========================================================================
.\"
.IX Title "OAuth::Lite::Server::mod_perl2 3"
.TH OAuth::Lite::Server::mod_perl2 3 "2014-01-04" "perl v5.10.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"
OAuth::Lite::Server::mod_perl2 \- mod_perl2 OAuth server
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Inherit this class, build your service with mod_perl2.
For example, write MyServiceWithOAuth.pm
And the source-code of OAuth::Lite::Server::Test::Echo is nice example.
See it.
.PP
.Vb 2
\& package MyServiceWithOAuth;
\& use base \*(AqOAuth::Lite::Server::mod_perl2\*(Aq;
\&
\& sub init {
\& my $self = shift;
\& $self\->oauth\->allow_extra_params(qw/file size/);
\& $self\->oauth\->support_signature_methods(qw/HMAC\-SHA1 PLAINTEXT/);
\& }
\&
\& sub get_request_token_secret {
\& my ($self, $token_string) = @_;
\& my $token = MyDB::Scheme\->resultset(\*(AqRequestToken\*(Aq)\->find($token_string);
\& unless ($token
\& && $token\->is_authorized_by_user
\& && !$token\->is_exchanged_to_access_token
\& && !$token\->is_expired) {
\& return $self\->error(q{Invalid token});
\& }
\& return $token\->secret;
\& }
\&
\& sub get_access_token_secret {
\& my ($self, $token_string, $consumer_key) = @_;
\& my $token = MyDB::Scheme\->resultset(\*(AqAccessToken\*(Aq)\->find($token_string);
\& unless ($token
\& && !$token\->is_expired) {
\& return $self\->error(q{Invalid token});
\& }
\& return $token\->secret;
\& }
\&
\& sub get_consumer_secret {
\& my ($self, $consumer_key) = @_;
\& my $consumer = MyDB::Shceme\->resultset(\*(AqConsumer\*(Aq)\->find($consumer_key);
\& unless ($consumer
\& && $consumer\->is_valid) {
\& return $self\->error(q{Inalid consumer_key});
\& }
\& return $consumer\->secret;
\& }
\&
\& sub publish_request_token {
\& my ($self, $consumer_key, $callback_url) = @_;
\& my $token = OAuth::Lite::Token\->new_random;
\& MyDB::Scheme\->resultset(\*(AqRequestToken\*(Aq)\->create({
\& token => $token\->token,
\& secret => $token\->secret,
\& realm => $self\->realm,
\& consumer_key => $consumer_key,
\& expired_on => \*(Aq\*(Aq,
\& callback => $callback_url,
\& });
\& return $token;
\& }
\&
\& sub publish_access_token {
\& my ($self, $consumer_key, $request_token_string, $verifier) = @_;
\& my $request_token = MyDB::Scheme\->resultset(\*(AqRequestToken\*(Aq)\->find($request_token_string);
\& unless ($request_token
\& && $request_token\->is_authorized_by_user
\& && !$request_token\->is_exchanged_to_access_token
\& && !$request_token\->is_expired
\& && $request_token\->has_verifier
\& && $request_token\->verifier eq $verifier) {
\& return $self\->error(q{Invalid token});
\& }
\& my $access_token = OAuth::Lite::Token\->new_random;
\& MyDB::Scheme\->resultset(\*(AqAccessToken\*(Aq)\->create({
\& token => $request_token\->token,
\& realm => $self\->realm,
\& secret => $request_token\->secret,
\& consumer_key => $consumer_key,
\& author => $request_token\->author,
\& expired_on => \*(Aq\*(Aq,
\& });
\&
\& $request_token\->is_exchanged_to_access_token(1);
\& $request_token\->update();
\&
\& return $access_token;
\& }
\&
\& sub check_nonce_and_timestamp {
\& my ($self, $consumer_key, $nonce, $timestamp) = @_;
\& my $request_log = MyDB::Scheme\->resultset(\*(AqRequestLog\*(Aq);
\& # check against replay\-attack
\& my $count = $request_log\->count({
\& consumer_key => $consumer_key,
\& \-nest => [
\& nonce => $nonce,
\& timestamp => { \*(Aq>\*(Aq => $timestamp },
\& ],
\& });
\& if ($count > 0) {
\& return $self\->error(q{Invalid timestamp or consumer});
\& }
\& # save new request log.
\& $request_log\->create({
\& consumer_key => $consumer_key,
\& nonce => $nonce,
\& timestamp => $timestamp,
\& });
\& return 1;
\& }
\&
\& sub service {
\& my $self = shift;
\& }
.Ve
.PP
in httpd.conf
.PP
.Vb 2
\& PerlSwitches \-I/var/www/MyApp/lib
\& PerlModule MyServiceWithOAuth
\&
\& <VirtualHost *>
\&
\& ServerName api.example.com
\& DocumentRoot /var/www/MyApp/root
\&
\& PerlSetVar Realm "http://api.example.com/picture"
\&
\& <Location /picture/request_token>
\& SetHandler perl\-script
\& PerlSetVar Mode REQUEST_TOKEN
\& PerlResponseHandler MyServiceWithOAuth
\& </Location>
\&
\& <Location /picture/access_token>
\& SetHandler perl\-script
\& PerlSetVar Mode ACCESS_TOKEN
\& PerlResponseHandler MyServiceWithOAuth
\& </Location>
\&
\& <Location /picture/resource>
\& SetHandler perl\-script
\& PerlSetVar Mode PROTECTED_RESOURCE
\& PerlResponseHandler MyServiceWithOAuth
\& </Location>
\&
\& </VirtualHost>
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module is for mod_perl2 PerlResponseHandler, and allows you to
build services with OAuth easily.
.SH "TUTORIAL"
.IX Header "TUTORIAL"
All you have to do is to make a package inheritting this module,
and override some methods, and in httpd.conf file, write
three configuration, each configuration needs to be set Mode value.
The each value must be \s-1REQUEST_TOKEN\s0, \s-1ACCESS_TOKEN\s0, or \s-1PROTECTED_RESOURCE\s0.
And the Realm value is needed for each resource.
.PP
The methods you have to override is bellow.
.SH "METHODS YOU HAVE TO OVERRIDE"
.IX Header "METHODS YOU HAVE TO OVERRIDE"
.SS "init"
.IX Subsection "init"
In this method, you can do some initialization.
For example, set what signature method your service supports,
and what extra-param is allowed.
.PP
.Vb 5
\& sub init {
\& my $self = shift;
\& $self\->oauth\->support_signature_method(qw/HMAC\-SHA1 PLAINTEXT/);
\& $self\->oauth\->allow_extra_params(qw/file size/);
\& }
.Ve
.SS "get_request_token_secret($token_string)"
.IX Subsection "get_request_token_secret($token_string)"
In this method, you should check if the request-token-string is
valid, and returns token-secret value corresponds to the
token value passed as argument.
If the token is invalid, you should call 'error' method.
.ie n .SS "get_access_token_secret($token_string, $consumer_key)"
.el .SS "get_access_token_secret($token_string, \f(CW$consumer_key\fP)"
.IX Subsection "get_access_token_secret($token_string, $consumer_key)"
In this method, you should check if the access-token-string is
valid, and returns token-secret value corresponds to the
token value passed as argument.
If the token is invalid, you should call 'error' method.
.SS "get_consumer_secret($consumer_key)"
.IX Subsection "get_consumer_secret($consumer_key)"
In this method, you should check if the consumer_key is valid,
and returns consumer_secret value corresponds to the consumer_key
passed as argument.
If the consumer is invalid, you should call 'error' method.
.ie n .SS "check_nonce_and_timestamp($consumer_key, $nonce, $timestamp)"
.el .SS "check_nonce_and_timestamp($consumer_key, \f(CW$nonce\fP, \f(CW$timestamp\fP)"
.IX Subsection "check_nonce_and_timestamp($consumer_key, $nonce, $timestamp)"
Check passed nonce and timestamp.
Among requests the consumer send service-provider, there shouldn't be
same nonce, and new timestamp should be greater than old ones.
If they are valid, returns 1, or returns 0.
.ie n .SS "publish_request_token($consumer_key, $callback_url)"
.el .SS "publish_request_token($consumer_key, \f(CW$callback_url\fP)"
.IX Subsection "publish_request_token($consumer_key, $callback_url)"
Create new request-token, and save it,
and returns it as OAuth::Lite::Token object.
.ie n .SS "publish_access_token($consumer_key, $request_token_string, $verifier)"
.el .SS "publish_access_token($consumer_key, \f(CW$request_token_string\fP, \f(CW$verifier\fP)"
.IX Subsection "publish_access_token($consumer_key, $request_token_string, $verifier)"
If the passed request-token is valid,
create new access-token, and save it,
and returns it as OAuth::Lite::Token object.
And disables the exchanged request-token.
.ie n .SS "verify_requestor_approval($consumer_key, $requestor_id)"
.el .SS "verify_requestor_approval($consumer_key, \f(CW$requestor_id\fP)"
.IX Subsection "verify_requestor_approval($consumer_key, $requestor_id)"
When the request is for OpenSocial Reverse Phone Home,
Check if the requestor has already given approval to consumer
to access the requestor's data.
.SS "service"
.IX Subsection "service"
Handle protected resource.
This method should returns Apache2::Const::OK.
.PP
.Vb 6
\& sub service {
\& my $self = shift;
\& my $params = $self\->{params};
\& my $token_string = $params\->{oauth_token};
\& my $access_token = MyDB::Scheme\->resultset(\*(AqRequestToken\*(Aq)\->find($token_string);
\& my $user = $access_token\->author;
\&
\& my $resource = $user\->get_my_some_resource();
\&
\& $self\->request\->status(200);
\& $self\->request\->content_type(q{text/html; charset=utf\-8});
\& $self\->print($resource);
\& return Apache2::Const::OK;
\& }
.Ve
.SH "API"
.IX Header "API"
.SS "handler"
.IX Subsection "handler"
Trigger method as response handler.
.SS "new"
.IX Subsection "new"
Constructor
.SS "request"
.IX Subsection "request"
Returns Apache request object.
See Apache2::RequestRec, Apache2::RequestIO, and etc...
.PP
.Vb 1
\& $self\->request;
.Ve
.SS "realm"
.IX Subsection "realm"
The realm value you set in httpd.conf by PerlSetVar.
.SS "oauth"
.IX Subsection "oauth"
Returns l<OAuth::Lite::ServerUtil> object.
.SS "allow_extra_param"
.IX Subsection "allow_extra_param"
.SS "allow_extra_params"
.IX Subsection "allow_extra_params"
.SS "support_signature_method"
.IX Subsection "support_signature_method"
.SS "support_signature_methods"
.IX Subsection "support_signature_methods"
These methods are just only delegate methods.
For example,
.PP
.Vb 1
\& $self\->allow_extra_param(\*(Aqfoo\*(Aq);
.Ve
.PP
is same as
.PP
.Vb 1
\& $self\->oauth\->allow_extra_param(\*(Aqfoo\*(Aq);
.Ve
.SS "request_method"
.IX Subsection "request_method"
Request method (Upper Case).
When the raw request method is \s-1POST\s0 and X\-HTTP-Method-Override is define in header,
return the value of X\-HTTP-Method-Override.
.SS "request_uri"
.IX Subsection "request_uri"
Returns request uri
.SS "request_body"
.IX Subsection "request_body"
Requets body data when the request's http-method is \s-1POST\s0 or \s-1PUT\s0
.SS "set_authenticate_header"
.IX Subsection "set_authenticate_header"
Set proper 'WWW\-Authentication' response header
.SS "is_required_request_token"
.IX Subsection "is_required_request_token"
Check if current request requires request-token.
.SS "is_required_access_token"
.IX Subsection "is_required_access_token"
Check if current request requires access-token.
.SS "is_required_protected_resource"
.IX Subsection "is_required_protected_resource"
Check if current request requires protected-resource.
.SS "is_consumer_request"
.IX Subsection "is_consumer_request"
Chekc if the server accepts consumer-request and
the request is for protected resource without token.
.SS "is_reverse_phone_home"
.IX Subsection "is_reverse_phone_home"
Check if the server accepts open-social reverse-phone-home
and the requests is for protected resource without token.
.SS "xrds_location"
.IX Subsection "xrds_location"
If you want to support OAuth Discovery, you need to
prepare \s-1XRDS\s0 document, and set the location as XRDSLocation value.
See below.
.PP
.Vb 5
\& <Location /resource>
\& PerlSetVar Mode PROTECTED_RESOURCE
\& PerlSetVar XRDSLocation "http://myservice/discovery/xrdsdocument"
\& PerlResponseHandler MyServiceWithOAuth
\& </Location>
.Ve
.PP
Then you can get this url in your script.
.PP
.Vb 4
\& sub service {
\& my $self = shift;
\& my $xrds_location = $self\->xrds_location;
\& }
.Ve
.PP
But normalry all you have to do is write location on httpd.conf.
And \*(L"errout\*(R" method automatically put it into response header properly.
.SS "build_xrds"
.IX Subsection "build_xrds"
In case client send request which includes application/xrds+xml in Accept header,
if The server is set XRDSLocation as above, return resuponse with it in header.
But you can also directly return XRDS-Document.
.PP
Override build_xrds document.
.PP
.Vb 10
\& sub build_xrds {
\& my $self = shift;
\& my $xrds = q{
\& <?xml version="1.0" encoding="UTF\-8"?>
\& <XRDS xmlns="xri://$xrds">
\& ...
\& </XRDS>
\& };
\& return $xrds;
\& }
.Ve
.PP
If the server doesn't support both XRDSLocation and build_xrds overriding,
The server doesn't support OAuth Discovery.
.SS "accepts_consumer_request"
.IX Subsection "accepts_consumer_request"
You can adopt OAuth Consumer Request 1.0.
.PP
See http://oauth.googlecode.com/svn/spec/ext/consumer_request/1.0/drafts/1/spec.html
.PP
To adopt this spec, you have to set var 'AcceptConsumerRequest' on httpd.conf
.PP
.Vb 5
\& <Location /resource>
\& PerlSetVar Mode PROTECTED_RESOURCE
\& PerlSetVar AcceptConsumerRequest 1
\& PerlResponseHandler MyServiceWithOAuth
\& </Location>
.Ve
.PP
Then override service method for protected resource.
.PP
.Vb 3
\& sub service {
\& my $self = shift;
\& my $params = $self\->{params};
\&
\& my $resource_owner_id;
\&
\& if (exists $params\->{oauth_token}) {
\&
\& my $access_token_value = $params\->{oauth_token};
\& $resource_owner_id = $self\->get_user_id_of_access_token($access_token_value);
\&
\& } else {
\&
\& my $consumer_key = $params\->{oauth_consumer_key};
\& $resource_owner_id = $self\->get_user_id_of_consumer_developer($consumer_key);
\&
\& }
\&
\& my @resources = MyDB::Scheme\->resultset(\*(AqSomeResource\*(Aq)\->search({
\& user_id => $resource_owner_id,
\& });
\&
\& # output resource data in the manner your api defines.
\& ...
\&
\& return Apache2::Const::OK;
\&
\& }
.Ve
.SS "accepts_reverse_phone_home"
.IX Subsection "accepts_reverse_phone_home"
You can adopt OpenSocial Reverse Phone Home.
.PP
.Vb 5
\& <Location /resource>
\& PerlSetVar Mode PROTECTED_RESOURCE
\& PerlSetVar AcceptReversePhoneHome 1
\& PerlResponseHandler MyServiceWithOAuth
\& </Location>
.Ve
.SS "error"
.IX Subsection "error"
Class::ErrorHandler method.
In some check-method, when you find invalid request value,
call this method with error message and return it.
.PP
.Vb 7
\& sub check_nonce_and_timestamp {
\& my ($self, $consumer_key, $nonce, $timestamp) = @_;
\& if ($timestamp ...) {
\& return $self\->error(q{Invalid timestamp});
\& }
\& return 1;
\& }
.Ve
.SS "errstr"
.IX Subsection "errstr"
Class::ErrorHandler method.
You can get error message that you set with error method.
.PP
.Vb 4
\& my $valid = $self\->check_nonce_and_timestamp($consumer_key, $nonce, $timestamp);
\& if (!$valid) {
\& return $self\->errout(401, $self\->errstr);
\& }
.Ve
.SS "output(%params)"
.IX Subsection "output(%params)"
Simply output response.
You can set 3 params, code, type and content.
.PP
.Vb 5
\& return $self\->output(
\& code => 200,
\& type => \*(Aqtext/plain; charset=utf\-8\*(Aq
\& content => \*(Aqsuccess\*(Aq,
\& );
.Ve
.ie n .SS "errout($code, $message)"
.el .SS "errout($code, \f(CW$message\fP)"
.IX Subsection "errout($code, $message)"
Output error message. This returns Apache2::Const::OK,
so, don't forget 'return';
.PP
.Vb 1
\& return $self\->errout(400, q{Bad request});
.Ve
.PP
And you can override this and put some function into this process.
For example, logging.
.PP
.Vb 5
\& sub errout {
\& my ($self, $code, $message) = @_;
\& $self\->my_log_process($code, $message);
\& return $self\->SUPER::errout($code, $message);
\& }
\&
\& sub my_log_process {
\& my ($self, $code, $message) = @_;
\& warn ...
\& }
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
OAuth::Lite::ServerUtil
OAuth::Lite::Server::Test::Echo
.SH "AUTHOR"
.IX Header "AUTHOR"
Lyo Kato, \f(CW\*(C`lyo.kato _at_ gmail.com\*(C'\fR
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.8.6 or,
at your option, any later version of Perl 5 you may have available.
Copyright 2K16 - 2K18 Indonesian Hacker Rulez
;?>)