Les modules de validation OAuth implémentent leur fonctionnalité en définissant un ensemble de fonctions callbacks. Le serveur les appelle selon les besoins pour traiter la demande d'authentification de l'utilisateur.
La fonction callback startup_cb
est appelée immédiatement après
le chargement du module. Cette fonction peut être utilisée pour initialiser un état
local et effectuer d'autres actions d'initialisation si nécessaire.
Si le module de validation conserve un état, il peut l'enregistrer dans
state->private_data
.
typedef void (*ValidatorStartupCB) (ValidatorModuleState *state);
La fonction callback validate_cb
est exécutée lors de l'échange OAuth
lorsqu'un utilisateur tente de s'authentifier à l'aide d'OAuth. Tout état défini
dans des appels précédents sera disponible via state->private_data
.
typedef bool (*ValidatorValidateCB) (const ValidatorModuleState *state, const char *token, const char *role, ValidatorModuleResult *result);
token
contiendra le jeton Bearer à valider.
PostgreSQL garantit que le jeton est syntaxiquement valide,
mais aucune autre validation n'a encore été effectuée.
role
contiendra le rôle avec lequel l'utilisateur
souhaite se connecter. La fonction doit renseigner les paramètres de sortie
dans la structure result
, qui est définie comme suit :
typedef struct ValidatorModuleResult { bool authorized; char *authn_id; } ValidatorModuleResult;
La connexion ne se poursuivra que si le module définit
result->authorized
à true
.
Pour authentifier l'utilisateur, le nom d'utilisateur authentifié (déterminé
via le jeton) doit être alloué avec palloc
et renvoyé
dans le champ result->authn_id
.
Alternativement, result->authn_id
peut être défini à
NULL
si le jeton est valide, mais que l'identité de l'utilisateur
associée ne peut pas être déterminée.
Un validateur peut retourner false
pour signaler une erreur interne,
dans ce cas, les autres paramètres du résultat sont ignorés et la connexion échoue.
Sinon, le validateur doit retourner true
pour indiquer
que le jeton a été traité et qu'une décision d'autorisation a été prise.
Le comportement après le retour de validate_cb
dépend de la
configuration HBA spécifique. Normalement, le nom d'utilisateur dans
result->authn_id
doit correspondre exactement au rôle
avec lequel l'utilisateur tente de se connecter (ce comportement peut être modifié
à l'aide d'une table de correspondance d'utilisateurs). Mais lorsqu'on utilise
une règle HBA avec delegate_ident_mapping
activé,
PostgreSQL ne vérifiera pas la valeur de
result->authn_id
; dans ce cas, il revient
au validateur de s'assurer que le jeton confère les privilèges nécessaires
pour que l'utilisateur puisse se connecter avec le
role
spécifié.
La fonction callback shutdown_cb
est appelée lorsque le processus
backend associé à la connexion se termine. Si le module de validation a
alloué de la mémoire ou d'autres ressources, cette fonction doit les libérer afin
d'éviter les fuites de mémoire.
typedef void (*ValidatorShutdownCB) (ValidatorModuleState *state);