pgsql/doc/src/sgml/html/oauth-validator-callbacks.html - master - Ao/MaxReport

pgsql/doc/src/sgml/html/oauth-validator-callbacks.html
71 строка7 KB
AoAnima
first_commit
13 июл 2026, 17:47
13 июл 2026, 17:47f1a670a
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>50.3. OAuth Validator Callbacks</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="oauth-validator-init.html" title="50.2. Initialization Functions" /><link rel="next" href="reference.html" title="Part VI. Reference" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">50.3. OAuth Validator Callbacks</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="oauth-validator-init.html" title="50.2. Initialization Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="oauth-validators.html" title="Chapter 50. OAuth Validator Modules">Up</a></td><th width="60%" align="center">Chapter 50. OAuth Validator Modules</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.4 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="reference.html" title="Part VI. Reference">Next</a></td></tr></table><hr /></div><div class="sect1" id="OAUTH-VALIDATOR-CALLBACKS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">50.3. OAuth Validator Callbacks <a href="#OAUTH-VALIDATOR-CALLBACKS" class="id_link">#</a></h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="oauth-validator-callbacks.html#OAUTH-VALIDATOR-CALLBACK-STARTUP">50.3.1. Startup Callback</a></span></dt><dt><span class="sect2"><a href="oauth-validator-callbacks.html#OAUTH-VALIDATOR-CALLBACK-VALIDATE">50.3.2. Validate Callback</a></span></dt><dt><span class="sect2"><a href="oauth-validator-callbacks.html#OAUTH-VALIDATOR-CALLBACK-SHUTDOWN">50.3.3. Shutdown Callback</a></span></dt></dl></div><p>
   OAuth validator modules implement their functionality by defining a set of
   callbacks. The server will call them as required to process the
   authentication request from the user.
  </p><div class="sect2" id="OAUTH-VALIDATOR-CALLBACK-STARTUP"><div class="titlepage"><div><div><h3 class="title">50.3.1. Startup Callback <a href="#OAUTH-VALIDATOR-CALLBACK-STARTUP" class="id_link">#</a></h3></div></div></div><p>
    The <code class="function">startup_cb</code> callback is executed directly after
    loading the module. This callback can be used to set up local state and
    perform additional initialization if required. If the validator module
    has state it can use <code class="structfield">state-&gt;private_data</code> to
    store it.

</p><pre class="programlisting">
typedef void (*ValidatorStartupCB) (ValidatorModuleState *state);
</pre><p>
   </p></div><div class="sect2" id="OAUTH-VALIDATOR-CALLBACK-VALIDATE"><div class="titlepage"><div><div><h3 class="title">50.3.2. Validate Callback <a href="#OAUTH-VALIDATOR-CALLBACK-VALIDATE" class="id_link">#</a></h3></div></div></div><p>
    The <code class="function">validate_cb</code> callback is executed during the OAuth
    exchange when a user attempts to authenticate using OAuth.  Any state set in
    previous calls will be available in <code class="structfield">state-&gt;private_data</code>.

</p><pre class="programlisting">
typedef bool (*ValidatorValidateCB) (const ValidatorModuleState *state,
                                     const char *token, const char *role,
                                     ValidatorModuleResult *result);
</pre><p>

    <em class="replaceable"><code>token</code></em> will contain the bearer token to validate.
    <span class="application">PostgreSQL</span> has ensured that the token is well-formed syntactically, but no
    other validation has been performed.  <em class="replaceable"><code>role</code></em> will
    contain the role the user has requested to log in as.  The callback must
    set output parameters in the <code class="literal">result</code> struct, which is
    defined as below:

</p><pre class="programlisting">
typedef struct ValidatorModuleResult
{
    bool        authorized;
    char       *authn_id;
} ValidatorModuleResult;
</pre><p>

    The connection will only proceed if the module sets
    <code class="structfield">result-&gt;authorized</code> to <code class="literal">true</code>.  To
    authenticate the user, the authenticated user name (as determined using the
    token) shall be palloc'd and returned in the <code class="structfield">result-&gt;authn_id</code>
    field.  Alternatively, <code class="structfield">result-&gt;authn_id</code> may be set to
    NULL if the token is valid but the associated user identity cannot be
    determined.
   </p><p>
    A validator may return <code class="literal">false</code> to signal an internal error,
    in which case any result parameters are ignored and the connection fails.
    Otherwise the validator should return <code class="literal">true</code> to indicate
    that it has processed the token and made an authorization decision.
   </p><p>
    The behavior after <code class="function">validate_cb</code> returns depends on the
    specific HBA setup.  Normally, the <code class="structfield">result-&gt;authn_id</code> user
    name must exactly match the role that the user is logging in as.  (This
    behavior may be modified with a usermap.)  But when authenticating against
    an HBA rule with <code class="literal">delegate_ident_mapping</code> turned on,
    <span class="productname">PostgreSQL</span> will not perform any checks on the value of
    <code class="structfield">result-&gt;authn_id</code> at all; in this case it is up to the
    validator to ensure that the token carries enough privileges for the user to
    log in under the indicated <em class="replaceable"><code>role</code></em>.
   </p></div><div class="sect2" id="OAUTH-VALIDATOR-CALLBACK-SHUTDOWN"><div class="titlepage"><div><div><h3 class="title">50.3.3. Shutdown Callback <a href="#OAUTH-VALIDATOR-CALLBACK-SHUTDOWN" class="id_link">#</a></h3></div></div></div><p>
    The <code class="function">shutdown_cb</code> callback is executed when the backend
    process associated with the connection exits. If the validator module has
    any allocated state, this callback should free it to avoid resource leaks.
</p><pre class="programlisting">
typedef void (*ValidatorShutdownCB) (ValidatorModuleState *state);
</pre><p>
   </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="oauth-validator-init.html" title="50.2. Initialization Functions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="oauth-validators.html" title="Chapter 50. OAuth Validator Modules">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="reference.html" title="Part VI. Reference">Next</a></td></tr><tr><td width="40%" align="left" valign="top">50.2. Initialization Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.4 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Part VI. Reference</td></tr></table></div></body></html>