| Server IP : 104.21.25.180 / Your IP : 162.159.115.41 Web Server : Apache/2.4.37 System : Linux almalinux.duckdns.org 4.18.0-553.111.1.el8_10.x86_64 #1 SMP Sun Mar 8 20:06:07 EDT 2026 x86_64 User : ricodeal ( 1046) PHP Version : 7.4.33 Disable Function : NONE MySQL : OFF | cURL : ON | WGET : ON | Perl : ON | Python : ON | Sudo : ON | Pkexec : ON Directory : /usr/share/doc/postgresql-docs/html/ |
Upload File : |
<?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>52.3. SASL Authentication</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="[email protected]" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="protocol-flow.html" title="52.2. Message Flow" /><link rel="next" href="protocol-replication.html" title="52.4. Streaming Replication Protocol" /></head><body><div xmlns="http://www.w3.org/TR/xhtml1/transitional" class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">52.3. SASL Authentication</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="protocol-flow.html" title="52.2. Message Flow">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="protocol.html" title="Chapter 52. Frontend/Backend Protocol">Up</a></td><th width="60%" align="center">Chapter 52. Frontend/Backend Protocol</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 10.23 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="protocol-replication.html" title="52.4. Streaming Replication Protocol">Next</a></td></tr></table><hr></hr></div><div class="sect1" id="SASL-AUTHENTICATION"><div class="titlepage"><div><div><h2 class="title" style="clear: both">52.3. SASL Authentication</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="sasl-authentication.html#SASL-SCRAM-SHA-256">52.3.1. SCRAM-SHA-256 authentication</a></span></dt></dl></div><p><em class="firstterm">SASL</em> is a framework for authentication in connection-oriented
protocols. At the moment, <span class="productname">PostgreSQL</span> implements only one SASL
authentication mechanism, SCRAM-SHA-256, but more might be added in the
future. The below steps illustrate how SASL authentication is performed in
general, while the next subsection gives more details on SCRAM-SHA-256.</p><div class="procedure" id="id-1.10.5.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> To begin a SASL authentication exchange, the server sends an
AuthenticationSASL message. It includes a list of SASL authentication
mechanisms that the server can accept, in the server's preferred order.</p></li><li class="step" id="SASL-AUTH-INITIAL-RESPONSE"><p> The client selects one of the supported mechanisms from the list, and sends
a SASLInitialResponse message to the server. The message includes the name
of the selected mechanism, and an optional Initial Client Response, if the
selected mechanism uses that.</p></li><li class="step" id="SASL-AUTH-CONTINUE"><p> One or more server-challenge and client-response message will follow. Each
server-challenge is sent in an AuthenticationSASLContinue message, followed
by a response from client in an SASLResponse message. The particulars of
the messages are mechanism specific.</p></li><li class="step" id="SASL-AUTH-END"><p> Finally, when the authentication exchange is completed successfully, the
server sends an AuthenticationSASLFinal message, followed
immediately by an AuthenticationOk message. The AuthenticationSASLFinal
contains additional server-to-client data, whose content is particular to the
selected authentication mechanism. If the authentication mechanism doesn't
use additional data that's sent at completion, the AuthenticationSASLFinal
message is not sent.</p></li></ol></div><p>On error, the server can abort the authentication at any stage, and send an
ErrorMessage.</p><div class="sect2" id="SASL-SCRAM-SHA-256"><div class="titlepage"><div><div><h3 class="title">52.3.1. SCRAM-SHA-256 authentication</h3></div></div></div><p> <em class="firstterm">SCRAM-SHA-256</em> (called just <em class="firstterm">SCRAM</em> from now on) is
the only implemented SASL mechanism, at the moment. It is described in detail
in RFC 7677 and RFC 5802.
</p><p>When SCRAM-SHA-256 is used in PostgreSQL, the server will ignore the user name
that the client sends in the <code class="structname">client-first-message</code>. The user name
that was already sent in the startup message is used instead.
<span class="productname">PostgreSQL</span> supports multiple character encodings, while SCRAM
dictates UTF-8 to be used for the user name, so it might be impossible to
represent the PostgreSQL user name in UTF-8.
</p><p>The SCRAM specification dictates that the password is also in UTF-8, and is
processed with the <em class="firstterm">SASLprep</em> algorithm.
<span class="productname">PostgreSQL</span>, however, does not require UTF-8 to be used for
the password. When a user's password is set, it is processed with SASLprep
as if it was in UTF-8, regardless of the actual encoding used. However, if
it is not a legal UTF-8 byte sequence, or it contains UTF-8 byte sequences
that are prohibited by the SASLprep algorithm, the raw password will be used
without SASLprep processing, instead of throwing an error. This allows the
password to be normalized when it is in UTF-8, but still allows a non-UTF-8
password to be used, and doesn't require the system to know which encoding
the password is in.
</p><p><em class="firstterm">Channel binding</em> has not been implemented yet.
</p><div class="procedure" id="id-1.10.5.8.5.6"><p class="title"><strong>Example</strong></p><ol class="procedure" type="1"><li class="step" id="SCRAM-BEGIN"><p> The server sends an AuthenticationSASL message. It includes a list of
SASL authentication mechanisms that the server can accept.</p></li><li class="step" id="SCRAM-CLIENT-FIRST"><p> The client responds by sending a SASLInitialResponse message, which
indicates the chosen mechanism, <code class="literal">SCRAM-SHA-256</code>. In the Initial
Client response field, the message contains the SCRAM
<code class="structname">client-first-message</code>.</p></li><li class="step" id="SCRAM-SERVER-FIRST"><p> Server sends an AuthenticationSASLContinue message, with a SCRAM
<code class="structname">server-first-message</code> as the content.</p></li><li class="step" id="SCRAM-CLIENT-FINAL"><p> Client sends a SASLResponse message, with SCRAM
<code class="structname">client-final-message</code> as the content.</p></li><li class="step" id="SCRAM-SERVER-FINAL"><p> Server sends an AuthenticationSASLFinal message, with the SCRAM
<code class="structname">server-final-message</code>, followed immediately by
an AuthenticationOk message.</p></li></ol></div></div></div><div xmlns="http://www.w3.org/TR/xhtml1/transitional" class="navfooter"><hr></hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="protocol-flow.html" title="52.2. Message Flow">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="protocol.html" title="Chapter 52. Frontend/Backend Protocol">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="protocol-replication.html" title="52.4. Streaming Replication Protocol">Next</a></td></tr><tr><td width="40%" align="left" valign="top">52.2. Message Flow </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 10.23 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 52.4. Streaming Replication Protocol</td></tr></table></div></body></html>