369
368
Obtain the operating system user name of the client (for
370
369
TCP/IP connections by contacting the ident server on the
371
370
client, for local connections by getting it from the
372
operating system) and check if the user is allowed to
373
connect as the requested database user by consulting the map
374
specified after the <literal>ident</literal> key word.
371
operating system) and check if it matches the requested
375
373
See <xref linkend="auth-ident"> for details.
417
415
<term><replaceable>auth-options</replaceable></term>
420
This field contains zero or more name-value pairs with
421
extra options passed to this authentication method. Details
422
about which options are available for which authentication
418
After the <replaceable>auth-method</> field, there can be field(s) of
419
the form <replaceable>name</><literal>=</><replaceable>value</> that
420
specify options for the authentication method. Details about which
421
options are available for which authentication method appear below.
491
489
# The same using local loopback TCP/IP connections.
493
491
# TYPE DATABASE USER CIDR-ADDRESS METHOD
494
host all all 127.0.0.1/32 trust
492
host all all 127.0.0.1/32 trust
496
# The same as the last line but using a separate netmask column
494
# The same as the previous line, but using a separate netmask column
498
496
# TYPE DATABASE USER IP-ADDRESS IP-MASK METHOD
499
host all all 127.0.0.1 255.255.255.255 trust
497
host all all 127.0.0.1 255.255.255.255 trust
501
499
# Allow any user from any host with IP address 192.168.93.x to connect
502
500
# to database "postgres" as the same user name that ident reports for
503
501
# the connection (typically the Unix user name).
505
503
# TYPE DATABASE USER CIDR-ADDRESS METHOD
506
504
host postgres all 192.168.93.0/24 ident
508
# Allow a user from host 192.168.12.10 to connect to database
506
# Allow any user from host 192.168.12.10 to connect to database
509
507
# "postgres" if the user's password is correctly supplied.
511
509
# TYPE DATABASE USER CIDR-ADDRESS METHOD
512
510
host postgres all 192.168.12.10/32 md5
514
512
# In the absence of preceding "host" lines, these two lines will
515
# reject all connection from 192.168.54.1 (since that entry will be
513
# reject all connections from 192.168.54.1 (since that entry will be
516
514
# matched first), but allow Kerberos 5 connections from anywhere else
517
515
# on the Internet. The zero mask means that no bits of the host IP
518
516
# address are considered so it matches any host.
520
518
# TYPE DATABASE USER CIDR-ADDRESS METHOD
521
519
host all all 192.168.54.1/32 reject
522
520
host all all 0.0.0.0/0 krb5
562
560
When using an external authentication system like Ident or GSSAPI,
563
the name of the operating system user that initiated the connection may
564
not be the same as the database user he is requesting to connect as.
561
the name of the operating system user that initiated the connection
562
might not be the same as the database user he needs to connect as.
565
563
In this case, a user name map can be applied to map the operating system
566
username to a database user, using the <filename>pg_ident.conf</filename>
567
file. In order to use username mapping, specify
564
username to a database user. To use username mapping, specify
568
565
<literal>map</literal>=<replaceable>map-name</replaceable>
569
566
in the options field in <filename>pg_hba.conf</filename>. This option is
570
567
supported for all authentication methods that receive external usernames.
571
Since the <filename>pg_ident.conf</filename> file can contain multiple maps,
568
Since different mappings might be needed for different connections,
572
569
the name of the map to be used is specified in the
573
570
<replaceable>map-name</replaceable> parameter in <filename>pg_hba.conf</filename>
574
571
to indicate which map to use for each individual connection.
578
Ident maps are defined in the ident map file, which by default is named
575
Username maps are defined in the ident map file, which by default is named
579
576
<filename>pg_ident.conf</><indexterm><primary>pg_ident.conf</primary></indexterm>
580
577
and is stored in the
581
578
cluster's data directory. (It is possible to place the map file
589
586
<filename>pg_hba.conf</>. The
590
587
<replaceable>map-name</> is an arbitrary name that will be used to
591
588
refer to this mapping in <filename>pg_hba.conf</filename>. The other
592
two fields specify which operating system user is allowed to connect
593
as which database user. The same <replaceable>map-name</> can be
594
used repeatedly to specify more user-mappings within a single map.
589
two fields specify an operating system user name and a matching
590
database user name. The same <replaceable>map-name</> can be
591
used repeatedly to specify multiple user-mappings within a single map.
595
594
There is no restriction regarding how many database users a given
596
operating system user can correspond to, nor vice versa.
595
operating system user can correspond to, nor vice versa. Thus, entries
596
in a map should be thought of as meaning <quote>this operating system
597
user is allowed to connect as this database user</quote>, rather than
598
implying that they are equivalent. The connection will be allowed if
599
there is any map entry that matches the user name obtained from the
600
external authentication system to the database user name that the
601
user has requested to connect as.
599
604
If the <replaceable>system-username</> field starts with a slash (<literal>/</>),
600
the contents of the field is treated as a regular expression. This regular
601
expression supports a single capture, which can be back-referenced as
602
<literal>\1</> (backslash-one). This allows the mapping of different syntax
603
names with a single line.
605
mymap /(.*)@mydomain.com \1
606
mymap /(.*)@otherdomain.com guest
608
will "remove" the domain part for users with system usernames @mydomain.com, and
609
allow all users from @otherdomain.com to log in as guest.
605
the remainder of the field is treated as a regular expression.
606
(See <xref linkend="posix-syntax-details"> for details of
607
<productname>PostgreSQL</>'s regular expression syntax.
608
Regular expressions in username maps are always treated as being
609
<quote>advanced</> flavor.) The regular
610
expression can include a single capture, or parenthesized subexpression,
611
which can then be referenced in the <replaceable>database-username</>
612
field as <literal>\1</> (backslash-one). This allows the mapping of
613
multiple usernames in a single line, which is particularly useful for
614
simple syntax substitutions. For example, these entries
616
mymap /^(.*)@mydomain\.com$ \1
617
mymap /^(.*)@otherdomain\.com$ guest
619
will remove the domain part for users with system usernames that end with
620
<literal>@mydomain.com</>, and allow any user whose system name ends with
621
<literal>@otherdomain.com</> to log in as <literal>guest</>.
626
Keep in mind that by default, a regular expression can match just part of
627
a string. It's usually wise to use <literal>^</> and <literal>$</>, as
628
shown in the above example, to force the match to be to the entire
613
634
The <filename>pg_ident.conf</filename> file is read on start-up and
614
635
when the main server process receives a
663
684
When <literal>trust</> authentication is specified,
664
685
<productname>PostgreSQL</productname> assumes that anyone who can
665
686
connect to the server is authorized to access the database with
666
whatever database user name they specify (including superusers).
687
whatever database user name they specify (even superuser names).
667
688
Of course, restrictions made in the <literal>database</> and
668
689
<literal>user</> columns still apply.
669
690
This method should only be used when there is adequate
689
710
Setting file-system permissions only helps for Unix-socket connections.
690
Local TCP/IP connections are not restricted by it; therefore, if you want
691
to use file-system permissions for local security, remove the <literal>host ...
692
127.0.0.1 ...</> line from <filename>pg_hba.conf</>, or change it to a
711
Local TCP/IP connections are not restricted by file-system permissions.
712
Therefore, if you want to use file-system permissions for local security,
713
remove the <literal>host ... 127.0.0.1 ...</> line from
714
<filename>pg_hba.conf</>, or change it to a
693
715
non-<literal>trust</> authentication method.
725
747
If you are at all concerned about password
726
748
<quote>sniffing</> attacks then <literal>md5</> is preferred.
727
749
Plain <literal>password</> should always be avoided if possible.
728
<literal>md5</> cannot be used with <xref
729
linkend="guc-db-user-namespace">.
750
However, <literal>md5</> cannot be used with the <xref
751
linkend="guc-db-user-namespace"> feature. If the connection is
752
protected by SSL encryption then <literal>password</> can be used
753
safely (though SSL certificate authentication might be a better
754
choice if one is depending on using SSL).
754
779
<productname>GSSAPI</productname> is an industry-standard protocol
755
for secure authentication defined in RFC 2743.
780
for secure authentication defined in RFC 2743.
756
781
<productname>PostgreSQL</productname> supports
757
782
<productname>GSSAPI</productname> with <productname>Kerberos</productname>
758
783
authentication according to RFC 1964. <productname>GSSAPI</productname>
759
784
provides automatic authentication (single sign-on) for systems
760
785
that support it. The authentication itself is secure, but the
761
data sent over the connection will be in clear unless
786
data sent over the database connection will be in clear unless
762
787
<acronym>SSL</acronym> is used.
766
791
When <productname>GSSAPI</productname> uses
767
792
<productname>Kerberos</productname>, it uses a standard principal
769
794
<literal><replaceable>servicename</>/<replaceable>hostname</>@<replaceable>realm</></literal>. For information about the parts of the principal, and
770
795
how to set up the required keys, see <xref linkend="kerberos-auth">.
771
796
GSSAPI support has to be enabled when <productname>PostgreSQL</> is built;
789
<term>include_realm</term>
814
<term><literal>include_realm</literal></term>
792
Include the realm name from the authenticated user principal. This is useful
793
in combination with Username maps (See <xref linkend="auth-username-maps">
794
for details), especially with regular expressions, to map users from
817
If set to <literal>1</>, the realm name from the authenticated user
818
principal is included in the system user name that's passed through
819
username mapping (<xref linkend="auth-username-maps">). This is
820
useful for handling users from multiple realms.
801
<term>krb_realm</term>
826
<term><literal>krb_realm</literal></term>
804
829
Sets the realm to match user principal names against. If this parameter
805
is not set, the realm of the user will be ignored.
830
is set, only users of that realm will be accepted. If it is not set,
831
users of any realm can connect, subject to whatever username mapping
852
<term>include_realm</term>
879
<term><literal>include_realm</literal></term>
855
Include the realm name from the authenticated user principal. This is useful
856
in combination with Username maps (See <xref linkend="auth-username-maps">
857
for details), especially with regular expressions, to map users from
882
If set to <literal>1</>, the realm name from the authenticated user
883
principal is included in the system user name that's passed through
884
username mapping (<xref linkend="auth-username-maps">). This is
885
useful for handling users from multiple realms.
864
<term>krb_realm</term>
891
<term><literal>krb_realm</literal></term>
867
894
Sets the realm to match user principal names against. If this parameter
868
is not set, the realm of the user will be ignored.
895
is set, only users of that realm will be accepted. If it is not set,
896
users of any realm can connect, subject to whatever username mapping
894
923
authentication system suitable for distributed computing over a public
895
924
network. A description of the <productname>Kerberos</productname> system
896
925
is far beyond the scope of this document; in full generality it can be
897
quite complex (yet powerful). The
926
quite complex (yet powerful). The
898
927
<ulink url="http://www.nrl.navy.mil/CCS/people/kenh/kerberos-faq.html">
899
Kerberos <acronym>FAQ</></ulink> or
928
Kerberos <acronym>FAQ</></ulink> or
900
929
<ulink url="http://web.mit.edu/kerberos/www/">MIT Kerberos page</ulink>
901
930
can be good starting points for exploration.
902
931
Several sources for <productname>Kerberos</> distributions exist.
923
952
client side using the <literal>krbsrvname</> connection parameter. (See
924
953
also <xref linkend="libpq-connect">.) The installation default can be
925
954
changed from the default <literal>postgres</literal> at build time using
926
<literal>./configure --with-krb-srvnam=whatever</>. In most environments,
955
<literal>./configure --with-krb-srvnam=</><replaceable>whatever</>.
956
In most environments,
927
957
this parameter never needs to be changed. However, to support multiple
928
958
<productname>PostgreSQL</> installations on the same host it is necessary.
929
959
Some Kerberos implementations might also require a different service name,
941
971
Client principals must have their <productname>PostgreSQL</> database user
942
972
name as their first component, for example
943
<literal>pgusername@realm</>. By default, the realm of the client is
973
<literal>pgusername@realm</>. Alternatively, you can use a username
974
mapping to map from the first component of the principal name to the
975
database user name. By default, the realm of the client is
944
976
not checked by <productname>PostgreSQL</>. If you have cross-realm
945
977
authentication enabled and need to verify the realm, use the
946
krb_realm parameter in <filename>pg_hba.conf</>.
978
<literal>krb_realm</> parameter, or enable <literal>include_realm</>
979
and use username mapping to check the realm.
1000
1034
</varlistentry>
1003
<term>include_realm</term>
1037
<term><literal>include_realm</literal></term>
1006
Include the realm name from the authenticated user principal. This is useful
1007
in combination with Username maps (See <xref linkend="auth-username-maps">
1008
for details), especially with regular expressions, to map users from
1040
If set to <literal>1</>, the realm name from the authenticated user
1041
principal is included in the system user name that's passed through
1042
username mapping (<xref linkend="auth-username-maps">). This is
1043
useful for handling users from multiple realms.
1012
1046
</varlistentry>
1015
<term>krb_realm</term>
1049
<term><literal>krb_realm</literal></term>
1018
1052
Sets the realm to match user principal names against. If this parameter
1019
is not set, the realm of the user will be ignored.
1053
is set, only users of that realm will be accepted. If it is not set,
1054
users of any realm can connect, subject to whatever username mapping
1022
1058
</varlistentry>
1025
<term>krb_server_hostname</term>
1061
<term><literal>krb_server_hostname</literal></term>
1028
1064
Sets the host name part of the service principal.
1048
1084
The ident authentication method works by obtaining the client's
1049
operating system user name, then optionally determining the allowed
1050
database user names using a map file that lists the permitted
1051
corresponding pairs of names. The determination of the client's
1085
operating system user name and using it as the allowed database user
1086
name (with an optional username mapping).
1087
The determination of the client's
1052
1088
user name is the security-critical point, and it works differently
1053
1089
depending on the connection type.
1122
1158
On systems supporting <symbol>SO_PEERCRED</symbol> requests for
1123
1159
Unix-domain sockets (currently <systemitem
1124
1160
class="osname">Linux</>, <systemitem class="osname">FreeBSD</>,
1125
<systemitem class="osname">NetBSD</>, <systemitem class="osname">OpenBSD</>,
1126
<systemitem class="osname">BSD/OS</>, and <systemitem class="osname">Solaris</systemitem>), ident authentication can also
1161
<systemitem class="osname">NetBSD</>, <systemitem class="osname">OpenBSD</>,
1162
<systemitem class="osname">BSD/OS</>, and <systemitem class="osname">Solaris</systemitem>), ident authentication can also
1127
1163
be applied to local connections. In this case, no security risk is added by
1128
1164
using ident authentication; indeed it is a preferable choice for
1129
1165
local connections on such systems.
1162
1198
The server will bind to the distinguished name constructed as
1163
1199
<replaceable>prefix</> <replaceable>username</> <replaceable>suffix</>.
1164
before the bind. Typically, the prefix parameter is used to specify
1165
<replaceable>cn=</>, or <replaceable>DOMAIN\</> in an Active
1166
Directory environment, and suffix is used to specify the remaining part
1167
of the DN in a non-Active Directory environment.
1200
Typically, the <replaceable>prefix</> parameter is used to specify
1201
<literal>cn=</>, or <replaceable>DOMAIN</><literal>\</> in an Active
1202
Directory environment. <replaceable>suffix</> is used to specify the
1203
remaining part of the DN in a non-Active Directory environment.
1171
1207
The following configuration options are supported for LDAP:
1174
<term>ldapserver</term>
1210
<term><literal>ldapserver</literal></term>
1177
1213
Name or IP of LDAP server to connect to.
1180
1216
</varlistentry>
1182
<term>ldapprefix</term>
1185
String to prepend to the username when building the base DN to
1191
<term>ldapsuffix</term>
1194
String to append to the username when building the base DN to
1200
<term>ldapport</term>
1218
<term><literal>ldapprefix</literal></term>
1221
String to prepend to the username when forming the DN to bind as.
1226
<term><literal>ldapsuffix</literal></term>
1229
String to append to the username when forming the DN to bind as.
1234
<term><literal>ldapport</literal></term>
1203
1237
Port number on LDAP server to connect to. If no port is specified,
1207
1241
</varlistentry>
1209
<term>ldaptls</term>
1243
<term><literal>ldaptls</literal></term>
1212
Set to 1 to make the connection between PostgreSQL and the
1246
Set to <literal>1</> to make the connection between PostgreSQL and the
1213
1247
LDAP server use TLS encryption. Note that this only encrypts
1214
the traffic to the LDAP server - the connection to the client
1215
may still be unencrypted unless TLS is used there as well.
1248
the traffic to the LDAP server — the connection to the client
1249
will still be unencrypted unless SSL is used.
1218
1252
</varlistentry>
1224
1258
Since LDAP often uses commas and spaces to separate the different
1225
parts of a DN, it is advised to always use double-quoted parameter
1226
values when configuring LDAP options, such as:
1259
parts of a DN, it is often necessary to use double-quoted parameter
1260
values when configuring LDAP options, for example:
1230
ldapserver=ldap.example.net prefix="cn=" suffix="dc=example, dc=net"
1264
ldapserver=ldap.example.net ldapprefix="cn=" ldapsuffix=", dc=example, dc=net"
1243
1277
This authentication method uses SSL client certificates to perform
1244
1278
authentication. It is therefore only available for SSL connections.
1245
1279
When using this authentication method, the server will require that
1246
the client provide a certificate. No password prompt will be sent
1280
the client provide a valid certificate. No password prompt will be sent
1247
1281
to the client. The <literal>cn</literal> attribute of the certificate
1248
will be compared to the login username, and if they match the
1249
login will be allowed. Username mapping can be used if the usernames
1282
will be compared to the requested database username, and if they match
1283
the login will be allowed. Username mapping can be used to allow
1284
<literal>cn</literal> to be different from the database username.
1288
The following configuration options are supported for SSL certificate
1292
<term><literal>map</literal></term>
1295
Allows for mapping between system and database usernames. See
1296
<xref linkend="auth-username-maps"> for details.
1265
1315
default PAM service name is <literal>postgresql</literal>.
1266
1316
PAM is used only to validate user name/password pairs.
1267
1317
Therefore the user must already exist in the database before PAM
1268
can be used for authentication. For more information about
1318
can be used for authentication. For more information about
1269
1319
PAM, please read the <ulink url="http://www.kernel.org/pub/linux/libs/pam/">
1270
1320
<productname>Linux-PAM</> Page</ulink>
1271
1321
and the <ulink url="http://www.sun.com/software/solaris/pam/">
added
removed
doc/src/sgml/client-auth.sgml
