Recommend include_realm=1 in docs

As discussed, the default setting of include_realm=0 can be dangerous in
multi-realm environments because it is then impossible to differentiate
users with the same username but who are from two different realms.

Recommend include_realm=1 and note that the default setting may change
in a future version of PostgreSQL and therefore users may wish to
explicitly set include_realm to avoid issues while upgrading.

diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml
index d27dd491458ed5eeee2db798b40617870fc586ee..9bb8a94b9193f2a22b3a5a2f99791216de0201b4 100644 (file)
--- a/doc/src/sgml/client-auth.sgml
+++ b/doc/src/sgml/client-auth.sgml
@@ -1000,7 +1000,12 @@ omicron         bryanh                  guest1
         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.
+        the recommended configuration as, otherwise, it is impossible to
+        differentiate users with the same username who are from different
+        realms.  The default for this parameter is 0 (meaning to not include
+        the realm in the system user name) but may change to 1 in a future
+        version of PostgreSQL.  Users can set it
+        explicitly to avoid any issues when upgrading.
        
       
      
@@ -1010,12 +1015,16 @@ omicron         bryanh                  guest1
       
        
         Allows for mapping between system and database user names. See
-         for details. For a Kerberos
-        principal username/[email protected], the
-        user name used for mapping is username/hostbased
-        if include_realm is disabled, and
-        username/[email protected] if
-        include_realm is enabled.
+         for details.  For a GSSAPI/Kerberos
+        principal, such as [email protected] (or, less
+        commonly, username/[email protected]), the
+        default user name used for mapping is
+        username (or username/hostbased,
+        respectfully), unless include_realm has been set to
+        1 (as recommended, see above), in which case
+        [email protected] (or
+        username/[email protected])
+        is what is seen as the system username when mapping.
        
       
      
@@ -1073,7 +1082,12 @@ omicron         bryanh                  guest1
         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.
+        the recommended configuration as, otherwise, it is impossible to
+        differentiate users with the same username who are from different
+        realms.  The default for this parameter is 0 (meaning to not include
+        the realm in the system user name) but may change to 1 in a future
+        version of PostgreSQL.  Users can set it
+        explicitly to avoid any issues when upgrading.
        
       
      
@@ -1083,7 +1097,16 @@ omicron         bryanh                  guest1
       
        
         Allows for mapping between system and database user names. See
-         for details.
+         for details.  For a SSPI/Kerberos
+        principal, such as [email protected] (or, less
+        commonly, username/[email protected]), the
+        default user name used for mapping is
+        username (or username/hostbased,
+        respectfully), unless include_realm has been set to
+        1 (as recommended, see above), in which case
+        [email protected] (or
+        username/[email protected])
+        is what is seen as the system username when mapping.