begriffs open source - ai-pg/blob - full-docs/txt/sasl-authentication.txt

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