diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml
index d27dd49145..620ddc6239 100644
--- a/doc/src/sgml/client-auth.sgml
+++ b/doc/src/sgml/client-auth.sgml
@@ -947,15 +947,24 @@ omicron bryanh guest1
- Client principals must have their PostgreSQL database user
- name as their first component, for example
- pgusername@realm. Alternatively, you can use a user name
- mapping to map from the first component of the principal name to the
- database user name. By default, the realm of the client is
- not checked by PostgreSQL. If you have cross-realm
- authentication enabled and need to verify the realm, use the
- krb_realm parameter, or enable include_realm
- and use user name mapping to check the realm.
+ Client principals can be mapped to different PostgreSQL
+ database user names with pg_ident.conf. For example,
+ pgusername@realm could be mapped to just pgusername.
+ Alternatively, you can use the full username@realm principal as
+ the role name in PostgreSQL without any mapping.
+
+
+
+ PostgreSQL also supports a parameter to strip 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 username but coming from different realms. To enable this,
+ set include_realm to 0. For simple single-realm
+ installations, include_realm combined with the
+ krb_realm parameter (which checks that the realm provided
+ matches exactly what is in the krb_realm parameter) would be a secure but
+ less capable option compared to specifying an explicit mapping in
+ pg_ident.conf.
@@ -997,10 +1006,13 @@ omicron bryanh guest1
include_realm
- If set to 1, the realm name from the authenticated user
- principal is included in the system user name that's passed through
- user name mapping (). This is
- useful for handling users from multiple realms.
+ If set to 0, the realm name from the authenticated user principal is
+ stripped off before being passed through the user name mapping
+ (). This is discouraged and is
+ primairly available for backwards compatibility as it is not secure
+ in multi-realm environments unless krb_realm is also used. Users
+ are recommended to leave include_realm set to the default (1) and to
+ provide an explicit mapping in pg_ident.conf.
@@ -1010,12 +1022,15 @@ omicron bryanh guest1
Allows for mapping between system and database user names. See
- for details. For a Kerberos
- principal username/hostbased@EXAMPLE.COM, the
- user name used for mapping is username/hostbased
- if include_realm is disabled, and
- username/hostbased@EXAMPLE.COM if
- include_realm is enabled.
+ for details. For a GSSAPI/Kerberos
+ principal, such as username@EXAMPLE.COM (or, less
+ commonly, username/hostbased@EXAMPLE.COM), the
+ user name used for mapping is
+ username@EXAMPLE.COM (or
+ username/hostbased@EXAMPLE.COM, respectfully),
+ unless include_realm has been set to 0, in which case
+ username (or username/hostbased)
+ is what is seen as the system username when mapping.
@@ -1070,10 +1085,13 @@ omicron bryanh guest1
include_realm
- If set to 1, the realm name from the authenticated user
- principal is included in the system user name that's passed through
- user name mapping (). This is
- useful for handling users from multiple realms.
+ If set to 0, the realm name from the authenticated user principal is
+ stripped off before being passed through the user name mapping
+ (). This is discouraged and is
+ primairly available for backwards compatibility as it is not secure
+ in multi-realm environments unless krb_realm is also used. Users
+ are recommended to leave include_realm set to the default (1) and to
+ provide an explicit mapping in pg_ident.conf.
@@ -1083,7 +1101,15 @@ omicron bryanh guest1
Allows for mapping between system and database user names. See
- for details.
+ for details. For a SSPI/Kerberos
+ principal, such as username@EXAMPLE.COM (or, less
+ commonly, username/hostbased@EXAMPLE.COM), the
+ user name used for mapping is
+ username@EXAMPLE.COM (or
+ username/hostbased@EXAMPLE.COM, respectfully),
+ unless include_realm has been set to 0, in which case
+ username (or username/hostbased)
+ is what is seen as the system username when mapping.
diff --git a/src/backend/libpq/hba.c b/src/backend/libpq/hba.c
index a0f5396036..c23938580b 100644
--- a/src/backend/libpq/hba.c
+++ b/src/backend/libpq/hba.c
@@ -1376,6 +1376,19 @@ parse_hba_auth_opt(char *name, char *val, HbaLine *hbaline, int line_num)
hbaline->ldapscope = LDAP_SCOPE_SUBTREE;
#endif
+ /*
+ * For GSS and SSPI, set the default value of include_realm to true.
+ * Having include_realm set to false is dangerous in multi-realm
+ * situations and is generally considered bad practice. We keep the
+ * capability around for backwards compatibility, but we might want to
+ * remove it at some point in the future. Users who still need to strip
+ * the realm off would be better served by using an appropriate regex in
+ * a pg_ident.conf mapping.
+ */
+ if (hbaline->auth_method == uaGSS ||
+ hbaline->auth_method == uaSSPI)
+ hbaline->include_realm = true;
+
if (strcmp(name, "map") == 0)
{
if (hbaline->auth_method != uaIdent &&