diff options
| -rw-r--r-- | doc/src/sgml/client-auth.sgml | 74 | ||||
| -rw-r--r-- | src/backend/libpq/hba.c | 13 |
2 files changed, 63 insertions, 24 deletions
diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml index d27dd49145..620ddc6239 100644 --- a/doc/src/sgml/client-auth.sgml +++ b/doc/src/sgml/client-auth.sgml @@ -947,15 +947,24 @@ omicron bryanh guest1 </para> <para> - Client principals must have their <productname>PostgreSQL</> database user - name as their first component, for example - <literal>pgusername@realm</>. Alternatively, you can use a user name - mapping to map from the first component of the principal name to the - database user name. By default, the realm of the client is - not checked by <productname>PostgreSQL</>. If you have cross-realm - authentication enabled and need to verify the realm, use the - <literal>krb_realm</> parameter, or enable <literal>include_realm</> - and use user name mapping to check the realm. + Client principals can be mapped to different <productname>PostgreSQL</> + database user names with <filename>pg_ident.conf</>. For example, + <literal>pgusername@realm</> could be mapped to just <literal>pgusername</>. + Alternatively, you can use the full <literal>username@realm</> principal as + the role name in <productname>PostgreSQL</> without any mapping. + </para> + + <para> + <productname>PostgreSQL</> also supports a parameter to strip the realm from + the principal. This method is supported for backwards compatibility and is + strongly discouraged as it is then impossible to distinguish different users + with the same username but coming from different realms. To enable this, + set <literal>include_realm</> to 0. For simple single-realm + installations, <literal>include_realm</> combined with the + <literal>krb_realm</> parameter (which checks that the realm provided + matches exactly what is in the krb_realm parameter) would be a secure but + less capable option compared to specifying an explicit mapping in + <filename>pg_ident.conf</>. </para> <para> @@ -997,10 +1006,13 @@ omicron bryanh guest1 <term><literal>include_realm</literal></term> <listitem> <para> - 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. + If set to 0, the realm name from the authenticated user principal is + stripped off before being passed through the user name mapping + (<xref linkend="auth-username-maps">). This is discouraged and is + primairly available for backwards compatibility as it is not secure + in multi-realm environments unless krb_realm is also used. Users + are recommended to leave include_realm set to the default (1) and to + provide an explicit mapping in <filename>pg_ident.conf</>. </para> </listitem> </varlistentry> @@ -1010,12 +1022,15 @@ 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 + user name used for mapping is + <literal>username@EXAMPLE.COM</literal> (or + <literal>username/hostbased@EXAMPLE.COM</literal>, respectfully), + unless <literal>include_realm</literal> has been set to 0, in which case + <literal>username</literal> (or <literal>username/hostbased</literal>) + is what is seen as the system username when mapping. </para> </listitem> </varlistentry> @@ -1070,10 +1085,13 @@ omicron bryanh guest1 <term><literal>include_realm</literal></term> <listitem> <para> - 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. + If set to 0, the realm name from the authenticated user principal is + stripped off before being passed through the user name mapping + (<xref linkend="auth-username-maps">). This is discouraged and is + primairly available for backwards compatibility as it is not secure + in multi-realm environments unless krb_realm is also used. Users + are recommended to leave include_realm set to the default (1) and to + provide an explicit mapping in <filename>pg_ident.conf</>. </para> </listitem> </varlistentry> @@ -1083,7 +1101,15 @@ 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 + user name used for mapping is + <literal>username@EXAMPLE.COM</literal> (or + <literal>username/hostbased@EXAMPLE.COM</literal>, respectfully), + unless <literal>include_realm</literal> has been set to 0, in which case + <literal>username</literal> (or <literal>username/hostbased</literal>) + is what is seen as the system username when mapping. </para> </listitem> </varlistentry> diff --git a/src/backend/libpq/hba.c b/src/backend/libpq/hba.c index a0f5396036..c23938580b 100644 --- a/src/backend/libpq/hba.c +++ b/src/backend/libpq/hba.c @@ -1376,6 +1376,19 @@ parse_hba_auth_opt(char *name, char *val, HbaLine *hbaline, int line_num) hbaline->ldapscope = LDAP_SCOPE_SUBTREE; #endif + /* + * For GSS and SSPI, set the default value of include_realm to true. + * Having include_realm set to false is dangerous in multi-realm + * situations and is generally considered bad practice. We keep the + * capability around for backwards compatibility, but we might want to + * remove it at some point in the future. Users who still need to strip + * the realm off would be better served by using an appropriate regex in + * a pg_ident.conf mapping. + */ + if (hbaline->auth_method == uaGSS || + hbaline->auth_method == uaSSPI) + hbaline->include_realm = true; + if (strcmp(name, "map") == 0) { if (hbaline->auth_method != uaIdent && |