oauth_validator_libraries

Definition PG 18 manual

The library/libraries to use for validating OAuth connection tokens. If only one validator library is provided, it will be used by default for any OAuth connections; otherwise, all oauth HBA entries must explicitly set a validator chosen from this list. If set to an empty string (the default), OAuth connections will be refused. This parameter can only be set in the postgresql.conf file.

Validator modules must be implemented/obtained separately; PostgreSQL does not ship with any default implementations. For more information on implementing OAuth validators, see Chapter 50.

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.

Operational considerations

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.

Workload guidance

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.

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.

SMALL: 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.