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:40:11 -0400 |
| commit | edfef090a555b3cc820821437389d05c041279e0 (patch) | |
| tree | ea8f845efe74fbcd397ece132eb8ea5ffb4107f1 | |
| parent | b9ded152904bba708a4332cf535098be46bb20b2 (diff) | |
| download | postgresql-edfef090a555b3cc820821437389d05c041279e0.tar.gz postgresql-edfef090a555b3cc820821437389d05c041279e0.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 4f0ede8aa86..369ed47469a 100644 --- a/doc/src/sgml/client-auth.sgml +++ b/doc/src/sgml/client-auth.sgml @@ -944,7 +944,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> @@ -954,12 +959,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> @@ -1017,7 +1026,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> @@ -1027,7 +1041,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> |