begriffs open source - ai-pg/blob - full-docs/src/sgml/html/oauth-validator-callbacks.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!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.0 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>
   3    OAuth validator modules implement their functionality by defining a set of
   4    callbacks. The server will call them as required to process the
   5    authentication request from the user.
   6   </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>
   7     The <code class="function">startup_cb</code> callback is executed directly after
   8     loading the module. This callback can be used to set up local state and
   9     perform additional initialization if required. If the validator module
  10     has state it can use <code class="structfield">state-&gt;private_data</code> to
  11     store it.
  12
  13 </p><pre class="programlisting">
  14 typedef void (*ValidatorStartupCB) (ValidatorModuleState *state);
  15 </pre><p>
  16    </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>
  17     The <code class="function">validate_cb</code> callback is executed during the OAuth
  18     exchange when a user attempts to authenticate using OAuth.  Any state set in
  19     previous calls will be available in <code class="structfield">state-&gt;private_data</code>.
  20
  21 </p><pre class="programlisting">
  22 typedef bool (*ValidatorValidateCB) (const ValidatorModuleState *state,
  23                                      const char *token, const char *role,
  24                                      ValidatorModuleResult *result);
  25 </pre><p>
  26
  27     <em class="replaceable"><code>token</code></em> will contain the bearer token to validate.
  28     <span class="application">PostgreSQL</span> has ensured that the token is well-formed syntactically, but no
  29     other validation has been performed.  <em class="replaceable"><code>role</code></em> will
  30     contain the role the user has requested to log in as.  The callback must
  31     set output parameters in the <code class="literal">result</code> struct, which is
  32     defined as below:
  33
  34 </p><pre class="programlisting">
  35 typedef struct ValidatorModuleResult
  36 {
  37     bool        authorized;
  38     char       *authn_id;
  39 } ValidatorModuleResult;
  40 </pre><p>
  41
  42     The connection will only proceed if the module sets
  43     <code class="structfield">result-&gt;authorized</code> to <code class="literal">true</code>.  To
  44     authenticate the user, the authenticated user name (as determined using the
  45     token) shall be palloc'd and returned in the <code class="structfield">result-&gt;authn_id</code>
  46     field.  Alternatively, <code class="structfield">result-&gt;authn_id</code> may be set to
  47     NULL if the token is valid but the associated user identity cannot be
  48     determined.
  49    </p><p>
  50     A validator may return <code class="literal">false</code> to signal an internal error,
  51     in which case any result parameters are ignored and the connection fails.
  52     Otherwise the validator should return <code class="literal">true</code> to indicate
  53     that it has processed the token and made an authorization decision.
  54    </p><p>
  55     The behavior after <code class="function">validate_cb</code> returns depends on the
  56     specific HBA setup.  Normally, the <code class="structfield">result-&gt;authn_id</code> user
  57     name must exactly match the role that the user is logging in as.  (This
  58     behavior may be modified with a usermap.)  But when authenticating against
  59     an HBA rule with <code class="literal">delegate_ident_mapping</code> turned on,
  60     <span class="productname">PostgreSQL</span> will not perform any checks on the value of
  61     <code class="structfield">result-&gt;authn_id</code> at all; in this case it is up to the
  62     validator to ensure that the token carries enough privileges for the user to
  63     log in under the indicated <em class="replaceable"><code>role</code></em>.
  64    </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>
  65     The <code class="function">shutdown_cb</code> callback is executed when the backend
  66     process associated with the connection exits. If the validator module has
  67     any allocated state, this callback should free it to avoid resource leaks.
  68 </p><pre class="programlisting">
  69 typedef void (*ValidatorShutdownCB) (ValidatorModuleState *state);
  70 </pre><p>
  71    </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.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Part VI. Reference</td></tr></table></div></body></html>