begriffs open source - ai-pg/blob - full-docs/html/sasl-authentication.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>54.3. SASL Authentication</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="protocol-flow.html" title="54.2. Message Flow" /><link rel="next" href="protocol-replication.html" title="54.4. Streaming Replication Protocol" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">54.3. SASL Authentication</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="protocol-flow.html" title="54.2. Message Flow">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="protocol.html" title="Chapter 54. Frontend/Backend Protocol">Up</a></td><th width="60%" align="center">Chapter 54. Frontend/Backend Protocol</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="protocol-replication.html" title="54.4. Streaming Replication Protocol">Next</a></td></tr></table><hr /></div><div class="sect1" id="SASL-AUTHENTICATION"><div class="titlepage"><div><div><h2 class="title" style="clear: both">54.3. SASL Authentication <a href="#SASL-AUTHENTICATION" class="id_link">#</a></h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="sasl-authentication.html#SASL-SCRAM-SHA-256">54.3.1. SCRAM-SHA-256 Authentication</a></span></dt><dt><span class="sect2"><a href="sasl-authentication.html#SASL-OAUTHBEARER">54.3.2. OAUTHBEARER Authentication</a></span></dt></dl></div><p>
   3    <em class="firstterm">SASL</em> is a framework for authentication in connection-oriented
   4    protocols. At the moment, <span class="productname">PostgreSQL</span> implements three
   5    SASL authentication mechanisms: SCRAM-SHA-256, SCRAM-SHA-256-PLUS, and
   6    OAUTHBEARER. More might be added in the future. The below steps illustrate how SASL
   7    authentication is performed in general, while the next subsections give
   8    more details on particular mechanisms.
   9   </p><div class="procedure" id="id-1.10.6.8.3"><p class="title"><strong>SASL Authentication Message Flow</strong></p><ol class="procedure" type="1"><li class="step" id="SASL-AUTH-BEGIN"><p>
  10      To begin a SASL authentication exchange, the server sends an
  11      AuthenticationSASL message. It includes a list of SASL authentication
  12      mechanisms that the server can accept, in the server's preferred order.
  13     </p></li><li class="step" id="SASL-AUTH-INITIAL-RESPONSE"><p>
  14      The client selects one of the supported mechanisms from the list, and sends
  15      a SASLInitialResponse message to the server. The message includes the name
  16      of the selected mechanism, and an optional Initial Client Response, if the
  17      selected mechanism uses that.
  18     </p></li><li class="step" id="SASL-AUTH-CONTINUE"><p>
  19      One or more server-challenge and client-response message will follow. Each
  20      server-challenge is sent in an AuthenticationSASLContinue message, followed
  21      by a response from client in a SASLResponse message. The particulars of
  22      the messages are mechanism specific.
  23     </p></li><li class="step" id="SASL-AUTH-END"><p>
  24      Finally, when the authentication exchange is completed successfully, the
  25      server sends an optional AuthenticationSASLFinal message, followed
  26      immediately by an AuthenticationOk message. The AuthenticationSASLFinal
  27      contains additional server-to-client data, whose content is particular to the
  28      selected authentication mechanism. If the authentication mechanism doesn't
  29      use additional data that's sent at completion, the AuthenticationSASLFinal
  30      message is not sent.
  31     </p></li></ol></div><p>
  32    On error, the server can abort the authentication at any stage, and send an
  33    ErrorMessage.
  34   </p><div class="sect2" id="SASL-SCRAM-SHA-256"><div class="titlepage"><div><div><h3 class="title">54.3.1. SCRAM-SHA-256 Authentication <a href="#SASL-SCRAM-SHA-256" class="id_link">#</a></h3></div></div></div><p>
  35     <code class="literal">SCRAM-SHA-256</code>, and its variant with channel
  36     binding <code class="literal">SCRAM-SHA-256-PLUS</code>, are password-based
  37     authentication mechanisms. They are described in
  38     detail in <a class="ulink" href="https://datatracker.ietf.org/doc/html/rfc7677" target="_top">RFC 7677</a>
  39     and <a class="ulink" href="https://datatracker.ietf.org/doc/html/rfc5802" target="_top">RFC 5802</a>.
  40    </p><p>
  41     When SCRAM-SHA-256 is used in PostgreSQL, the server will ignore the user name
  42     that the client sends in the <code class="structname">client-first-message</code>. The user name
  43     that was already sent in the startup message is used instead.
  44     <span class="productname">PostgreSQL</span> supports multiple character encodings, while SCRAM
  45     dictates UTF-8 to be used for the user name, so it might be impossible to
  46     represent the PostgreSQL user name in UTF-8.
  47    </p><p>
  48     The SCRAM specification dictates that the password is also in UTF-8, and is
  49     processed with the <em class="firstterm">SASLprep</em> algorithm.
  50     <span class="productname">PostgreSQL</span>, however, does not require UTF-8 to be used for
  51     the password. When a user's password is set, it is processed with SASLprep
  52     as if it was in UTF-8, regardless of the actual encoding used. However, if
  53     it is not a legal UTF-8 byte sequence, or it contains UTF-8 byte sequences
  54     that are prohibited by the SASLprep algorithm, the raw password will be used
  55     without SASLprep processing, instead of throwing an error. This allows the
  56     password to be normalized when it is in UTF-8, but still allows a non-UTF-8
  57     password to be used, and doesn't require the system to know which encoding
  58     the password is in.
  59    </p><p>
  60     <em class="firstterm">Channel binding</em> is supported in PostgreSQL builds with
  61     SSL support. The SASL mechanism name for SCRAM with channel binding is
  62     <code class="literal">SCRAM-SHA-256-PLUS</code>.  The channel binding type used by
  63     PostgreSQL is <code class="literal">tls-server-end-point</code>.
  64    </p><p>
  65     In <acronym class="acronym">SCRAM</acronym> without channel binding, the server chooses
  66     a random number that is transmitted to the client to be mixed with the
  67     user-supplied password in the transmitted password hash.  While this
  68     prevents the password hash from being successfully retransmitted in
  69     a later session, it does not prevent a fake server between the real
  70     server and client from passing through the server's random value
  71     and successfully authenticating.
  72    </p><p>
  73     <acronym class="acronym">SCRAM</acronym> with channel binding prevents such
  74     man-in-the-middle attacks by mixing the signature of the server's
  75     certificate into the transmitted password hash. While a fake server can
  76     retransmit the real server's certificate, it doesn't have access to the
  77     private key matching that certificate, and therefore cannot prove it is
  78     the owner, causing SSL connection failure.
  79    </p><div class="procedure" id="id-1.10.6.8.5.8"><p class="title"><strong>Example</strong></p><ol class="procedure" type="1"><li class="step" id="SCRAM-BEGIN"><p>
  80       The server sends an AuthenticationSASL message. It includes a list of
  81       SASL authentication mechanisms that the server can accept.
  82       This will be <code class="literal">SCRAM-SHA-256-PLUS</code>
  83       and <code class="literal">SCRAM-SHA-256</code> if the server is built with SSL
  84       support, or else just the latter.
  85      </p></li><li class="step" id="SCRAM-CLIENT-FIRST"><p>
  86       The client responds by sending a SASLInitialResponse message, which
  87       indicates the chosen mechanism, <code class="literal">SCRAM-SHA-256</code> or
  88       <code class="literal">SCRAM-SHA-256-PLUS</code>. (A client is free to choose either
  89       mechanism, but for better security it should choose the channel-binding
  90       variant if it can support it.) In the Initial Client response field, the
  91       message contains the SCRAM <code class="structname">client-first-message</code>.
  92       The <code class="structname">client-first-message</code> also contains the channel
  93       binding type chosen by the client.
  94      </p></li><li class="step" id="SCRAM-SERVER-FIRST"><p>
  95       Server sends an AuthenticationSASLContinue message, with a SCRAM
  96       <code class="structname">server-first-message</code> as the content.
  97      </p></li><li class="step" id="SCRAM-CLIENT-FINAL"><p>
  98       Client sends a SASLResponse message, with SCRAM
  99       <code class="structname">client-final-message</code> as the content.
 100      </p></li><li class="step" id="SCRAM-SERVER-FINAL"><p>
 101       Server sends an AuthenticationSASLFinal message, with the SCRAM
 102       <code class="structname">server-final-message</code>, followed immediately by
 103       an AuthenticationOk message.
 104      </p></li></ol></div></div><div class="sect2" id="SASL-OAUTHBEARER"><div class="titlepage"><div><div><h3 class="title">54.3.2. OAUTHBEARER Authentication <a href="#SASL-OAUTHBEARER" class="id_link">#</a></h3></div></div></div><p>
 105     <code class="literal">OAUTHBEARER</code> is a token-based mechanism for federated
 106     authentication. It is described in detail in
 107     <a class="ulink" href="https://datatracker.ietf.org/doc/html/rfc7628" target="_top">RFC 7628</a>.
 108    </p><p>
 109     A typical exchange differs depending on whether or not the client already
 110     has a bearer token cached for the current user. If it does not, the exchange
 111     will take place over two connections: the first "discovery" connection to
 112     obtain OAuth metadata from the server, and the second connection to send
 113     the token after the client has obtained it. (libpq does not currently
 114     implement a caching method as part of its builtin flow, so it uses the
 115     two-connection exchange.)
 116    </p><p>
 117     This mechanism is client-initiated, like SCRAM. The client initial response
 118     consists of the standard "GS2" header used by SCRAM, followed by a list of
 119     <code class="literal">key=value</code> pairs. The only key currently supported by
 120     the server is <code class="literal">auth</code>, which contains the bearer token.
 121     <code class="literal">OAUTHBEARER</code> additionally specifies three optional
 122     components of the client initial response (the <code class="literal">authzid</code> of
 123     the GS2 header, and the <code class="structfield">host</code> and
 124     <code class="structfield">port</code> keys) which are currently ignored by the
 125     server.
 126    </p><p>
 127     <code class="literal">OAUTHBEARER</code> does not support channel binding, and there
 128     is no "OAUTHBEARER-PLUS" mechanism. This mechanism does not make use of
 129     server data during a successful authentication, so the
 130     AuthenticationSASLFinal message is not used in the exchange.
 131    </p><div class="procedure" id="id-1.10.6.8.6.6"><p class="title"><strong>Example</strong></p><ol class="procedure" type="1"><li class="step"><p>
 132       During the first exchange, the server sends an AuthenticationSASL message
 133       with the <code class="literal">OAUTHBEARER</code> mechanism advertised.
 134      </p></li><li class="step"><p>
 135       The client responds by sending a SASLInitialResponse message which
 136       indicates the <code class="literal">OAUTHBEARER</code> mechanism. Assuming the
 137       client does not already have a valid bearer token for the current user,
 138       the <code class="structfield">auth</code> field is empty, indicating a discovery
 139       connection.
 140      </p></li><li class="step"><p>
 141       Server sends an AuthenticationSASLContinue message containing an error
 142       <code class="literal">status</code> alongside a well-known URI and scopes that the
 143       client should use to conduct an OAuth flow.
 144      </p></li><li class="step"><p>
 145       Client sends a SASLResponse message containing the empty set (a single
 146       <code class="literal">0x01</code> byte) to finish its half of the discovery
 147       exchange.
 148      </p></li><li class="step"><p>
 149       Server sends an ErrorMessage to fail the first exchange.
 150      </p><p>
 151       At this point, the client conducts one of many possible OAuth flows to
 152       obtain a bearer token, using any metadata that it has been configured with
 153       in addition to that provided by the server. (This description is left
 154       deliberately vague; <code class="literal">OAUTHBEARER</code> does not specify or
 155       mandate any particular method for obtaining a token.)
 156      </p><p>
 157       Once it has a token, the client reconnects to the server for the final
 158       exchange:
 159      </p></li><li class="step"><p>
 160       The server once again sends an AuthenticationSASL message with the
 161       <code class="literal">OAUTHBEARER</code> mechanism advertised.
 162      </p></li><li class="step"><p>
 163       The client responds by sending a SASLInitialResponse message, but this
 164       time the <code class="structfield">auth</code> field in the message contains the
 165       bearer token that was obtained during the client flow.
 166      </p></li><li class="step"><p>
 167       The server validates the token according to the instructions of the
 168       token provider. If the client is authorized to connect, it sends an
 169       AuthenticationOk message to end the SASL exchange.
 170      </p></li></ol></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="protocol-flow.html" title="54.2. Message Flow">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="protocol.html" title="Chapter 54. Frontend/Backend Protocol">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="protocol-replication.html" title="54.4. Streaming Replication Protocol">Next</a></td></tr><tr><td width="40%" align="left" valign="top">54.2. Message Flow </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"> 54.4. Streaming Replication Protocol</td></tr></table></div></body></html>