begriffs open source - ai-pg/blob - full-docs/html/auth-username-maps.html

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