<!-- doc/src/sgml/oauth-validators.sgml -->

<chapter id="oauth-validators">
 <title>OAuth Validator Modules</title>
 <indexterm zone="oauth-validators">
  <primary>OAuth Validators</primary>
 </indexterm>
 <para>
  <productname>PostgreSQL</productname> provides infrastructure for creating
  custom modules to perform server-side validation of OAuth bearer tokens.
  Because OAuth implementations vary so wildly, and bearer token validation is
  heavily dependent on the issuing party, the server cannot check the token
  itself; validator modules provide the integration layer between the server
  and the OAuth provider in use.
 </para>
 <para>
  OAuth validator modules must at least consist of an initialization function
  (see <xref linkend="oauth-validator-init"/>) and the required callback for
  performing validation (see <xref linkend="oauth-validator-callback-validate"/>).
 </para>
 <warning>
  <para>
   Since a misbehaving validator might let unauthorized users into the database,
   correct implementation is crucial for server safety. See
   <xref linkend="oauth-validator-design"/> for design considerations.
  </para>
 </warning>

 <sect1 id="oauth-validator-design">
  <title>Safely Designing a Validator Module</title>
  <warning>
   <para>
    Read and understand the entirety of this section before implementing a
    validator module. A malfunctioning validator is potentially worse than no
    authentication at all, both because of the false sense of security it
    provides, and because it may contribute to attacks against other pieces of
    an OAuth ecosystem.
   </para>
  </warning>

  <sect2 id="oauth-validator-design-responsibilities">
   <title>Validator Responsibilities</title>
   <para>
    Although different modules may take very different approaches to token
    validation, implementations generally need to perform three separate
    actions:
   </para>
   <variablelist>
    <varlistentry>
     <term>Validate the Token</term>
     <listitem>
      <para>
       The validator must first ensure that the presented token is in fact a
       valid Bearer token for use in client authentication. The correct way to
       do this depends on the provider, but it generally involves either
       cryptographic operations to prove that the token was created by a trusted
       party (offline validation), or the presentation of the token to that
       trusted party so that it can perform validation for you (online
       validation).
      </para>
      <para>
       Online validation, usually implemented via
       <ulink url="https://datatracker.ietf.org/doc/html/rfc7662">OAuth Token
       Introspection</ulink>, requires fewer steps of a validator module and
       allows central revocation of a token in the event that it is stolen
       or misissued. However, it does require the module to make at least one
       network call per authentication attempt (all of which must complete
       within the configured <xref linkend="guc-authentication-timeout"/>).
       Additionally, your provider may not provide introspection endpoints for
       use by external resource servers.
      </para>
      <para>
       Offline validation is much more involved, typically requiring a validator
       to maintain a list of trusted signing keys for a provider and then
       check the token's cryptographic signature along with its contents.
       Implementations must follow the provider's instructions to the letter,
       including any verification of issuer ("where is this token from?"),
       audience ("who is this token for?"), and validity period ("when can this
       token be used?"). Since there is no communication between the module and
       the provider, tokens cannot be centrally revoked using this method;
       offline validator implementations may wish to place restrictions on the
       maximum length of a token's validity period.
      </para>
      <para>
       If the token cannot be validated, the module should immediately