From c106f397d1199b1f835c2dbbfceb1907822afd00 Mon Sep 17 00:00:00 2001 From: Stephen Frost Date: Fri, 8 May 2015 19:39:52 -0400 Subject: [PATCH] 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. --- doc/src/sgml/client-auth.sgml | 41 +++++++++++++++++++++++++++-------- 1 file changed, 32 insertions(+), 9 deletions(-) diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml index d27dd49145..9bb8a94b91 100644 --- 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/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. @@ -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 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. -- 2.40.0