PostgreSQL OAuth Authentication: What Works in 18 and 19

Ghazi · July 31, 2026

PostgreSQL 18 adds OAuth bearer-token authentication to the server and libpq, but it does not provide an authorization server. A deployment still needs an OAuth provider, a server-side validator module, identity mapping, and compatible clients.

Treat PostgreSQL OAuth as an authentication integration, not a switch. Validate the issuer and scopes, load a trusted validator, map external identities to narrow database roles, test psql with a compatible libpq build, and keep password or certificate access available during rollout.

The pg_hba.conf rule names the OAuth contract

hostssl app_db all 10.0.0.0/8 oauth \
  issuer="https://login.example.com/tenant" \
  scope="postgres.connect" \
  validator=my_validator \
  map=oauth_users

This is a configuration shape, not a drop-in provider recipe. The validator library, issuer, discovery document, scopes, certificates, and identity mapping must agree exactly.

Separate the four moving parts

The authorization server issues bearer tokens. libpq or another driver acts as the OAuth client. PostgreSQL is the resource server. A validator module checks the token and provides the authenticated identity.

PostgreSQL does not become an OpenID Connect login application by itself. Provider-specific discovery, client registration, token claims, and user experience still need implementation and testing.

Match the issuer exactly

PostgreSQL sends the configured issuer and scope to the client. libpq requires the server issuer, discovery document issuer, and oauth_issuer client setting to match exactly, including case and formatting.

Use HTTPS, verify the discovery endpoint, and do not accept arbitrary issuers supplied by a connecting client. Issuer confusion can turn a token from the wrong tenant or provider into an authentication path.

Map identities to database roles deliberately

Without a map, the identity returned by the validator must match the requested PostgreSQL role. pg_ident.conf can map external identities to database roles when naming conventions differ.

Avoid mapping every authenticated identity to an owner or superuser role. OAuth proves an identity according to the validator; PostgreSQL privileges still decide what that role can do.

Example identity map

# pg_ident.conf
oauth_users  alice@example.com  app_reader
oauth_users  dba@example.com    app_operator

Use real provider identities and roles designed for the required duties. Reload configuration and test both allowed and denied mappings.

Client support is not automatic

psql can use OAuth when linked against a libpq build with OAuth client support. Other tools may use libpq, a different driver, or a custom connection stack. The PostgreSQL server cannot make an older client understand an OAuth challenge.

Check the application's documented driver and flow support before changing pg_hba.conf. PostgresGUI currently supports password and TLS connection workflows; do not assume OAuth support until the app explicitly exposes it.

PostgreSQL 19 continues the client API work

The PostgreSQL 19 draft adds a newer OAuth flow hook with issuer and error details. That matters to client and plugin developers, but PostgreSQL 19 is still beta and the final interface can change.

Roll out OAuth beside an existing method, monitor failed logins, document revocation behavior, and test what happens when the provider is unavailable. Authentication that depends on an external service needs an operational fallback plan.