# 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 {#identity}

| Field | Value | Meaning |
| --- | --- | --- |
| Type | `string` | Upstream pg_settings type |
| Context | `sighup` | Takes effect after configuration reload |
| Unit | — | Raw unit |
| Range | — | Raw limits in the last observed version |
| Enum values | — | — for non-enum types |
| Category | Connections and Authentication / Authentication | Upstream classification |
| Latest boot value | `""` | empty string |
{.fields meta="-"}

## Lifecycle {#lifecycle}

| Fact | Value |
| --- | --- |
| First observed | PG18 |
| Present in | PG18–19 Beta 3 |
| Removed in | No |
| Introduction commit | [`b3f0be788afc`](https://git.postgresql.org/gitweb/?p=postgresql.git;a=commit;h=b3f0be788afc17d2206e1ae1c731d8aeda1f2f59) — Add support for OAUTHBEARER SASL mechanism |
| Commit date | 2025-02-20 |
| Discussion | [thread 1](https://postgr.es/m/d1b467a78e0e36ed85a09adf979d04cf124a9d4b.camel@vmware.com) |

## Default history {#default-history}

| Versions | Raw `boot_val` | Unit | Human value |
| --- | --- | --- | --- |
| PG18–19 Beta 3 | `""` | — | empty string |
{.full-width caption="Measured PG9.0–19 Beta 3 boot defaults"}

## How it works {#mechanism}

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 {#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. |
{.full-width}

## Pigsty {#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 | — | — |
{.full-width}

> [!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 {#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.

## Related parameters {#related-parameters}

[`password_encryption`](/parameters/password-encryption/) · [`scram_iterations`](/parameters/scram-iterations/) · [`md5_password_warnings`](/parameters/md5-password-warnings/) · [`authentication_timeout`](/parameters/authentication-timeout/) · [`krb_server_keyfile`](/parameters/krb-server-keyfile/)

## References {#references}

- [PostgreSQL 19 Beta 3 — oauth_validator_libraries](https://www.postgresql.org/docs/19/runtime-config-connection.html#GUC-OAUTH-VALIDATOR-LIBRARIES)
- [PostgreSQL 19 release notes](https://www.postgresql.org/docs/19/release-19.html)
- [Machine-readable GUC export](/data/guc.jsonl)