begriffs open source - ai-pg/blob - full-docs/html/gssapi-auth.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>20.6. GSSAPI 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="auth-password.html" title="20.5. Password Authentication" /><link rel="next" href="sspi-auth.html" title="20.7. SSPI Authentication" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">20.6. GSSAPI Authentication</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="auth-password.html" title="20.5. Password Authentication">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="client-authentication.html" title="Chapter 20. Client Authentication">Up</a></td><th width="60%" align="center">Chapter 20. Client Authentication</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="sspi-auth.html" title="20.7. SSPI Authentication">Next</a></td></tr></table><hr /></div><div class="sect1" id="GSSAPI-AUTH"><div class="titlepage"><div><div><h2 class="title" style="clear: both">20.6. GSSAPI Authentication <a href="#GSSAPI-AUTH" class="id_link">#</a></h2></div></div></div><a id="id-1.6.7.13.2" class="indexterm"></a><p>
   3     <span class="productname">GSSAPI</span> is an industry-standard protocol
   4     for secure authentication defined in
   5     <a class="ulink" href="https://datatracker.ietf.org/doc/html/rfc2743" target="_top">RFC 2743</a>.
   6     <span class="productname">PostgreSQL</span>
   7     supports <span class="productname">GSSAPI</span> for authentication,
   8     communications encryption, or both.
   9     <span class="productname">GSSAPI</span> provides automatic authentication
  10     (single sign-on) for systems that support it. The authentication itself is
  11     secure.  If <span class="productname">GSSAPI</span> encryption
  12     or <acronym class="acronym">SSL</acronym> encryption is
  13     used, the data sent along the database connection will be encrypted;
  14     otherwise, it will not.
  15    </p><p>
  16     GSSAPI support has to be enabled when <span class="productname">PostgreSQL</span> is built;
  17     see <a class="xref" href="installation.html" title="Chapter 17. Installation from Source Code">Chapter 17</a> for more information.
  18    </p><p>
  19     When <span class="productname">GSSAPI</span> uses
  20     <span class="productname">Kerberos</span>, it uses a standard service
  21     principal (authentication identity) name in the format
  22     <code class="literal"><em class="replaceable"><code>servicename</code></em>/<em class="replaceable"><code>hostname</code></em>@<em class="replaceable"><code>realm</code></em></code>.
  23     The principal name used by a particular installation is not encoded in
  24     the <span class="productname">PostgreSQL</span> server in any way; rather it
  25     is specified in the <em class="firstterm">keytab</em> file that the server
  26     reads to determine its identity.  If multiple principals are listed in
  27     the keytab file, the server will accept any one of them.
  28     The server's realm name is the preferred realm specified in the Kerberos
  29     configuration file(s) accessible to the server.
  30    </p><p>
  31     When connecting, the client must know the principal name of the server
  32     it intends to connect to.  The <em class="replaceable"><code>servicename</code></em>
  33     part of the principal is ordinarily <code class="literal">postgres</code>,
  34     but another value can be selected via <span class="application">libpq</span>'s
  35     <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-KRBSRVNAME">krbsrvname</a> connection parameter.
  36     The <em class="replaceable"><code>hostname</code></em> part is the fully qualified
  37     host name that <span class="application">libpq</span> is told to connect to.
  38     The realm name is the preferred realm specified in the Kerberos
  39     configuration file(s) accessible to the client.
  40    </p><p>
  41     The client will also have a principal name for its own identity
  42     (and it must have a valid ticket for this principal).  To
  43     use <span class="productname">GSSAPI</span> for authentication, the client
  44     principal must be associated with
  45     a <span class="productname">PostgreSQL</span> database user name.
  46     The <code class="filename">pg_ident.conf</code> configuration file can be used
  47     to map principals to user names; for example,
  48     <code class="literal">pgusername@realm</code> could be mapped to just <code class="literal">pgusername</code>.
  49     Alternatively, you can use the full <code class="literal">username@realm</code> principal as
  50     the role name in <span class="productname">PostgreSQL</span> without any mapping.
  51    </p><p>
  52     <span class="productname">PostgreSQL</span> also supports mapping
  53     client principals to user names by just stripping the realm from
  54     the principal.  This method is supported for backwards compatibility and is
  55     strongly discouraged as it is then impossible to distinguish different users
  56     with the same user name but coming from different realms.  To enable this,
  57     set <code class="literal">include_realm</code> to 0.  For simple single-realm
  58     installations, doing that combined with setting the
  59     <code class="literal">krb_realm</code> parameter (which checks that the principal's realm
  60     matches exactly what is in the <code class="literal">krb_realm</code> parameter)
  61     is still secure; but this is a
  62     less capable approach compared to specifying an explicit mapping in
  63     <code class="filename">pg_ident.conf</code>.
  64    </p><p>
  65     The location of the server's keytab file is specified by the <a class="xref" href="runtime-config-connection.html#GUC-KRB-SERVER-KEYFILE">krb_server_keyfile</a> configuration parameter.
  66     For security reasons, it is recommended to use a separate keytab
  67     just for the <span class="productname">PostgreSQL</span> server rather
  68     than allowing the server to read the system keytab file.
  69     Make sure that your server keytab file is readable (and preferably
  70     only readable, not writable) by the <span class="productname">PostgreSQL</span>
  71     server account.  (See also <a class="xref" href="postgres-user.html" title="18.1. The PostgreSQL User Account">Section 18.1</a>.)
  72    </p><p>
  73     The keytab file is generated using the Kerberos software; see the
  74     Kerberos documentation for details. The following example shows
  75     doing this using the <span class="application">kadmin</span> tool of
  76     MIT Kerberos:
  77 </p><pre class="screen">
  78 <code class="prompt">kadmin% </code><strong class="userinput"><code>addprinc -randkey postgres/server.my.domain.org</code></strong>
  79 <code class="prompt">kadmin% </code><strong class="userinput"><code>ktadd -k krb5.keytab postgres/server.my.domain.org</code></strong>
  80 </pre><p>
  81    </p><p>
  82     The following authentication options are supported for
  83     the <span class="productname">GSSAPI</span> authentication method:
  84     </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">include_realm</code></span></dt><dd><p>
  85         If set to 0, the realm name from the authenticated user principal is
  86         stripped off before being passed through the user name mapping
  87         (<a class="xref" href="auth-username-maps.html" title="20.2. User Name Maps">Section 20.2</a>). This is discouraged and is
  88         primarily available for backwards compatibility, as it is not secure
  89         in multi-realm environments unless <code class="literal">krb_realm</code> is
  90         also used.  It is recommended to
  91         leave <code class="literal">include_realm</code> set to the default (1) and to
  92         provide an explicit mapping in <code class="filename">pg_ident.conf</code> to convert
  93         principal names to <span class="productname">PostgreSQL</span> user names.
  94        </p></dd><dt><span class="term"><code class="literal">map</code></span></dt><dd><p>
  95         Allows mapping from client principals to database user names. See
  96         <a class="xref" href="auth-username-maps.html" title="20.2. User Name Maps">Section 20.2</a> for details.  For a GSSAPI/Kerberos
  97         principal, such as <code class="literal">username@EXAMPLE.COM</code> (or, less
  98         commonly, <code class="literal">username/hostbased@EXAMPLE.COM</code>), the
  99         user name used for mapping is
 100         <code class="literal">username@EXAMPLE.COM</code> (or
 101         <code class="literal">username/hostbased@EXAMPLE.COM</code>, respectively),
 102         unless <code class="literal">include_realm</code> has been set to 0, in which case
 103         <code class="literal">username</code> (or <code class="literal">username/hostbased</code>)
 104         is what is seen as the system user name when mapping.
 105        </p></dd><dt><span class="term"><code class="literal">krb_realm</code></span></dt><dd><p>
 106         Sets the realm to match user principal names against. If this parameter
 107         is set, only users of that realm will be accepted.  If it is not set,
 108         users of any realm can connect, subject to whatever user name mapping
 109         is done.
 110        </p></dd></dl></div><p>
 111    </p><p>
 112     In addition to these settings, which can be different for
 113     different <code class="filename">pg_hba.conf</code> entries, there is the
 114     server-wide <a class="xref" href="runtime-config-connection.html#GUC-KRB-CASEINS-USERS">krb_caseins_users</a> configuration
 115     parameter.  If that is set to true, client principals are matched to
 116     user map entries case-insensitively.  <code class="literal">krb_realm</code>, if
 117     set, is also matched case-insensitively.
 118    </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="auth-password.html" title="20.5. Password Authentication">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="client-authentication.html" title="Chapter 20. Client Authentication">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sspi-auth.html" title="20.7. SSPI Authentication">Next</a></td></tr><tr><td width="40%" align="left" valign="top">20.5. Password Authentication </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"> 20.7. SSPI Authentication</td></tr></table></div></body></html>