diff options
| author | Stephen Frost <sfrost@snowman.net> | 2015-05-08 19:39:52 -0400 |
|---|---|---|
| committer | Stephen Frost <sfrost@snowman.net> | 2015-05-08 19:39:52 -0400 |
| commit | c106f397d1199b1f835c2dbbfceb1907822afd00 (patch) | |
| tree | d3f2543062fdc4a077b234094e7204deacbee92c | |
| parent | 3ecab37d97ed72bf81fd042dcef10e7111369875 (diff) | |
| download | postgresql-c106f397d1199b1f835c2dbbfceb1907822afd00.tar.gz postgresql-c106f397d1199b1f835c2dbbfceb1907822afd00.zip | |
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.
| -rw-r--r-- | doc/src/sgml/client-auth.sgml | 41 |
1 files changed, 32 insertions, 9 deletions
diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml index d27dd491458..9bb8a94b919 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 (<xref linkend="auth-username-maps">). 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 <productname>PostgreSQL</productname>. Users can set it + explicitly to avoid any issues when upgrading. </para> </listitem> </varlistentry> @@ -1010,12 +1015,16 @@ omicron bryanh guest1 <listitem> <para> Allows for mapping between system and database user names. See - <xref linkend="auth-username-maps"> for details. For a Kerberos - principal <literal>username/hostbased@EXAMPLE.COM</literal>, the - user name used for mapping is <literal>username/hostbased</literal> - if <literal>include_realm</literal> is disabled, and - <literal>username/hostbased@EXAMPLE.COM</literal> if - <literal>include_realm</literal> is enabled. + <xref linkend="auth-username-maps"> for details. For a GSSAPI/Kerberos + principal, such as <literal>username@EXAMPLE.COM</literal> (or, less + commonly, <literal>username/hostbased@EXAMPLE.COM</literal>), the + default user name used for mapping is + <literal>username</literal> (or <literal>username/hostbased</literal>, + respectfully), unless <literal>include_realm</literal> has been set to + 1 (as recommended, see above), in which case + <literal>username@EXAMPLE.COM</literal> (or + <literal>username/hostbased@EXAMPLE.COM</literal>) + is what is seen as the system username when mapping. </para> </listitem> </varlistentry> @@ -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 (<xref linkend="auth-username-maps">). 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 <productname>PostgreSQL</productname>. Users can set it + explicitly to avoid any issues when upgrading. </para> </listitem> </varlistentry> @@ -1083,7 +1097,16 @@ omicron bryanh guest1 <listitem> <para> Allows for mapping between system and database user names. See - <xref linkend="auth-username-maps"> for details. + <xref linkend="auth-username-maps"> for details. For a SSPI/Kerberos + principal, such as <literal>username@EXAMPLE.COM</literal> (or, less + commonly, <literal>username/hostbased@EXAMPLE.COM</literal>), the + default user name used for mapping is + <literal>username</literal> (or <literal>username/hostbased</literal>, + respectfully), unless <literal>include_realm</literal> has been set to + 1 (as recommended, see above), in which case + <literal>username@EXAMPLE.COM</literal> (or + <literal>username/hostbased@EXAMPLE.COM</literal>) + is what is seen as the system username when mapping. </para> </listitem> </varlistentry> |