<application>libpq</application> implements support for the OAuth v2 Device Authorization client flow, documented in <ulink url="https://datatracker.ietf.org/doc/html/rfc8628">RFC 8628</ulink>, as an optional module. See the <link linkend="configure-option-with-libcurl"> installation documentation</link> for information on how to enable support for Device Authorization as a builtin flow. 《機械翻訳》libpqRFC 8628に記載されている、OAuth v2サポート認証のためのデバイスをクライアントモジュールとして実装しています。 組み込みフローとしてデバイス認証のためのサポートを有効にする方法については、インストール文書を参照してください。 オプショナルフロー
When support is enabled and the optional module installed, <application>libpq</application> will use the builtin flow by default if the server <link linkend="auth-oauth">requests a bearer token</link> during authentication. This flow can be utilized even if the system running the client application does not have a usable web browser, for example when running a client via <acronym>SSH</acronym>. 《機械翻訳》サポートが有効でオプショナルモジュールがインストールされている場合、フロー中にデフォルトがベアラトークンを要求すると、libpqは組み込みのサーバby認証を使用します。 このフローは、クライアントアプリケーションを実行しているシステムに使用可能なWebブラウザがない場合でも、SSH経由でクライアントを実行している場合の例に使用できます。
The builtin flow will, by default, print a URL to visit and a user code to enter there: 《機械翻訳》組み込みのフローでは、デフォルト、プリント別に、訪問するURLと、そこに入力するユーザコードが表示されます。
$ psql 'dbname=postgres oauth_issuer=https://example.com oauth_client_id=...' Visit https://example.com/device and enter the code: ABCD-EFGH
(This prompt may be <link linkend="libpq-oauth-authdata-prompt-oauth-device">customized</link>.) The user will then log into their OAuth provider, which will ask whether to allow libpq and the server to perform actions on their behalf. It is always a good idea to carefully review the URL and permissions displayed, to ensure they match expectations, before continuing. Permissions should not be given to untrusted third parties. 《機械翻訳》(このプロンプトはカスタマイズされている可能性があります。) その後、ユーザはログをOAuthプロバイダに入れ、libpqとサーバが彼らに代わってアクションを実行することを許可するかどうかを尋ねます。 表示されたURLと権限を慎重にレビューし、保証に期待をマッチさせ、前を続けることは、常に良いアイディアです。 信頼できないサードパーティに権限を与えるべきではありません。
Client applications may implement their own flows to customize interaction and integration with applications. See <xref linkend="libpq-oauth-authdata-hooks"/> for more information on how add a custom flow to <application>libpq</application>. 《機械翻訳》クライアントアプリケーションは、カスタマイズとの対話およびアプリケーションとの統合に独自のフローを実装する場合があります。 カスタムフローをlibpqに追加する方法の詳細は、32.20.1を参照してください。
For an OAuth client flow to be usable, the connection string must at minimum contain <xref linkend="libpq-connect-oauth-issuer"/> and <xref linkend="libpq-connect-oauth-client-id"/>. (These settings are determined by your organization's OAuth provider.) The builtin flow additionally requires the OAuth authorization server to publish a device authorization endpoint. 《機械翻訳》OAuthクライアントフローを使用するには、コネクション文字列に少なくともoauth_issuerとoauth_client_idが含まれている必要があります。 (これらの設定は、組織のOAuthプロバイダによって決定されます。) 組み込みのフローには、デバイス認証エンドポイントをパブリッシュするためのOAuth認証サーバも必要です。
The builtin Device Authorization flow is not currently supported on Windows. Custom client flows may still be implemented. 《機械翻訳》組み込みのデバイス許可フローは現在、Windowsではサポートされていません。 カスタムクライアントフローはまだ実装されている可能性があります。
The behavior of the OAuth flow may be modified or replaced by a client using the following hook API: 《機械翻訳》OAuthフローの動作は、次のクライアントAPIを使用して変更またはフックに置き換えることができます。
PQsetAuthDataHook
#
Sets the <symbol>PGauthDataHook</symbol>, overriding
<application>libpq</application>'s handling of one or more aspects of
its OAuth client flow.
《機械翻訳》OAuthハンドリングフローの1つ以上のアスペクトのPGauthDataHook
,overriding libpqのクライアントを設定します。
void PQsetAuthDataHook(PQauthDataHook_type hook);
If <replaceable>hook</replaceable> is <literal>NULL</literal>, the
default handler will be reinstalled. Otherwise, the application passes
a pointer to a callback function with the signature:
《機械翻訳》フック
がNULL
の場合、デフォルトハンドラは再インストールされます。
それ以外の場合、アプリケーションはポインタをシグネチャ:とともにコールバック機能に渡します。
int hook_fn(PGauthData type, PGconn *conn, void *data);
which <application>libpq</application> will call when an action is
required of the application. <replaceable>type</replaceable> describes
the request being made, <replaceable>conn</replaceable> is the
connection handle being authenticated, and <replaceable>data</replaceable>
points to request-specific metadata. The contents of this pointer are
determined by <replaceable>type</replaceable>; see
<xref linkend="libpq-oauth-authdata-hooks-types"/> for the supported
list.
《機械翻訳》このlibpqは、アプリケーションに対してアクションが要求されたときに呼び出しを行います。
type
は作成されるリクエストを記述し、conn
は認証されるコネクションハンドルであり、data
はリクエスト固有のメタデータを指します。
このポインタの内容はtype
によって決定されます。
サポートされるリストについては32.20.1.1を参照してください。
Hooks can be chained together to allow cooperative and/or fallback
behavior. In general, a hook implementation should examine the incoming
<replaceable>type</replaceable> (and, potentially, the request metadata
and/or the settings for the particular <replaceable>conn</replaceable>
in use) to decide whether or not to handle a specific piece of authdata.
If not, it should delegate to the previous hook in the chain
(retrievable via <function>PQgetAuthDataHook</function>).
《機械翻訳》フックは、連携動作や代替動作を可能にするために連鎖させることができます。
一般に、フック実装は、特定のauthdataをハンドルするかどうかを決定するために、着信タイプ
を調べる必要があります(場合によっては、リクエストメタデータや、使用中の特定のconn
の設定も調べる必要があります)。
そうでない場合は、チェーン内の前のフックに委任する必要があります(PQgetAuthDataHook
を使用して取得可能)。
Success is indicated by returning an integer greater than zero. Returning a negative integer signals an error condition and abandons the connection attempt. (A zero value is reserved for the default implementation.) 《機械翻訳》成功は、整数より大きいゼロを戻すことで示されます。 負の整数を戻すと、エラー条件が通知され、コネクション試行が中止されます(デフォルト実装のゼロ値は予約です)。
PQgetAuthDataHook
#
Retrieves the current value of <symbol>PGauthDataHook</symbol>.
《機械翻訳》現在のPGauthDataHook
.
PQauthDataHook_type PQgetAuthDataHook(void);
At initialization time (before the first call to
<function>PQsetAuthDataHook</function>), this function will return
<symbol>PQdefaultAuthDataHook</symbol>.
《機械翻訳》初期設定時にPQsetAuthDataHook
前はへの最初の呼び出しで、この関数は結果PQdefaultAuthDataHook
。
The following <symbol>PGauthData</symbol> types and their corresponding
<replaceable>data</replaceable> structures are defined:
《機械翻訳》以下のPGauthData
型とそれに対応するdata
構造体が定義されています。
PQAUTHDATA_PROMPT_OAUTH_DEVICE
#
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 */ } 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組み込みのフロー用にサポートで構築されていない場合、このauthdataタイプは使用されません。
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を参照してください。
PQAUTHDATA_OAUTH_BEARER_TOKEN
#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 */ /* Hook outputs */ /* Callback implementing a custom asynchronous OAuth flow. */ PostgresPollingStatusType (*async) (PGconn *conn, struct PGoauthBearerRequest *request, 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 */ } 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.)
《機械翻訳》次の2つの情報がlibpqによってフックに提供されます。
openid_設定
包含は、認可サーバがサポートするフローを記述するOAuthディスカバリドキュメントのURLであり、スコープ
包含は、サーバをアクセス化するために必要な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
token
during the initial call to the hook,
it should set the async
callback to handle
nonblocking communication with the authorization server.
[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 PGRES_POLLING_READING
or
PGRES_POLLING_WRITING
after setting
*pgsocket
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
PQsocket()
.) Return PGRES_POLLING_OK
after setting token
when the flow is
complete, or PGRES_POLLING_FAILED
to indicate failure.
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
callbacks. user
データはこの目的のために提供されています。
libpqはその内容に触れることはなく、ポインタは都合のよいときにそれを使用することができます。
アプリケーションクリーンアップ中に割り当てられたものをフリーすることを忘れないでください。
への呼び出し全体にわたって簿記のために追加のトークンを格納することを望む場合があります。
A "dangerous debugging mode" may be enabled by setting the environment
variable <envar>PGOAUTHDEBUG=UNSAFE</envar>. This functionality is provided
for ease of local development and testing only. It does several things that
you will not want a production system to do:
《機械翻訳》「危険なデバッグモード」は、環境変数PGOAUTHDEBUG=UNSAFE
を設定することで有効にできます。
この機能は、ローカルの開発とテストを容易にするためにのみ提供されています。
この機能は、本番システムでは実行したくないいくつかのことを実行します。
permits the use of unencrypted HTTP during the OAuth provider exchange 《機械翻訳》は、OAuthプロバイダの交換中に暗号化されていないHTTPの使用を許可します。
allows the system's trusted CA list to be completely replaced using the
<envar>PGOAUTHCAFILE</envar> environment variable
《機械翻訳》PGOAUTHCAFILE
リストを使用して、このシステムのカリフォルニア州トラステッド環境変数を完全に置き換えることができます。
prints HTTP traffic (containing several critical secrets) to standard error during the OAuth flow 《機械翻訳》はOAuthトラフィック中にHTTPフロー(いくつかの重要な秘密情報を含む)を標準エラーに出力する。
permits the use of zero-second retry intervals, which can cause the client to busy-loop and pointlessly consume CPU 《機械翻訳》では、ゼロ秒のリトライ間隔を使用できます。 これにより、クライアントがビジー-ループになり、CPU使用率が無意味に消費される可能性があります。
Do not share the output of the OAuth flow traffic with third parties. It contains secrets that can be used to attack your clients and servers. 《機械翻訳》OAuthフロートラフィックの出力を第三者と共有しないでください。 クライアントやサーバを攻撃するために使用できる包含シークレットです。
[16]
Performing blocking operations during the
<symbol>PQAUTHDATA_OAUTH_BEARER_TOKEN</symbol> hook callback will
interfere with nonblocking connection APIs such as
<function>PQconnectPoll</function> and prevent concurrent connections
from making progress. Applications which only ever use the
synchronous connection primitives, such as
<function>PQconnectdb</function>, may synchronously retrieve a token
during the hook instead of implementing the
<replaceable>async</replaceable> callback, but they will necessarily
be limited to one connection at a time.
《機械翻訳》PQAUTHDATA_OAUTH_BEARER_TOKEN
のブロッキング中にフック操作を実行すると、PQconnectPoll
などの非ブロッキング接続APIに干渉し、同時接続が進行しなくなります。
PQconnectdb
などの同期的コネクションプリミティブのみを使用するアプリケーションは、async
コールバックを実装するフック代わり中にトークンを同期的に取得できますが、一度に取得できるコネクションは1つに制限されます。