codekingpro/portable-devtools

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>21.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="21.5. Password Authentication" /><link rel="next" href="sspi-auth.html" title="21.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">21.6. GSSAPI Authentication</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="auth-password.html" title="21.5. Password Authentication">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="client-authentication.html" title="Chapter 21. Client Authentication">Up</a></td><th width="60%" align="center">Chapter 21. Client Authentication</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 16.3 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sspi-auth.html" title="21.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">21.6. GSSAPI Authentication <a href="#GSSAPI-AUTH" class="id_link">#</a></h2></div></div></div><a id="id-1.6.8.13.2" class="indexterm"></a><p>3    <span class="productname">GSSAPI</span> is an industry-standard protocol4    for secure authentication defined in5    <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 authentication10    (single sign-on) for systems that support it. The authentication itself is11    secure.  If <span class="productname">GSSAPI</span> encryption12    or <acronym class="acronym">SSL</acronym> encryption is13    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> uses20    <span class="productname">Kerberos</span>, it uses a standard service21    principal (authentication identity) name in the format22    <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 in24    the <span class="productname">PostgreSQL</span> server in any way; rather it25    is specified in the <em class="firstterm">keytab</em> file that the server26    reads to determine its identity.  If multiple principals are listed in27    the keytab file, the server will accept any one of them.28    The server's realm name is the preferred realm specified in the Kerberos29    configuration file(s) accessible to the server.30   </p><p>31    When connecting, the client must know the principal name of the server32    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>'s35    <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 qualified37    host name that <span class="application">libpq</span> is told to connect to.38    The realm name is the preferred realm specified in the Kerberos39    configuration file(s) accessible to the client.40   </p><p>41    The client will also have a principal name for its own identity42    (and it must have a valid ticket for this principal).  To43    use <span class="productname">GSSAPI</span> for authentication, the client44    principal must be associated with45    a <span class="productname">PostgreSQL</span> database user name.46    The <code class="filename">pg_ident.conf</code> configuration file can be used47    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 as50    the role name in <span class="productname">PostgreSQL</span> without any mapping.51   </p><p>52    <span class="productname">PostgreSQL</span> also supports mapping53    client principals to user names by just stripping the realm from54    the principal.  This method is supported for backwards compatibility and is55    strongly discouraged as it is then impossible to distinguish different users56    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-realm58    installations, doing that combined with setting the59    <code class="literal">krb_realm</code> parameter (which checks that the principal's realm60    matches exactly what is in the <code class="literal">krb_realm</code> parameter)61    is still secure; but this is a62    less capable approach compared to specifying an explicit mapping in63    <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 keytab67    just for the <span class="productname">PostgreSQL</span> server rather68    than allowing the server to read the system keytab file.69    Make sure that your server keytab file is readable (and preferably70    only readable, not writable) by the <span class="productname">PostgreSQL</span>71    server account.  (See also <a class="xref" href="postgres-user.html" title="19.1. The PostgreSQL User Account">Section 19.1</a>.)72   </p><p>73    The keytab file is generated using the Kerberos software; see the74    Kerberos documentation for details. The following example shows75    doing this using the <span class="application">kadmin</span> tool of76    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 for83    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 is86        stripped off before being passed through the user name mapping87        (<a class="xref" href="auth-username-maps.html" title="21.2. User Name Maps">Section 21.2</a>). This is discouraged and is88        primarily available for backwards compatibility, as it is not secure89        in multi-realm environments unless <code class="literal">krb_realm</code> is90        also used.  It is recommended to91        leave <code class="literal">include_realm</code> set to the default (1) and to92        provide an explicit mapping in <code class="filename">pg_ident.conf</code> to convert93        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. See96        <a class="xref" href="auth-username-maps.html" title="21.2. User Name Maps">Section 21.2</a> for details.  For a GSSAPI/Kerberos97        principal, such as <code class="literal">username@EXAMPLE.COM</code> (or, less98        commonly, <code class="literal">username/hostbased@EXAMPLE.COM</code>), the99        user name used for mapping is100        <code class="literal">username@EXAMPLE.COM</code> (or101        <code class="literal">username/hostbased@EXAMPLE.COM</code>, respectively),102        unless <code class="literal">include_realm</code> has been set to 0, in which case103        <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 parameter107        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 mapping109        is done.110       </p></dd></dl></div><p>111   </p><p>112    In addition to these settings, which can be different for113    different <code class="filename">pg_hba.conf</code> entries, there is the114    server-wide <a class="xref" href="runtime-config-connection.html#GUC-KRB-CASEINS-USERS">krb_caseins_users</a> configuration115    parameter.  If that is set to true, client principals are matched to116    user map entries case-insensitively.  <code class="literal">krb_realm</code>, if117    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="21.5. Password Authentication">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="client-authentication.html" title="Chapter 21. Client Authentication">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sspi-auth.html" title="21.7. SSPI Authentication">Next</a></td></tr><tr><td width="40%" align="left" valign="top">21.5. Password Authentication </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 16.3 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 21.7. SSPI Authentication</td></tr></table></div></body></html>