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:06 -0400 |
| commit | 3de791ee766779f89e399da6316e0d280de6ecaa (patch) | |
| tree | f5b695c6c43fcd4a8075278bda54ac62d595e109 | |
| parent | 596fb5aa73e6073bf870a9093941f937921ad4a4 (diff) | |
| download | postgresql-3de791ee766779f89e399da6316e0d280de6ecaa.tar.gz postgresql-3de791ee766779f89e399da6316e0d280de6ecaa.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 f390bca85c3..7deaa62a17d 100644 --- a/doc/src/sgml/client-auth.sgml +++ b/doc/src/sgml/client-auth.sgml @@ -951,7 +951,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> @@ -961,12 +966,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> @@ -1024,7 +1033,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> @@ -1034,7 +1048,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> |