Replaces the default user prompt during the builtin device authorization client flow. <replaceable>data</replaceable> points to an instance of <symbol>PGpromptOAuthDevice</symbol>: 組み込みデバイス認証クライアントフロー中の、デフォルトのユーザプロンプトを置き換えます。 dataは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 */

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

The OAuth Device Authorization flow which <link linkend="configure-option-with-libcurl">can be included</link> in <application>libpq</application> requires the end user to visit a URL with a browser, then enter a code which permits <application>libpq</application> to connect to the server on their behalf. The default prompt simply prints the <literal>verification_uri</literal> and <literal>user_code</literal> on standard error. Replacement implementations may display this information using any preferred method, for example with a GUI. libpqに含めることができるOAuthデバイス認証フローでは、エンドユーザがブラウザでURLにアクセスし、libpqがユーザに代わってサーバに接続することを許可するコードを入力する必要があります。 デフォルトのプロンプトは、標準エラーにverification_uriとuser_codeを出力するだけです。 代替の実装では、この情報をGUIなど好みの方法を使用して表示できます。

This callback is only invoked during the builtin device authorization flow. If the application installs a <link linkend="libpq-oauth-authdata-oauth-bearer-token">custom OAuth flow</link>, or <application>libpq</application> was not built with support for the builtin flow, this authdata type will not be used. このコールバックは、組み込みデバイス認証フロー中にのみ呼び出されます。 アプリケーションがカスタムOAuthフローをインストールしている場合や、libpqが組み込みフローをサポートするようにビルドされていない場合、この認証データ型は使用されません。

If a non-NULL <structfield>verification_uri_complete</structfield> is provided, it may optionally be used for non-textual verification (for example, by displaying a QR code). The URL and user code should still be displayed to the end user in this case, because the code will be manually confirmed by the provider, and the URL lets users continue even if they can't use the non-textual method. For more information, see section 3.3.1 in <ulink url="https://datatracker.ietf.org/doc/html/rfc8628#section-3.3.1">RFC 8628</ulink>. 非NULLのverification_uri_completeが提供されている場合は、テキスト以外の検証（QRコードの表示など）にも使用できます。 この場合でも、URLとユーザコードは引き続きエンドユーザに表示する必要があります。 これは、そのコードがプロバイダによって手動で確認されるため、またユーザがテキスト以外の方法を使用できない場合でもURLを使用して続行できるようにするためです。 詳細については、RFC 8628のセクション3.3.1を参照してください。

Adds a custom implementation of a flow, replacing the builtin flow if it is <link linkend="configure-option-with-libcurl">installed</link>. The hook should either directly return a Bearer token for the current user/issuer/scope combination, if one is available without blocking, or else set up an asynchronous callback to retrieve one. 独自実装したフローを追加し、組み込みフローがインストールされている場合はそれを置き換えます。 フックは、ブロッキングなしで使用可能な場合は現在のユーザ/発行者/スコープの組み合わせのベアラトークンを直接返すか、それ以外の場合は非同期コールバックを設定してベアラトークンを取得する必要があります。

<replaceable>data</replaceable> points to an instance of <symbol>PGoauthBearerRequest</symbol>, which should be filled in by the implementation: dataはPGoauthBearerRequestのインスタンスを指しています。 このインスタンスは実装側で入力する必要があります。

typedef struct PGoauthBearerRequest
{

    /* Hook inputs (constant across all calls) */
    const char *openid_configuration; /* OIDC discovery URL */
    const char *scope;                /* required scope(s), or NULL */

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


    /* Hook outputs */

    /* フックの出力 */

    /*

     * Callback implementing a custom asynchronous OAuth flow. The signature is
     * platform-dependent: PQ_SOCKTYPE is SOCKET on Windows, and int everywhere
     * else.

     * カスタム非同期OAuthフローを実装するコールバック。シグネチャはプラット
     * フォーム依存です。WindowsではPQ_SOCKTYPEはSOCKETで、その他のすべての場所
     * ではintです。
     */
    PostgresPollingStatusType (*async) (PGconn *conn,
                                        struct PGoauthBearerRequest *request,
                                        PQ_SOCKTYPE *altsock);


    /* Callback to clean up custom allocations. */

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


    char       *token;   /* acquired Bearer token */
    void       *user;    /* hook-defined allocated data */

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

Two pieces of information are provided to the hook by <application>libpq</application>: <replaceable>openid_configuration</replaceable> contains the URL of an OAuth discovery document describing the authorization server's supported flows, and <replaceable>scope</replaceable> contains a (possibly empty) space-separated list of OAuth scopes which are required to access the server. Either or both may be <literal>NULL</literal> to indicate that the information was not discoverable. (In this case, implementations may be able to establish the requirements using some other preconfigured knowledge, or they may choose to fail.) libpqでは、このフックで2つの情報を提供しています。 openid_configurationには、認証サーバがサポートするフローを説明するOAuthディスカバリー文書のURLが含まれ、scopeには、サーバへのアクセスに必要なOAuthスコープの一覧（空の場合もあります）がスペースで区切られて含まれています。 どちらか一方または両方がNULLの場合は、情報が検出できなかったことを示します。 （この場合、実装側で事前に設定された他の知識を使用して要件を確立できる場合もあれば、失敗を選択する場合もあります。）

The final output of the hook is <replaceable>token</replaceable>, which must point to a valid Bearer token for use on the connection. (This token should be issued by the <xref linkend="libpq-connect-oauth-issuer"/> and hold the requested scopes, or the connection will be rejected by the server's validator module.) The allocated token string must remain valid until <application>libpq</application> is finished connecting; the hook should set a <replaceable>cleanup</replaceable> callback which will be called when <application>libpq</application> no longer requires it. フックの最終出力はtokenであり、これは接続で使用できる有効なベアラトークンを指している必要があります。 （このトークンはoauth_issuerによって発行され、要求されたスコープを保持する必要があります。 そうしないと、サーバの検証モジュールによって接続が拒否されます。） 割り当てられたトークン文字列は、libpqが接続を終了するまで有効なままでなければなりません。 フックは、libpqが接続を必要としなくなったときに呼び出されるcleanupコールバックを設定する必要があります。

If an implementation cannot immediately produce a <replaceable>token</replaceable> during the initial call to the hook, it should set the <replaceable>async</replaceable> callback to handle nonblocking communication with the authorization server. 実装上フックの最初の呼び出し中にすぐにtokenを生成できない場合は、認証サーバとの非ブロッキング通信を処理するように非同期コールバックを設定する必要があります。 ^[16] This will be called to begin the flow immediately upon return from the hook. When the callback cannot make further progress without blocking, it should return either <symbol>PGRES_POLLING_READING</symbol> or <symbol>PGRES_POLLING_WRITING</symbol> after setting <literal>*altsock</literal> to the file descriptor that will be marked ready to read/write when progress can be made again. (This descriptor is then provided to the top-level polling loop via <function>PQsocket()</function>.) Return <symbol>PGRES_POLLING_OK</symbol> after setting <replaceable>token</replaceable> when the flow is complete, or <symbol>PGRES_POLLING_FAILED</symbol> to indicate failure. これは、フックから戻るとすぐにフローを開始するために呼び出されます。 コールバックがブロッキングなしでこれ以上先に進めない場合は、*altsockに、処理が再開できるようになったときに読み取り/書き込みの準備完了とマークされるファイルディスクリプタを設定した後、PGRES_POLLING_READINGまたはPGRES_POLLING_WRITINGのいずれかを返す必要があります。 （その後、このディスクリプタはPQsocket()を介して最上位のポーリングループに提供されます。） フローが完了したらtokenを設定した後にPGRES_POLLING_OKを返し、失敗した場合はPGRES_POLLING_FAILEDを返します。

Implementations may wish to store additional data for bookkeeping across calls to the <replaceable>async</replaceable> and <replaceable>cleanup</replaceable> callbacks. The <replaceable>user</replaceable> pointer is provided for this purpose; <application>libpq</application> will not touch its contents and the application may use it at its convenience. (Remember to free any allocations during token cleanup.) 実装によっては、asyncコールバックとcleanupコールバックの呼び出しをまたぐ情報に対し、追加のデータを格納したい場合があります。 userポインタはこの目的のために提供されています。 libpqはその内容に触れることはなく、アプリケーションは都合の良いときにこの追加のデータを使用できます。 （トークンのクリーンアップ中に割り当てを解放することを忘れないでください。）