Authentication methods and what each one proves · PostgreSQL

The METHOD column decides what the server will accept as evidence of identity. Reading it as “how secure is this” is less useful than reading it as “what exactly is being proved, and by whom”.

What each one proves

Method	Proves	Depends on
`trust`	Nothing. The claimed role is accepted	Network reachability alone
`reject`	Nothing; refuses unconditionally	—
`peer`	The OS account owning the client socket	Unix socket, local only
`scram-sha-256`	Knowledge of a password, without sending it	The stored verifier
`md5`	Knowledge of a password, weakly. Deprecated in 18	The stored hash
`cert`	Possession of a private key matching a trusted certificate	TLS, and a CA you trust
`ldap`	The directory accepted the credential	An external directory being up
`gss` / `sspi`	A Kerberos ticket	A KDC being up
`oauth`	A token a validator accepted. New in 18	An identity provider being up

Two columns matter equally. The middle one is the security question. The right-hand one is the availability question, and it is the one that produces incidents: an authentication method with an external dependency means your database is unreachable whenever that dependency is.

trust, and where it is legitimate

trust accepts the connection as whatever role it claims to be, with no evidence at all. Any client that can reach the port can connect as any role, including superusers.

It has exactly two legitimate uses.

A disposable local cluster, which is why the official container image ships it for loopback and the Unix socket, and why every lab in this course relies on it.

Single-user recovery, where the server is not accepting network connections at all and you are repairing something.

peer, and why it is local-only

peer asks the kernel which operating-system user owns the other end of the Unix socket, and requires that name to match the PostgreSQL role being requested. The evidence comes from the kernel, cannot be forged by the client, and needs no password.

It is the right default for the local line, and it is why the Debian packaging ships exactly that:

Read-only / Safethe pg_hba.conf a Debian-packaged cluster starts with— peer locally, scram-sha-256 over the network. Captured from a pg_createcluster run.

$ grep -vE '^#|^$' /etc/postgresql/18/reporting/pg_hba.conf

local   all             postgres                                peer
local   all             all                                     peer
host    all             all             127.0.0.1/32            scram-sha-256
host    all             all             ::1/128                 scram-sha-256
local   replication     all                                     peer
host    replication     all             127.0.0.1/32            scram-sha-256
host    replication     all             ::1/128                 scram-sha-256

peer cannot work over TCP, because there is no operating-system identity attached to a network connection. A host line with peer is a configuration error, and the server will tell you so.

The name-matching requirement is strict by default: OS user deploy can only connect as PostgreSQL role deploy. pg_ident.conf provides a mapping when that is too rigid:

# pg_ident.conf: MAPNAME  SYSTEM-USERNAME  PG-USERNAME
ops    deploy      app_migrator
ops    ansible     app_migrator

# pg_hba.conf
local   all   app_migrator   peer  map=ops

That says: the OS accounts deploy and ansible may connect as the PostgreSQL role app_migrator, and nobody else may.

The password methods

scram-sha-256 is the current standard and the default for password_encryption in every supported version. The next lesson covers how it works and why the distinction from md5 matters more than it looks.

password sends the password in clear over the connection. It is acceptable only inside TLS, and since scram-sha-256 works everywhere password does, there is essentially no remaining reason to choose it.

md5 is deprecated in PostgreSQL 18, which emits a warning when a password is stored with it and announces removal in a future release.

cert

cert requires a client certificate and treats a successful TLS client-certificate validation as the authentication. It implies hostssl, and the certificate’s Common Name must match the requested role unless a map says otherwise.

Its strength is that no password exists to leak, rotate or embed in a configuration file. Its cost is a certificate lifecycle: issuance, distribution, expiry monitoring and revocation, all of which become your problem. A client certificate that expires unnoticed is an outage, and it is exactly the failure the Secrets and PKI course is built around.

Every external authentication method is an availability dependency

ldap, gss and the new oauth method delegate the proof to another system. That is frequently the right architectural choice: central identity, central revocation, one place to disable a leaver.

It also means the database cannot authenticate anybody when that system is unreachable. A directory outage becomes a database outage, and the failure looks like a database problem to everyone reporting it.

Two mitigations are worth building in from the start. Keep a locally-authenticated break-glass role — a scram-sha-256 account whose credential lives in a vault and whose use is alerted on — so the database remains administrable when the directory is down. And monitor the authentication path itself rather than only the database, because a slow directory makes every connection slow before it makes any of them fail.

Where authentication sits in the connection sequence, and what that costs

Part I established the six stages of a connection. Authentication is stage five, after pg_hba.conf matching and before the backend is forked and initialised.

The ordering has a consequence measured in PostgreSQL 18’s granular connection log, which reports the components separately:

LOG:  connection ready: setup total=1.498 ms, fork=0.445 ms, authentication=0.127 ms

0.127 ms for trust on a local socket — the only authentication timing captured for this course. scram-sha-256 adds a round trip and key derivation on top of that; the cost is small but it was not measured here, so treat the shape rather than a number as the point. An external directory adds a network call to another system, which can be tens of milliseconds and is subject to that system’s latency and availability. That last one is the difference that matters operationally, and it is large enough that you will see it without instrumentation.

For a connection held for hours this is irrelevant. For an application opening a connection per request, an authentication method with a network round trip multiplies the per-request cost, and the database is blamed for latency that is being spent in the directory.

The authentication component in that log line is how you measure it rather than guess. If it is large, the method’s dependency is the cause, and a connection pooler removes the problem entirely by authenticating once per pooled connection rather than once per request.

Choosing

A serviceable default for a self-managed estate:

# Local administration, authenticated by the operating system
local   all   postgres                     peer
local   all   all                          peer

# Applications over the network, encrypted and password-authenticated
hostssl all   +app_roles   10.0.0.0/8      scram-sha-256

# Replication, from known standbys only
hostssl replication  replicator  10.0.1.0/24  scram-sha-256

# Everything else
host    all   all          all             reject

The final explicit reject is optional — the absence of a matching rule already refuses — but it makes the intent visible and produces the clearer of the two error messages from the previous lesson.

Production discipline

Read the method as “what is being proved”, not “how secure”. trust proves nothing; peer proves an OS account; scram-sha-256 proves knowledge of a password.
Use peer rather than trust on the local line, including on hosts you consider private.
Prefer hostssl over host for anything crossing a network, so a rule cannot match an unencrypted connection.
Treat every external method as an availability dependency and keep a locally-authenticated break-glass role.
Measure the authentication component in the connection log before blaming the database for connection latency.
Never use password. scram-sha-256 works everywhere it does and does not transmit the secret.

Cross-course references

Secrets, PKI & Certificate Management — Part V (X.509) and Part IX (Certificate lifecycle) cover the client-certificate lifecycle that cert authentication makes your responsibility.
Linux for Production Sysadmins — Part XXVII (Auth) covers PAM, SSSD and directory integration, which is the same dependency discussed here from the host side.
Observability for Production Sysadmins — Part XI (Blackbox) covers probing an authentication path end to end rather than probing only the port.