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

   1
   2 20.2. User Name Maps #
   3
   4    When using an external authentication system such as Ident or GSSAPI,
   5    the name of the operating system user that initiated the connection
   6    might not be the same as the database user (role) that is to be used.
   7    In this case, a user name map can be applied to map the operating
   8    system user name to a database user. To use user name mapping, specify
   9    map=map-name in the options field in pg_hba.conf. This option is
  10    supported for all authentication methods that receive external user
  11    names. Since different mappings might be needed for different
  12    connections, the name of the map to be used is specified in the
  13    map-name parameter in pg_hba.conf to indicate which map to use for each
  14    individual connection.
  15
  16    User name maps are defined in the ident map file, which by default is
  17    named pg_ident.conf and is stored in the cluster's data directory. (It
  18    is possible to place the map file elsewhere, however; see the
  19    ident_file configuration parameter.) The ident map file contains lines
  20    of the general forms:
  21 map-name system-username database-username
  22 include file
  23 include_if_exists file
  24 include_dir directory
  25
  26    Comments, whitespace and line continuations are handled in the same way
  27    as in pg_hba.conf. The map-name is an arbitrary name that will be used
  28    to refer to this mapping in pg_hba.conf. The other two fields specify
  29    an operating system user name and a matching database user name. The
  30    same map-name can be used repeatedly to specify multiple user-mappings
  31    within a single map.
  32
  33    As for pg_hba.conf, the lines in this file can be include directives,
  34    following the same rules.
  35
  36    The pg_ident.conf file is read on start-up and when the main server
  37    process receives a SIGHUP signal. If you edit the file on an active
  38    system, you will need to signal the postmaster (using pg_ctl reload,
  39    calling the SQL function pg_reload_conf(), or using kill -HUP) to make
  40    it re-read the file.
  41
  42    The system view pg_ident_file_mappings can be helpful for pre-testing
  43    changes to the pg_ident.conf file, or for diagnosing problems if
  44    loading of the file did not have the desired effects. Rows in the view
  45    with non-null error fields indicate problems in the corresponding lines
  46    of the file.
  47
  48    There is no restriction regarding how many database users a given
  49    operating system user can correspond to, nor vice versa. Thus, entries
  50    in a map should be thought of as meaning “this operating system user is
  51    allowed to connect as this database user”, rather than implying that
  52    they are equivalent. The connection will be allowed if there is any map
  53    entry that pairs the user name obtained from the external
  54    authentication system with the database user name that the user has
  55    requested to connect as. The value all can be used as the
  56    database-username to specify that if the system-username matches, then
  57    this user is allowed to log in as any of the existing database users.
  58    Quoting all makes the keyword lose its special meaning.
  59
  60    If the database-username begins with a + character, then the operating
  61    system user can login as any user belonging to that role, similarly to
  62    how user names beginning with + are treated in pg_hba.conf. Thus, a +
  63    mark means “match any of the roles that are directly or indirectly
  64    members of this role”, while a name without a + mark matches only that
  65    specific role. Quoting a username starting with a + makes the + lose
  66    its special meaning.
  67
  68    If the system-username field starts with a slash (/), the remainder of
  69    the field is treated as a regular expression. (See Section 9.7.3.1 for
  70    details of PostgreSQL's regular expression syntax.) The regular
  71    expression can include a single capture, or parenthesized
  72    subexpression. The portion of the system user name that matched the
  73    capture can then be referenced in the database-username field as \1
  74    (backslash-one). This allows the mapping of multiple user names in a
  75    single line, which is particularly useful for simple syntax
  76    substitutions. For example, these entries
  77 mymap   /^(.*)@mydomain\.com$      \1
  78 mymap   /^(.*)@otherdomain\.com$   guest
  79
  80    will remove the domain part for users with system user names that end
  81    with @mydomain.com, and allow any user whose system name ends with
  82    @otherdomain.com to log in as guest. Quoting a database-username
  83    containing \1 does not make \1 lose its special meaning.
  84
  85    If the database-username field starts with a slash (/), the remainder
  86    of the field is treated as a regular expression. When the
  87    database-username field is a regular expression, it is not possible to
  88    use \1 within it to refer to a capture from the system-username field.
  89
  90 Tip
  91
  92    Keep in mind that by default, a regular expression can match just part
  93    of a string. It's usually wise to use ^ and $, as shown in the above
  94    example, to force the match to be to the entire system user name.
  95
  96    A pg_ident.conf file that could be used in conjunction with the
  97    pg_hba.conf file in Example 20.1 is shown in Example 20.2. In this
  98    example, anyone logged in to a machine on the 192.168 network that does
  99    not have the operating system user name bryanh, ann, or robert would
 100    not be granted access. Unix user robert would only be allowed access
 101    when he tries to connect as PostgreSQL user bob, not as robert or
 102    anyone else. ann would only be allowed to connect as ann. User bryanh
 103    would be allowed to connect as either bryanh or as guest1.
 104
 105    Example 20.2. An Example pg_ident.conf File
 106 # MAPNAME       SYSTEM-USERNAME         PG-USERNAME
 107
 108 omicron         bryanh                  bryanh
 109 omicron         ann                     ann
 110 # bob has user name robert on these machines
 111 omicron         robert                  bob
 112 # bryanh can also connect as guest1
 113 omicron         bryanh                  guest1