begriffs open source - ai-pg/blob - full-docs/txt/gssapi-auth.txt

   1
   2 20.6. GSSAPI Authentication #
   3
   4    GSSAPI is an industry-standard protocol for secure authentication
   5    defined in RFC 2743. PostgreSQL supports GSSAPI for authentication,
   6    communications encryption, or both. GSSAPI provides automatic
   7    authentication (single sign-on) for systems that support it. The
   8    authentication itself is secure. If GSSAPI encryption or SSL encryption
   9    is used, the data sent along the database connection will be encrypted;
  10    otherwise, it will not.
  11
  12    GSSAPI support has to be enabled when PostgreSQL is built; see
  13    Chapter 17 for more information.
  14
  15    When GSSAPI uses Kerberos, it uses a standard service principal
  16    (authentication identity) name in the format
  17    servicename/hostname@realm. The principal name used by a particular
  18    installation is not encoded in the PostgreSQL server in any way; rather
  19    it is specified in the keytab file that the server reads to determine
  20    its identity. If multiple principals are listed in the keytab file, the
  21    server will accept any one of them. The server's realm name is the
  22    preferred realm specified in the Kerberos configuration file(s)
  23    accessible to the server.
  24
  25    When connecting, the client must know the principal name of the server
  26    it intends to connect to. The servicename part of the principal is
  27    ordinarily postgres, but another value can be selected via libpq's
  28    krbsrvname connection parameter. The hostname part is the fully
  29    qualified host name that libpq is told to connect to. The realm name is
  30    the preferred realm specified in the Kerberos configuration file(s)
  31    accessible to the client.
  32
  33    The client will also have a principal name for its own identity (and it
  34    must have a valid ticket for this principal). To use GSSAPI for
  35    authentication, the client principal must be associated with a
  36    PostgreSQL database user name. The pg_ident.conf configuration file can
  37    be used to map principals to user names; for example, pgusername@realm
  38    could be mapped to just pgusername. Alternatively, you can use the full
  39    username@realm principal as the role name in PostgreSQL without any
  40    mapping.
  41
  42    PostgreSQL also supports mapping client principals to user names by
  43    just stripping the realm from the principal. This method is supported
  44    for backwards compatibility and is strongly discouraged as it is then
  45    impossible to distinguish different users with the same user name but
  46    coming from different realms. To enable this, set include_realm to 0.
  47    For simple single-realm installations, doing that combined with setting
  48    the krb_realm parameter (which checks that the principal's realm
  49    matches exactly what is in the krb_realm parameter) is still secure;
  50    but this is a less capable approach compared to specifying an explicit
  51    mapping in pg_ident.conf.
  52
  53    The location of the server's keytab file is specified by the
  54    krb_server_keyfile configuration parameter. For security reasons, it is
  55    recommended to use a separate keytab just for the PostgreSQL server
  56    rather than allowing the server to read the system keytab file. Make
  57    sure that your server keytab file is readable (and preferably only
  58    readable, not writable) by the PostgreSQL server account. (See also
  59    Section 18.1.)
  60
  61    The keytab file is generated using the Kerberos software; see the
  62    Kerberos documentation for details. The following example shows doing
  63    this using the kadmin tool of MIT Kerberos:
  64 kadmin% addprinc -randkey postgres/server.my.domain.org
  65 kadmin% ktadd -k krb5.keytab postgres/server.my.domain.org
  66
  67    The following authentication options are supported for the GSSAPI
  68    authentication method:
  69
  70    include_realm
  71           If set to 0, the realm name from the authenticated user
  72           principal is stripped off before being passed through the user
  73           name mapping (Section 20.2). This is discouraged and is
  74           primarily available for backwards compatibility, as it is not
  75           secure in multi-realm environments unless krb_realm is also
  76           used. It is recommended to leave include_realm set to the
  77           default (1) and to provide an explicit mapping in pg_ident.conf
  78           to convert principal names to PostgreSQL user names.
  79
  80    map
  81           Allows mapping from client principals to database user names.
  82           See Section 20.2 for details. For a GSSAPI/Kerberos principal,
  83           such as username@EXAMPLE.COM (or, less commonly,
  84           username/hostbased@EXAMPLE.COM), the user name used for mapping
  85           is username@EXAMPLE.COM (or username/hostbased@EXAMPLE.COM,
  86           respectively), unless include_realm has been set to 0, in which
  87           case username (or username/hostbased) is what is seen as the
  88           system user name when mapping.
  89
  90    krb_realm
  91           Sets the realm to match user principal names against. If this
  92           parameter is set, only users of that realm will be accepted. If
  93           it is not set, users of any realm can connect, subject to
  94           whatever user name mapping is done.
  95
  96    In addition to these settings, which can be different for different
  97    pg_hba.conf entries, there is the server-wide krb_caseins_users
  98    configuration parameter. If that is set to true, client principals are
  99    matched to user map entries case-insensitively. krb_realm, if set, is
 100    also matched case-insensitively.