.\" 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
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "OAuth::Lite2::Server::DataHandler 3pm"
.TH OAuth::Lite2::Server::DataHandler 3pm "2023-07-01" "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"
OAuth::Lite2::Server::DataHandler \- Base class that specifies interface for data handler for your service.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This connects OAuth::Lite2 library to your service.
.PP
This specifies an interface to handle data stored in your application. You must
inherit this and implement the subroutines according to the interface contract.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    package YourDataHandler;
\&    
\&    use strict;
\&    use warnings;
\&
\&    use parent \*(AqOAuth::Lite2::Server::DataHandler\*(Aq;
.Ve
.SH "METHODS"
.IX Header "METHODS"
.SS "init"
.IX Subsection "init"
This method can be implemented to initialize your subclass.
.SH "INTERFACES"
.IX Header "INTERFACES"
.SS "request"
.IX Subsection "request"
Returns <Plack::Request> object.
.ie n .SS "validate_client( $client_id, $client_secret, $grant_type )"
.el .SS "validate_client( \f(CW$client_id\fP, \f(CW$client_secret\fP, \f(CW$grant_type\fP )"
.IX Subsection "validate_client( $client_id, $client_secret, $grant_type )"
This method is used by Token Endpoint. This method will be called all the time,
regardless of the grant_type setting.
.PP
This is the place to check if the client_id and client credentials are valid,
as well as checking if the client is allowed to use this grant_type.
.PP
If all the checks are successful, return 1. Otherwise return 0.
.ie n .SS "get_user_id( $username, $password )"
.el .SS "get_user_id( \f(CW$username\fP, \f(CW$password\fP )"
.IX Subsection "get_user_id( $username, $password )"
This method is used by Token Endpoint, when requested grant_type is 'password'.
.PP
The username and password are provided. You should check if the credentials are
valid or not.
.PP
If the checks are successful, return the user's identifier. The user's
identifier is managed by your service.
.ie n .SS "create_or_update_auth_info( %params )"
.el .SS "create_or_update_auth_info( \f(CW%params\fP )"
.IX Subsection "create_or_update_auth_info( %params )"
Create and save new authorization info.
Should return OAuth::Lite2::Model::AuthInfo object.
.ie n .SS "create_or_update_access_token( %params )"
.el .SS "create_or_update_access_token( \f(CW%params\fP )"
.IX Subsection "create_or_update_access_token( %params )"
Create and save new access token.
Should return OAuth::Lite2::Model::AccessToken object.
.ie n .SS "get_auth_info_by_code( $code )"
.el .SS "get_auth_info_by_code( \f(CW$code\fP )"
.IX Subsection "get_auth_info_by_code( $code )"
This method is used when the client obtains an access_token using an
authorization-code that was issued by server with user's authorization.
.PP
The Web Server Profile requires this interface.
.PP
Should return OAuth::Lite2::Model::AuthInfo object.
.ie n .SS "get_auth_info_by_refresh_token( $refresh_token )"
.el .SS "get_auth_info_by_refresh_token( \f(CW$refresh_token\fP )"
.IX Subsection "get_auth_info_by_refresh_token( $refresh_token )"
This method is used when the access_token is refreshed.
.PP
Should return OAuth::Lite2::Model::AuthInfo object.
.ie n .SS "get_access_token( $token )"
.el .SS "get_access_token( \f(CW$token\fP )"
.IX Subsection "get_access_token( $token )"
This interface is used on a protected resource endpoint.
See Plack::Middleware::Auth::OAuth2::ProtectedResource.
.PP
Returns an access token which allows access to the protected attributes.
Should return OAuth::Lite2::Model::AccessToken object.
.ie n .SS "get_auth_info_by_id( $auth_id )"
.el .SS "get_auth_info_by_id( \f(CW$auth_id\fP )"
.IX Subsection "get_auth_info_by_id( $auth_id )"
This method is used on a protected resource endpoint.
See Plack::Middleware::Auth::OAuth2::ProtectedResource.
.PP
This method is called after the get_access_token method. Returns
authorization-info that is related to the \f(CW$auth_id\fR and access-token.
.PP
Should return OAuth::Lite2::Model::AuthInfo object.
.ie n .SS "validate_client_by_id( $client_id )"
.el .SS "validate_client_by_id( \f(CW$client_id\fP )"
.IX Subsection "validate_client_by_id( $client_id )"
This hook is called on protected resource endpoint.
See Plack::Middleware::Auth::OAuth2::ProtectedResource.
.PP
After checking if the token is valid, you can check if the client related the
token is valid in this method.
.PP
If the validation of the client_id is successful, return 1. Otherwise return 0.
.ie n .SS "validate_user_by_id( $user_id )"
.el .SS "validate_user_by_id( \f(CW$user_id\fP )"
.IX Subsection "validate_user_by_id( $user_id )"
This hook is called on protected resource endpoint.
See Plack::Middleware::Auth::OAuth2::ProtectedResource.
.PP
After checking if token is valid, you can check if the user related the token
is valid in this method.
.PP
If the validation of the user is successful, return 1. Otherwise return 0.
.ie n .SS "get_group_id_by_client_id ( $client_id )"
.el .SS "get_group_id_by_client_id ( \f(CW$client_id\fP )"
.IX Subsection "get_group_id_by_client_id ( $client_id )"
If client_id has group_id, return it.
.ie n .SS "validate_grouping_scope ( $client_id, $scope )"
.el .SS "validate_grouping_scope ( \f(CW$client_id\fP, \f(CW$scope\fP )"
.IX Subsection "validate_grouping_scope ( $client_id, $scope )"
If scope value is allowed, return 1.
.ie n .SS "create_server_state ( $client_id )"
.el .SS "create_server_state ( \f(CW$client_id\fP )"
.IX Subsection "create_server_state ( $client_id )"
Create and save OAuth::Lite2::Model::ServerState object.
.ie n .SS "get_user_id_by_external_assertion ( %params )"
.el .SS "get_user_id_by_external_assertion ( \f(CW%params\fP )"
.IX Subsection "get_user_id_by_external_assertion ( %params )"
This method is used by Token Endpoint, when requested grant_type is 'federation\-bearer'.
.PP
The external service assertion is provided. You should check if the related external service account is valid or not.
If the checks are successful, return the user's identifier. The user's identifier is managed by your service.
.SH "AUTHOR"
.IX Header "AUTHOR"
Ryo Ito, <ritou.06@gmail.com>
.PP
Lyo Kato, <lyo.kato@gmail.com>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2010 by Lyo Kato
.PP
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.8 or,
at your option, any later version of Perl 5 you may have available.