oauth_validator_libraries

oauth_validator_libraries is the PostgreSQL setting that lists libraries that may be called to validate OAuth v2 bearer tokens.

Note

Fact — official short description: “Lists libraries that may be called to validate OAuth v2 bearer tokens.”

Identity

Type , Valuestring: Upstream pg_settings type
Context , Valuesighup: Takes effect after configuration reload
Unit , Value—: Raw unit
Range , Value—: Raw limits in the last observed version
Enum values , Value—: — for non-enum types
Category , ValueConnections and Authentication / Authentication: Upstream classification
Latest boot value , Value"": empty string

Lifecycle

Fact	Value
First observed	PG18
Present in	PG18–19 Beta 3
Removed in	No
Introduction commit	`b3f0be788afc` — Add support for OAUTHBEARER SASL mechanism
Commit date	2025-02-20
Discussion	thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions	Raw `boot_val`	Unit	Human value
PG18–19 Beta 3	`""`	—	empty string

How it works

oauth_validator_libraries lists trusted server modules that can validate OAuth 2.0 bearer tokens. PostgreSQL 18 ships no validator implementation, and the empty default refuses all OAuth connections; a usable deployment must install and name at least one compatible module.

With exactly one listed library, PostgreSQL uses it by default for OAuth connections. With multiple libraries, every oauth record in pg_hba.conf must name a validator selected from this list. The setting has SIGHUP context, so changing the allow-list requires a configuration reload and affects subsequent authentication attempts.

A validator executes trusted native code inside the server authentication path. Its token issuer, audience, claim-to-role mapping, failure behavior, dependencies, package version, and availability on every primary/failover node must agree with pg_hba.conf and the identity provider.

Tuning advice

Tip

Advice. These are workload-specific starting points and must be validated with measurements.

Workload	Guidance
OLTP	Install one reviewed validator first, pin its package/version on every failover target, and test issuer, audience, expiry, revocation, role mapping, malformed tokens, and identity-provider outage before enabling an oauth HBA rule.
OLAP	Use the same validator trust policy for analytical access. If a different issuer or claim mapping is required, list the reviewed modules explicitly and select the intended validator in every matching HBA record.
Small nodes	The empty value securely disables OAuth but is not a working OAuth configuration. On a small node, prefer one well-tested validator and budget its token-validation latency instead of weakening checks.

Pigsty

Values use the fixed 8-vCPU, 32-GiB, 100-GiB SSD fixture and render the current Pigsty templates for PG19 Beta 3; this does not assert current Pigsty support for that historical or beta release.

Template	Effective value	Versus upstream boot	Source expression
OLTP	Unmodified	—	—
OLAP	Unmodified	—	—
CRIT	Unmodified	—	—
TINY	Unmodified	—	—

Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG18–19 Beta 3 unmodified; OLAP: PG18–19 Beta 3 unmodified; CRIT: PG18–19 Beta 3 unmodified; TINY: PG18–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

Creating an oauth HBA rule while the list is empty; PostgreSQL will refuse every OAuth connection.
Expecting PostgreSQL to provide a built-in validator implementation.
Listing multiple libraries without selecting a validator in every oauth HBA record.
Installing a validator on the primary but not on a failover target, or trusting native code whose issuer, audience, and role mapping were not reviewed.

password_encryption · scram_iterations · md5_password_warnings · authentication_timeout · krb_server_keyfile