</programlisting>
   </para>
  </sect2>

  <sect2 id="oauth-validator-callback-validate">
   <title>Validate Callback</title>
   <para>
    The <function>validate_cb</function> 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 <structfield>state->private_data</structfield>.

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

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

<programlisting>
typedef struct ValidatorModuleResult
{
    bool        authorized;
    char       *authn_id;
} ValidatorModuleResult;
</programlisting>

    The connection will only proceed if the module sets
    <structfield>result->authorized</structfield> to <literal>true</literal>.  To
    authenticate the user, the authenticated user name (as determined using the
    token) shall be palloc'd and returned in the <structfield>result->authn_id</structfield>
    field.  Alternatively, <structfield>result->authn_id</structfield> may be set to
    NULL if the token is valid but the associated user identity cannot be
    determined.
   </para>
   <para>
    A validator may return <literal>false</literal> to signal an internal error,
    in which case any result parameters are ignored and the connection fails.
    Otherwise the validator should return <literal>true</literal> to indicate
    that it has processed the token and made an authorization decision.
   </para>
   <para>
    The behavior after <function>validate_cb</function> returns depends on the
    specific HBA setup.  Normally, the <structfield>result->authn_id</structfield> 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 <literal>delegate_ident_mapping</literal> turned on,
    <productname>PostgreSQL</productname> will not perform any checks on the value of
    <structfield>result->authn_id</structfield> 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 <replaceable>role</replaceable>.
   </para>
  </sect2>

  <sect2 id="oauth-validator-callback-shutdown">
   <title>Shutdown Callback</title>
   <para>
    The <function>shutdown_cb</function> 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.
<programlisting>
typedef void (*ValidatorShutdownCB) (ValidatorModuleState *state);
</programlisting>
   </para>
  </sect2>

 </sect1>
</chapter>