diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml index d698dbd96f..82445547a1 100644 --- a/doc/src/sgml/client-auth.sgml +++ b/doc/src/sgml/client-auth.sgml @@ -834,7 +834,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. @@ -844,12 +849,16 @@ 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 + 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 + username@EXAMPLE.COM (or + username/hostbased@EXAMPLE.COM) + is what is seen as the system username when mapping. @@ -905,7 +914,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. @@ -915,7 +929,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 username@EXAMPLE.COM (or, less + commonly, username/hostbased@EXAMPLE.COM), 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 + username@EXAMPLE.COM (or + username/hostbased@EXAMPLE.COM) + is what is seen as the system username when mapping.