OAuth:...Handler(3pm)

💖 NAME 💖

okay so bestie, meet OAuth::Lite2::Server::DataHandler — in the manual it's filed under OAuth:...Handler(3pm), which is giving "the title got truncated by the column width" energy, but we move. it's the base class that specifies the interface for the data handler for your service. it's a blueprint, not a vibe you instantiate directly. periodt.

---

🎀 DESCRIPTION 🎀

this thing right here is the glue that connects the OAuth::Lite2 library to your service. 🫶

it specifies an interface to handle data stored in your application. and listen, this is not optional-decorative — you must inherit this and implement the subroutines according to the interface contract. it's a contract, bestie, not a suggestion. sign it or don't show up. 💅

---

✨ SYNOPSIS ✨

package YourDataHandler;

use strict;
use warnings;

use parent 'OAuth::Lite2::Server::DataHandler';

that's it. that's the whole inheritance moment. <rainbow>slay.</rainbow> 🌈

---

🦋 METHODS 🦋

💫 init

this method can be implemented to initialize your subclass. you can — it's not mandatory, it's just there for when you need a little setup moment. ✨

---

👑 INTERFACES 👑

okay this is the main event, the whole reason we're here. every single one of these, no skipping. 🔥

💌 request

Returns Plack::Request object.

💌 validate_client( $client_id, $client_secret, $grant_type )

this one is used by Token Endpoint, and heads up — it gets called all the time, regardless of the grant_type setting. no days off. 😤

this is the place to check if the client_id and client credentials are valid, and also whether the client is allowed to use this grant_type.

if all the checks are successful, return 1. otherwise return 0.

💌 get_user_id( $username, $password )

used by Token Endpoint, specifically when the requested grant_type is 'password'.

you get the username and password, and it's on you to check if the credentials are valid or not.

if the checks are successful, return the user's identifier — and that identifier is managed by your service, so it's your own little thing, you invented it, own it. 💅

💌 create_or_update_auth_info( %params )

create and save new authorization info. should return OAuth::Lite2::Model::AuthInfo object.

💌 create_or_update_access_token( %params )

create and save new access token. should return OAuth::Lite2::Model::AccessToken object.

💌 get_auth_info_by_code( $code )

this one kicks in when the client obtains an access_token using an authorization-code that was issued by the server with the user's authorization. so, the whole consent-flow moment.

the Web Server Profile requires this interface. required. not optional. do not skip it. 🚨

should return OAuth::Lite2::Model::AuthInfo object.

💌 get_auth_info_by_refresh_token( $refresh_token )

used when the access_token is refreshed. the little re-up moment. 🧚

should return OAuth::Lite2::Model::AuthInfo object.

💌 get_access_token( $token )

used on a protected resource endpoint. see Plack::Middleware::Auth::OAuth2::ProtectedResource.

returns an access token which allows access to the protected attributes. should return OAuth::Lite2::Model::AccessToken object.

💌 get_auth_info_by_id( $auth_id )

used on a protected resource endpoint. see Plack::Middleware::Auth::OAuth2::ProtectedResource.

called after the get_access_token method. it returns authorization-info that is related to the $auth_id and access-token.

should return OAuth::Lite2::Model::AuthInfo object.

💌 validate_client_by_id( $client_id )

this hook is called on a protected resource endpoint. see Plack::Middleware::Auth::OAuth2::ProtectedResource.

after checking if the token is valid, you can check if the client related to the token is valid in this method.

if the validation of the client_id is successful, return 1. otherwise return 0.

💌 validate_user_by_id( $user_id )

also a hook called on a protected resource endpoint. see Plack::Middleware::Auth::OAuth2::ProtectedResource.

after checking if the token is valid, you can check if the user related to the token is valid in this method.

if the validation of the user is successful, return 1. otherwise return 0.

💌 get_group_id_by_client_id ( $client_id )

if client_id has group_id, return it. short and sweet, we love a low-effort icon. 💜

💌 validate_grouping_scope ( $client_id, $scope )

if the scope value is allowed, return 1.

💌 create_server_state ( $client_id )

create and save OAuth::Lite2::Model::ServerState object.

💌 get_user_id_by_external_assertion ( %params )

used by Token Endpoint, and this time when the requested grant_type is 'federation-bearer'. fancy. 🦋

you get the external service assertion and it's on you to check if the related external service account is valid or not.

if the checks are successful, return the user's identifier — again, managed by your service. your house, your rules. 👑

---

🌸 AUTHOR 🌸

Ryo Ito, <ritou.06@gmail.com>

Lyo Kato, <lyo.kato@gmail.com>

---

💜 COPYRIGHT AND LICENSE 💜

Copyright (C) 2010 by Lyo Kato

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.

---

and that's the whole page, bestie 🎀 shoutout to the perl v5.36.0 docs and that 2023-07-01 timestamp at the bottom — go off, icon, thanks for the lore. mwah. 💋✨