1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
|
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>21.2. User Name Maps</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="auth-pg-hba-conf.html" title="21.1. The pg_hba.conf File" /><link rel="next" href="auth-methods.html" title="21.3. Authentication Methods" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">21.2. User Name Maps</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="auth-pg-hba-conf.html" title="21.1. The pg_hba.conf File">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="client-authentication.html" title="Chapter 21. Client Authentication">Up</a></td><th width="60%" align="center">Chapter 21. Client Authentication</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 16.2 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="auth-methods.html" title="21.3. Authentication Methods">Next</a></td></tr></table><hr /></div><div class="sect1" id="AUTH-USERNAME-MAPS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">21.2. User Name Maps <a href="#AUTH-USERNAME-MAPS" class="id_link">#</a></h2></div></div></div><a id="id-1.6.8.9.2" class="indexterm"></a><p>
When using an external authentication system such as Ident or GSSAPI,
the name of the operating system user that initiated the connection
might not be the same as the database user (role) that is to be used.
In this case, a user name map can be applied to map the operating system
user name to a database user. To use user name mapping, specify
<code class="literal">map</code>=<em class="replaceable"><code>map-name</code></em>
in the options field in <code class="filename">pg_hba.conf</code>. This option is
supported for all authentication methods that receive external user names.
Since different mappings might be needed for different connections,
the name of the map to be used is specified in the
<em class="replaceable"><code>map-name</code></em> parameter in <code class="filename">pg_hba.conf</code>
to indicate which map to use for each individual connection.
</p><p>
User name maps are defined in the ident map file, which by default is named
<code class="filename">pg_ident.conf</code><a id="id-1.6.8.9.4.2" class="indexterm"></a>
and is stored in the
cluster's data directory. (It is possible to place the map file
elsewhere, however; see the <a class="xref" href="runtime-config-file-locations.html#GUC-IDENT-FILE">ident_file</a>
configuration parameter.)
The ident map file contains lines of the general forms:
</p><pre class="synopsis">
<em class="replaceable"><code>map-name</code></em> <em class="replaceable"><code>system-username</code></em> <em class="replaceable"><code>database-username</code></em>
<em class="replaceable"><code>include</code></em> <em class="replaceable"><code>file</code></em>
<em class="replaceable"><code>include_if_exists</code></em> <em class="replaceable"><code>file</code></em>
<em class="replaceable"><code>include_dir</code></em> <em class="replaceable"><code>directory</code></em>
</pre><p>
Comments, whitespace and line continuations are handled in the same way as in
<code class="filename">pg_hba.conf</code>. The
<em class="replaceable"><code>map-name</code></em> is an arbitrary name that will be used to
refer to this mapping in <code class="filename">pg_hba.conf</code>. The other
two fields specify an operating system user name and a matching
database user name. The same <em class="replaceable"><code>map-name</code></em> can be
used repeatedly to specify multiple user-mappings within a single map.
</p><p>
As for <code class="filename">pg_hba.conf</code>, the lines in this file can
be include directives, following the same rules.
</p><p>
There is no restriction regarding how many database users a given
operating system user can correspond to, nor vice versa. Thus, entries
in a map should be thought of as meaning <span class="quote">“<span class="quote">this operating system
user is allowed to connect as this database user</span>”</span>, rather than
implying that they are equivalent. The connection will be allowed if
there is any map entry that pairs the user name obtained from the
external authentication system with the database user name that the
user has requested to connect as. The value <code class="literal">all</code>
can be used as the <em class="replaceable"><code>database-username</code></em> to specify
that if the <em class="replaceable"><code>system-user</code></em> matches, then this user
is allowed to log in as any of the existing database users. Quoting
<code class="literal">all</code> makes the keyword lose its special meaning.
</p><p>
If the <em class="replaceable"><code>database-username</code></em> begins with a
<code class="literal">+</code> character, then the operating system user can login as
any user belonging to that role, similarly to how user names beginning with
<code class="literal">+</code> are treated in <code class="literal">pg_hba.conf</code>.
Thus, a <code class="literal">+</code> mark means <span class="quote">“<span class="quote">match any of the roles that
are directly or indirectly members of this role</span>”</span>, while a name
without a <code class="literal">+</code> mark matches only that specific role. Quoting
a username starting with a <code class="literal">+</code> makes the
<code class="literal">+</code> lose its special meaning.
</p><p>
If the <em class="replaceable"><code>system-username</code></em> field starts with a slash (<code class="literal">/</code>),
the remainder of the field is treated as a regular expression.
(See <a class="xref" href="functions-matching.html#POSIX-SYNTAX-DETAILS" title="9.7.3.1. Regular Expression Details">Section 9.7.3.1</a> for details of
<span class="productname">PostgreSQL</span>'s regular expression syntax.) The regular
expression can include a single capture, or parenthesized subexpression,
which can then be referenced in the <em class="replaceable"><code>database-username</code></em>
field as <code class="literal">\1</code> (backslash-one). This allows the mapping of
multiple user names in a single line, which is particularly useful for
simple syntax substitutions. For example, these entries
</p><pre class="programlisting">
mymap /^(.*)@mydomain\.com$ \1
mymap /^(.*)@otherdomain\.com$ guest
</pre><p>
will remove the domain part for users with system user names that end with
<code class="literal">@mydomain.com</code>, and allow any user whose system name ends with
<code class="literal">@otherdomain.com</code> to log in as <code class="literal">guest</code>.
Quoting a <em class="replaceable"><code>database-username</code></em> containing
<code class="literal">\1</code> <span class="emphasis"><em>does not</em></span> make
<code class="literal">\1</code> lose its special meaning.
</p><p>
If the <em class="replaceable"><code>database-username</code></em> field starts with
a slash (<code class="literal">/</code>), the remainder of the field is treated
as a regular expression (see <a class="xref" href="functions-matching.html#POSIX-SYNTAX-DETAILS" title="9.7.3.1. Regular Expression Details">Section 9.7.3.1</a>
for details of <span class="productname">PostgreSQL</span>'s regular
expression syntax). It is not possible to use <code class="literal">\1</code>
to use a capture from regular expression on
<em class="replaceable"><code>system-username</code></em> for a regular expression
on <em class="replaceable"><code>database-username</code></em>.
</p><div class="tip"><h3 class="title">Tip</h3><p>
Keep in mind that by default, a regular expression can match just part of
a string. It's usually wise to use <code class="literal">^</code> and <code class="literal">$</code>, as
shown in the above example, to force the match to be to the entire
system user name.
</p></div><p>
The <code class="filename">pg_ident.conf</code> file is read on start-up and
when the main server process receives a
<span class="systemitem">SIGHUP</span><a id="id-1.6.8.9.11.3" class="indexterm"></a>
signal. If you edit the file on an
active system, you will need to signal the postmaster
(using <code class="literal">pg_ctl reload</code>, calling the SQL function
<code class="function">pg_reload_conf()</code>, or using <code class="literal">kill
-HUP</code>) to make it re-read the file.
</p><p>
The system view
<a class="link" href="view-pg-ident-file-mappings.html" title="54.10. pg_ident_file_mappings"><code class="structname">pg_ident_file_mappings</code></a>
can be helpful for pre-testing changes to the
<code class="filename">pg_ident.conf</code> file, or for diagnosing problems if
loading of the file did not have the desired effects. Rows in the view with
non-null <code class="structfield">error</code> fields indicate problems in the
corresponding lines of the file.
</p><p>
A <code class="filename">pg_ident.conf</code> file that could be used in
conjunction with the <code class="filename">pg_hba.conf</code> file in <a class="xref" href="auth-pg-hba-conf.html#EXAMPLE-PG-HBA.CONF" title="Example 21.1. Example pg_hba.conf Entries">Example 21.1</a> is shown in <a class="xref" href="auth-username-maps.html#EXAMPLE-PG-IDENT.CONF" title="Example 21.2. An Example pg_ident.conf File">Example 21.2</a>. In this example, anyone
logged in to a machine on the 192.168 network that does not have the
operating system user name <code class="literal">bryanh</code>, <code class="literal">ann</code>, or
<code class="literal">robert</code> would not be granted access. Unix user
<code class="literal">robert</code> would only be allowed access when he tries to
connect as <span class="productname">PostgreSQL</span> user <code class="literal">bob</code>, not
as <code class="literal">robert</code> or anyone else. <code class="literal">ann</code> would
only be allowed to connect as <code class="literal">ann</code>. User
<code class="literal">bryanh</code> would be allowed to connect as either
<code class="literal">bryanh</code> or as <code class="literal">guest1</code>.
</p><div class="example" id="EXAMPLE-PG-IDENT.CONF"><p class="title"><strong>Example 21.2. An Example <code class="filename">pg_ident.conf</code> File</strong></p><div class="example-contents"><pre class="programlisting">
# MAPNAME SYSTEM-USERNAME PG-USERNAME
omicron bryanh bryanh
omicron ann ann
# bob has user name robert on these machines
omicron robert bob
# bryanh can also connect as guest1
omicron bryanh guest1
</pre></div></div><br class="example-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="auth-pg-hba-conf.html" title="21.1. The pg_hba.conf File">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="client-authentication.html" title="Chapter 21. Client Authentication">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="auth-methods.html" title="21.3. Authentication Methods">Next</a></td></tr><tr><td width="40%" align="left" valign="top">21.1. The <code class="filename">pg_hba.conf</code> File </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 16.2 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 21.3. Authentication Methods</td></tr></table></div></body></html>
|
