Open search page
Hello, I’m DocuDroid!
Open Ask AI page
Submitting feedback
Thank you for rating our AI Search!
We would be grateful if you could share your thoughts so we can improve our AI Search for you and other readers.
GitHub

Overview of pg_ident.conf

Andrey Aksenov

The pg_ident.conf file defines user name mappings for authentication methods that use external identities, including operating system user names, Kerberos principals, and SSL client certificates. These mappings are applied in conjunction with the authentication rules defined in the pg_hba.conf file.

On the master host, the pg_ident.conf file is located in the $MASTER_DATA_DIRECTORY directory.

NOTE

For more information about pg_ident.conf, see the corresponding topic in the PostgreSQL documentation: User Name Maps.

Supported authentication methods

The following authentication methods support user name mapping:

pg_ident.conf format overview

To use a user name mapping, you must configure both pg_hba.conf and pg_ident.conf. In pg_hba.conf, specify a mapping name using the map authentication option:

# pg_hba.conf
# connection-type  database  user  address  auth-method  auth-options
...                ...       ...   ...      ...          map=<map-name>

In pg_ident.conf, define the mapping using the same map name:

# pg_ident.conf
<map-name>    <system-username>    <database-username>
...

where:

  • map-name is an arbitrary identifier used to reference this mapping in pg_hba.conf.

  • system-username specifies the external user identity obtained from the authentication method (for example, a system user name, Kerberos principal, or SSL certificate CN).

  • database-username specifies the corresponding database user name.

The same map-name can be reused to define multiple user mappings within a single map.

There is no restriction on how many database users a given external identity can map to, or vice versa. Each entry in a map defines an explicit authorization: the specified external identity is permitted to authenticate as the corresponding database user. This does not imply identity or equivalence between the two accounts.

During connection, authentication succeeds if any map entry pairs the identity obtained from the external authentication method with the database user name requested by the client.

Configure user mapping

This section provides an example of configuring user name mapping for connections that use the ident authentication method.

Create a new operating system user

Create an operating system user before defining a mapping in pg_ident.conf:

  1. Log in to the master host as a user with sudo privileges.

  2. Create a new system user named dbadmin:

    $ sudo useradd dbadmin -r -m -s /bin/bash

Edit pg_hba.conf and pg_ident.conf

  1. Switch to the gpadmin user:

    $ sudo su - gpadmin

  2. Open pg_hba.conf for editing:

    $ vi $MASTER_DATA_DIRECTORY/pg_hba.conf

    Add the following line to enable user mapping via ident authentication:

    # connection-type  database  user     auth-method  auth-options
local              all       gpadmin  ident        map=admin_map

  3. Open pg_ident.conf for editing:

    $ vi $MASTER_DATA_DIRECTORY/pg_ident.conf

    Add the following mapping entries:

    # MAPNAME    SYSTEM-USERNAME    PG-USERNAME
admin_map    gpadmin            gpadmin
admin_map    dbadmin            gpadmin

    These entries allow both the gpadmin and dbadmin operating system users to connect as the gpadmin database role using admin_map.

  4. Reload the configuration to apply the changes:

    $ gpstop -u

Connect to a database

  1. Switch to the newly created dbadmin user:

    $ sudo su - dbadmin

  2. Set the Greengage DB path:

    $ source /usr/local/gpdb/greengage_path.sh

    The exact path depends on how Greengage DB was installed.

  3. Attempt to connect without specifying a database user. By default, psql uses the current operating system user name:

    $ psql postgres

    The connection attempt fails because pg_hba.conf allows connections only for the gpadmin database user:

    FATAL:  no pg_hba.conf entry for host "[local]", user "dbadmin", database "postgres", SSL off

  4. Attempt to connect as gpadmin:

    $ psql postgres -U gpadmin

    The connection succeeds because the operating system user dbadmin is mapped to the gpadmin database user, which is allowed by pg_hba.conf:

    psql (9.4.26)
Type "help" for help.

postgres=#

Regular expressions

If the system-username field begins with a slash (/), the rest of the field is interpreted as a regular expression. For details on PostgreSQL’s regular expression syntax, see Regular Expression Details.

The regular expression may include a single capture group (a parenthesized subexpression), which can be referenced in the database-username field as \1. This allows multiple system usernames to be mapped in a single line, which is particularly useful for syntax substitutions.

The example pg_hba.conf below enables GSSAPI authentication for users in the gss_users group:

# connection-type  database  user        address  auth-method  auth-options
host               all       +gss_users  samenet  gss          include_realm=1 krb_realm=EXAMPLE.COM map=user_map

Setting include_realm=1 keeps the Kerberos realm in the authenticated user principal. To remove the realm from user names ending with @EXAMPLE.COM, update pg_ident.conf as follows:

# MAPNAME    SYSTEM-USERNAME             PG-USERNAME
user_map     /^(.*)@EXAMPLE\.COM$        \1

To allow any user whose system user name ends with @OTHERDOMAIN.ORG to connect as guest, add the following mapping:

# MAPNAME    SYSTEM-USERNAME             PG-USERNAME
user_map     /^(.*)@OTHERDOMAIN\.ORG$    guest
TIP

By default, a regular expression can match any substring of the input. To ensure that the entire system user name is matched, use the ^ and $ anchors, as shown in the example above.

Previous
pg_hba.conf
Next
Password