Remplace l'invite par défaut de l'utilisateur lors du flux client natif d'autorisation du périphérique. data pointe vers une instance de PGpromptOAuthDevice :

typedef struct _PGpromptOAuthDevice
{
    const char *verification_uri;   /* verification URI to visit */
    const char *user_code;          /* user code to enter */
    const char *verification_uri_complete;  /* optional combination of URI and
                                             * code, or NULL */
    int         expires_in;         /* seconds until user code expires */
} PGpromptOAuthDevice;

Le flux d'autorisation de périphérique OAuth qui peut être inclus dans libpq nécessite que l'utilisateur final visite une URL avec un navigateur puis saisisse un code qui permet à libpq de se connecter au serveur en leur nom. L'invite par défaut affiche seulement le verification_uri et le user_code sur la sortie des erreurs. Les implémentations de remplacement pourraient afficher cette information en utilisant toute autre méthode, par exemple avec une interface graphique.

Ce callback est seulement appelé lors du flux d'autorisation natif du périphérique. Si l'application installe un flux OAuth personnalisé ou que libpq n'était pas compilé avec le support du flux natif, ce type authdata ne sera pas utilisé.

Si un verification_uri_complete non NULL est fourni, il pourrait être utilisé en option pour une vérification non textuelle (par exemple en affichant un QR-code). L'URL et le code utilisateur devront toujours être affichés à l'utilisateur final dans ce cas car le code devra être manuellement confirmé par le fournisseur et l'URL laisse les utilisateurs continuer, même s'ils ne peuvent pas utiliser la méthode non textuelle. Pour plus d'informations, voir la section 3.3.1 dans la RFC 8628.

Ajoute une implémentation personnalisée d'un flux, remplaçant le flux natif s'il est installé. Le hook doit soit renvoyer directement un jeton du porteur pour la combinaison utilisateur/fournisseur/portée, si une est disponible sans blocage, soit configurer un callback asynchrone pour en récupérer un.

data pointe vers une instance de PGoauthBearerRequest, qui doit être remplie par cette implémentation :

typedef struct PGoauthBearerRequest
{
    /* Entrées du Hook (constantes pour tous les appels) */
    const char *openid_configuration; /* URL de découverte OIDC */
    const char *scope;                /* portée(s) requise(s), ou NULL */

    /* Sorties du Hook */

    /* Callback implémentant un flux personnalisé OAuth asynchrone. */
    PostgresPollingStatusType (*async) (PGconn *conn,
                                        struct PGoauthBearerRequest *request,
                                        SOCKTYPE *altsock);

    /* Callback pour nettoyer des allocations personnalisées. */
    void        (*cleanup) (PGconn *conn, struct PGoauthBearerRequest *request);

    char       *token;   /* jeton du porteur acquis */
    void       *user;    /* données allouées définies par le hook */
} PGoauthBearerRequest;

Deux pièces d'information sont fournies au hook par libpq : openid_configuration contient l'URL d'un document de découverte OAuth décrivant les flux acceptés par le serveur d'autorisation, et scope contient une liste (potentiellement vide) de portées OAuth séparées par des espace, requises pour accéder au serveur. Ils peuvent être NULL pour indiquer que l'information n'est pas disponible. (Dans ce cas, les implémentations pourraient être capables d'établir les prérequis en utilisant une certaine connaissance pré-configurée, ou elles pourraient choisir d'échouer.)

La sortie finale du hook est token, qui doit pointer vers un jeton valide du porteur pour l'utiliser sur la connexion. (Ce jeton doit être fourni par oauth_issuer et contenir les portées demandées, sinon la connexion sera rejetée par le module de validation du serveur.) La chaîne allouée du jeton doit rester valide jusqu'à ce que libpq ait terminé l'étape de connexion ; le hook doit configurer un callback cleanup qui sera appelé quand libpq n'en a plus besoin.

Si une implémentation ne peut pas immédiatement produire un jeton (token) lors de l'appel initial au hook, il doit configurer le callback async pour gérer une communication non bloquante avec le serveur d'autorisation. ^[16] Elle sera appelée pour commencer le flux immédiatement au retour du hook. Quand le callback ne peut plus avancer sans bloquer, il doit renvoyer soit PGRES_POLLING_READING soit PGRES_POLLING_WRITING après avoir configuré *pgsocket sur le descripteur de fichier qui sera marqué prêt en lecture/écriture quand la progression pourra reprendre. (Ce descripteur est ensuite fourniau haut niveau de la boucle d'interrogation via PQsocket().) Renvoyez PGRES_POLLING_OK après avoir configuré token quand le flux est terminé, ou PGRES_POLLING_FAILED pour indiquer l'échec.

Les implémentations pourraient vouloir enregistrer des données supplémentaires entre les appels aux callbacks async et cleanup. Le pointeur user est fourni dans ce but ; libpq ne touchera pas à son contenu et les applications pourraient l'utiliser à leur convenance. (Rappelez-vous de libérer toute allocation pendant le nettoyage du jeton.)