method specifications
    in <filename>pg_hba.conf</filename> to <literal>scram-sha-256</literal>.
   </para>
  </sect1>

  <sect1 id="gssapi-auth">
   <title>GSSAPI Authentication</title>

   <indexterm zone="gssapi-auth">
    <primary>GSSAPI</primary>
   </indexterm>

   <para>
    <productname>GSSAPI</productname> is an industry-standard protocol
    for secure authentication defined in
    <ulink url="https://datatracker.ietf.org/doc/html/rfc2743">RFC 2743</ulink>.
    <productname>PostgreSQL</productname>
    supports <productname>GSSAPI</productname> for authentication,
    communications encryption, or both.
    <productname>GSSAPI</productname> provides automatic authentication
    (single sign-on) for systems that support it. The authentication itself is
    secure.  If <productname>GSSAPI</productname> encryption
    or <acronym>SSL</acronym> encryption is
    used, the data sent along the database connection will be encrypted;
    otherwise, it will not.
   </para>

   <para>
    GSSAPI support has to be enabled when <productname>PostgreSQL</productname> is built;
    see <xref linkend="installation"/> for more information.
   </para>

   <para>
    When <productname>GSSAPI</productname> uses
    <productname>Kerberos</productname>, it uses a standard service
    principal (authentication identity) name in the format
    <literal><replaceable>servicename</replaceable>/<replaceable>hostname</replaceable>@<replaceable>realm</replaceable></literal>.
    The principal name used by a particular installation is not encoded in
    the <productname>PostgreSQL</productname> server in any way; rather it
    is specified in the <firstterm>keytab</firstterm> file that the server
    reads to determine its identity.  If multiple principals are listed in
    the keytab file, the server will accept any one of them.
    The server's realm name is the preferred realm specified in the Kerberos
    configuration file(s) accessible to the server.
   </para>

   <para>
    When connecting, the client must know the principal name of the server
    it intends to connect to.  The <replaceable>servicename</replaceable>
    part of the principal is ordinarily <literal>postgres</literal>,
    but another value can be selected via <application>libpq</application>'s
    <xref linkend="libpq-connect-krbsrvname"/> connection parameter.
    The <replaceable>hostname</replaceable> part is the fully qualified
    host name that <application>libpq</application> is told to connect to.
    The realm name is the preferred realm specified in the Kerberos
    configuration file(s) accessible to the client.
   </para>

   <para>
    The client will also have a principal name for its own identity
    (and it must have a valid ticket for this principal).  To
    use <productname>GSSAPI</productname> for authentication, the client
    principal must be associated with
    a <productname>PostgreSQL</productname> database user name.
    The <filename>pg_ident.conf</filename> configuration file can be used
    to map principals to user names; for example,
    <literal>pgusername@realm</literal> could be mapped to just <literal>pgusername</literal>.
    Alternatively, you can use the full <literal>username@realm</literal> principal as
    the role name in <productname>PostgreSQL</productname> without any mapping.
   </para>

   <para>
    <productname>PostgreSQL</productname> also supports mapping
    client principals to user names by just stripping the realm from
    the principal.  This method is supported for backwards compatibility and is
    strongly discouraged as it is then impossible to distinguish different users
    with the same user name but coming from different realms.  To enable this,
    set <literal>include_realm</literal> to 0.  For simple single-realm
    installations, doing that combined with setting the
    <literal>krb_realm</literal> parameter (which checks that the principal's realm
    matches exactly what is in the <literal>krb_realm</literal>