skip to content

In PostgreSQL, how do peer and cert authentication identify a user without a password, and when do you need a pg_ident.conf map?

level: middleimportance: should knowfreq 35%

answer

  1. the kernel names the OS user
  2. certificate CN versus role name
  3. map= in the options column
  4. a permission, not an equivalence

basics

~20 s

peer asks the kernel for the OS user on a Unix-socket connection; cert takes the client certificate's CN over TLS. Each must equal the requested role unless a pg_ident.conf map, named with map=, allows the pair.

solid answer

~50 s

`peer` works only on `local` (Unix-socket) records. PostgreSQL asks the kernel (`getpeereid()`, `SO_PEERCRED` or similar) for the connecting process's operating-system user and compares it with the requested role. `cert` works only on `hostssl` records: the client must present a certificate signed by a CA in the server's `ssl_ca_file`, and its CN (or the full DN with `clientname=DN`) is compared with the role. No password is asked in either case. When the external name differs from the role, add `map=<name>` to the record and define the map in `pg_ident.conf` as `map-name system-username database-username` lines. Each line is a **permission** (this external name may connect as this role), not an equivalence. One OS user can map to several roles, a regular expression with `\1` can strip a domain, and the roles must already exist. The `clientcert=verify-full` option adds the same certificate check to any other method on a `hostssl` record.

code

console · 4 lines
console
$ cat "$PGDATA/pg_ident.conf"
# MAPNAME   SYSTEM-USERNAME           PG-USERNAME
localops    pgbackup                  clinic_backup
certmap     reports.clinic.internal   clinic_reports

go deeper

for a junior

Remember that peer is for local socket logins and compares the OS user with the role, and that cert reads the client certificate's CN.

for a middle

Explain how map= links a pg_hba.conf record to pg_ident.conf lines, why each line is a permission, and what cert needs from ssl_ca_file.

for a senior

Place these methods in a hardened setup (peer for local maintenance jobs, cert or clientcert=verify-full for services) and diagnose a usermap failure from the server log.

for a principal

Weigh certificate-based service identity against passwords at fleet scale: issuance, rotation, revocation lists, and who owns the CA the database trusts.

## Authentication without a password Several PostgreSQL methods take the user's identity from something other than a password: the operating system, a certificate, or a Kerberos ticket. All of them produce an **external user name**, compare it with the role the client asked for, and accept the login only if the two match or a **user-name map** allows the pair. This answer covers `peer`, `ident` and `cert`, plus the `pg_ident.conf` maps they share. ## peer: the kernel vouches for the OS user - `peer` is available only on `local` records, meaning Unix-domain socket connections. - The server asks the kernel which OS user owns the other end of the socket. This works on systems that provide `getpeereid()`, the `SO_PEERCRED` socket option or something similar: Linux, most BSDs including macOS, and Solaris. - Without a map, the OS user name must equal the requested role, which is why `sudo -u postgres psql` works out of the box on many installations. - `ident` is the TCP cousin. It asks an RFC 1413 ident server on the **client** machine who owns the connection, so it is only as trustworthy as that machine. On a `local` record, `ident` is treated as `peer`. ## cert: the certificate vouches for the user - `cert` is available only on `hostssl` records, because the identity comes from the TLS handshake. - The server needs `ssl = on`, its own certificate and key (`ssl_cert_file`, `ssl_key_file`), and `ssl_ca_file`. With `ssl_ca_file` left at its default (empty), no CA is loaded and client certificates are not verified at all. `ssl_crl_file` can list revoked certificates. - By default the certificate's **CN** is compared with the role name. `clientname=DN` compares the full distinguished name in RFC 2253 form instead, which is best combined with a map. - No password prompt is sent. The documentation describes `cert` as `trust` plus `clientcert=verify-full`. - To require both a certificate and a password, use a password method on a `hostssl` record and add `clientcert=verify-full` (CN must match) or `clientcert=verify-ca` (any trusted certificate). - Service certificates usually come from a private CA. Rotating that CA means updating `ssl_ca_file` on every server and reloading before the old CA expires, so plan the overlap. ## Comparing the password-less methods | Method | Connection | Where the identity comes from | Map option | |---|---|---|---| | `peer` | `local` only | kernel-reported OS user | `map=` | | `ident` | TCP | ident server on the client host | `map=` | | `cert` | `hostssl` only | client certificate CN or DN | `map=` | | `gss` | TCP | Kerberos principal | `map=`, `include_realm` | ## pg_ident.conf maps A record opts into mapping with `map=<name>`. The map itself lives in `pg_ident.conf` (location set by `ident_file`) as lines of `map-name system-username database-username`: 1. The **same map name** can appear on many lines, and an OS user may map to several roles or the other way round. 2. Each line means 'this external name may connect as this role'. The login succeeds if **any** line pairs the external name with the requested role. 3. A system user name starting with `/` is a regular expression, and one capture group can be reused as `\1` in the role column. Anchor these expressions with `^` and `$`. 4. `all` in the role column allows any existing role, and `+role` allows members of that role. 5. Maps never create roles and grant no privileges. They decide only who may **log in as** a role. The file is reloaded together with `pg_hba.conf`, and `pg_ident_file_mappings` shows how it was parsed. ## Clinic example and failure messages The nightly backup job runs as OS user `pgbackup` but should connect as role `clinic_backup`, and the reporting service presents a certificate whose CN is `reports.clinic.internal` but should become `clinic_reports`. The two maps are shown in the code examples. When a mapping fails, the client sees `Peer authentication failed for user ...` or `certificate authentication failed for user ...`. The server log explains why: either the provided and authenticated user names `do not match` (no map was used), or there is `no match in usermap` for the pair.

  • How do you require both a password and a client certificate for one role?
    Put the role on a `hostssl` record with `scram-sha-256` and add `clientcert=verify-full`. The client must present a certificate from a CA in `ssl_ca_file` whose CN matches the role (or a mapped name), and then complete SCRAM as well. Plain `cert` is the certificate check alone, equivalent to `trust` plus `clientcert=verify-full`.
  • A peer login fails with 'Peer authentication failed for user clinic_backup'. Where do you look?
    In the server log. Without a map, it reports that the provided user name and the authenticated user name do not match, meaning the OS user is not `clinic_backup`. With a map, it reports `no match in usermap` for that pair, meaning `pg_ident.conf` has no line pairing them. `pg_ident_file_mappings` shows whether the map loaded as intended.

  • peer authentication also works for TCP connections from localhost.
  • cert authentication still prompts for a password after the certificate check.
  • A pg_ident.conf line creates the database role it maps to.
  • A map line makes the OS user and the role equivalent identities.
  • ident over TCP is as trustworthy as peer on a Unix socket.