組み込みデバイス認証クライアントフロー中の、デフォルトのユーザプロンプトを置き換えます。 dataはPGpromptOAuthDeviceのインスタンスを指しています。

typedef struct _PGpromptOAuthDevice
{

    const char *verification_uri;   /* アクセスする検証URI */
    const char *user_code;          /* 入力するユーザコード */
    const char *verification_uri_complete;  /* URIとコードのオプションの組み合わせ、
                                             * またはNULL */
    int         expires_in;         /* ユーザコードの有効期限が切れるまでの秒数 */
} PGpromptOAuthDevice;

libpqに含めることができるOAuthデバイス認証フローでは、エンドユーザがブラウザでURLにアクセスし、libpqがユーザに代わってサーバに接続することを許可するコードを入力する必要があります。 デフォルトのプロンプトは、標準エラーにverification_uriとuser_codeを出力するだけです。 代替の実装では、この情報をGUIなど好みの方法を使用して表示できます。

このコールバックは、組み込みデバイス認証フロー中にのみ呼び出されます。 アプリケーションがカスタムOAuthフローをインストールしている場合や、libpqが組み込みフローをサポートするようにビルドされていない場合、この認証データ型は使用されません。

非NULLのverification_uri_completeが提供されている場合は、テキスト以外の検証（QRコードの表示など）にも使用できます。 この場合でも、URLとユーザコードは引き続きエンドユーザに表示する必要があります。 これは、そのコードがプロバイダによって手動で確認されるため、またユーザがテキスト以外の方法を使用できない場合でもURLを使用して続行できるようにするためです。 詳細については、RFC 8628のセクション3.3.1を参照してください。

独自実装したフローを追加し、組み込みフローがインストールされている場合はそれを置き換えます。 フックは、ブロッキングなしで使用可能な場合は現在のユーザ/発行者/スコープの組み合わせのベアラトークンを直接返すか、それ以外の場合は非同期コールバックを設定してベアラトークンを取得する必要があります。

dataはPGoauthBearerRequestのインスタンスを指しています。 このインスタンスは実装側で入力する必要があります。

typedef struct PGoauthBearerRequest
{

    /* フックの入力（全ての呼び出しで一定） */
    const char *openid_configuration; /* OIDCディスカバリーURL */
    const char *scope;                /* 必要なスコープ、またはNULL */

    /* フックの出力 */

    /* カスタム非同期OAuthフローを実装するコールバック。 */
    PostgresPollingStatusType (*async) (PGconn *conn,
                                        struct PGoauthBearerRequest *request,
                                        SOCKTYPE *altsock);

    /* カスタム割り当てをクリーンアップするためのコールバック。 */
    void        (*cleanup) (PGconn *conn, struct PGoauthBearerRequest *request);

    char       *token;   /* 取得したベアラトークン */
    void       *user;    /* フックで定義される割り当てデータ */
} PGoauthBearerRequest;

libpqでは、このフックで2つの情報を提供しています。 openid_configurationには、認証サーバがサポートするフローを説明するOAuthディスカバリー文書のURLが含まれ、scopeには、サーバへのアクセスに必要なOAuthスコープの一覧（空の場合もあります）がスペースで区切られて含まれています。 どちらか一方または両方がNULLの場合は、情報が検出できなかったことを示します。 （この場合、実装側で事前に設定された他の知識を使用して要件を確立できる場合もあれば、失敗を選択する場合もあります。）

フックの最終出力はtokenであり、これは接続で使用できる有効なベアラトークンを指している必要があります。 （このトークンはoauth_issuerによって発行され、要求されたスコープを保持する必要があります。 そうしないと、サーバの検証モジュールによって接続が拒否されます。） 割り当てられたトークン文字列は、libpqが接続を終了するまで有効なままでなければなりません。 フックは、libpqが接続を必要としなくなったときに呼び出されるcleanupコールバックを設定する必要があります。

実装上フックの最初の呼び出し中にすぐにtokenを生成できない場合は、認証サーバとの非ブロッキング通信を処理するように非同期コールバックを設定する必要があります。 ^[16] これは、フックから戻るとすぐにフローを開始するために呼び出されます。 コールバックがブロッキングなしでこれ以上先に進めない場合は、*pgsocketに、処理が再開できるようになったときに読み取り/書き込みの準備完了とマークされるファイルディスクリプタを設定した後、PGRES_POLLING_READINGまたはPGRES_POLLING_WRITINGのいずれかを返す必要があります。 （その後、このディスクリプタはPQsocket()を介して最上位のポーリングループに提供されます。） フローが完了したらtokenを設定した後にPGRES_POLLING_OKを返し、失敗した場合はPGRES_POLLING_FAILEDを返します。

実装によっては、asyncコールバックとcleanupコールバックの呼び出しをまたぐ情報に対し、追加のデータを格納したい場合があります。 userポインタはこの目的のために提供されています。 libpqはその内容に触れることはなく、アプリケーションは都合の良いときにこの追加のデータを使用できます。 （トークンのクリーンアップ中に割り当てを解放することを忘れないでください。）