pg.ddx.io  GitHub: pgjdbc/pgjdbc (issues + PRs as email threads)  
help / color / mirror / Atom feed
From: vlsi (@vlsi) <noreply+vlsi@github.com>
To: pgjdbc/pgjdbc <noreply+pgjdbc-pgjdbc@github.com>
Subject: Re: [pgjdbc/pgjdbc] PR #4251 (changes requested): OAuth implementation
Date: Wed, 23 Sep 2026 06:47:01 +0000
Message-ID: <gh-pgjdbc-pgjdbc-4251-r5287718997@github.com> (raw)
In-Reply-To: <gh-pgjdbc-pgjdbc-4251@github.com>
References: <gh-pgjdbc-pgjdbc-4251@github.com>

Thanks for the big update. The OAUTHBEARER message format matches RFC 7628, `requireAuth=oauth` behaves correctly end to end, and the loopback `OAuthHandshakeTest` is a good way to test the handshake without Keycloak. I ran the PR (head 0b6a1442e) against PostgreSQL 18.6 with a dummy validator, against a scripted fake backend, under 131 hand-made mutants, and with HikariCP 7.1 and Spring Boot 4.1. I compared behavior with libpq and pgbouncer at their current `master`. The results are below, and the line-specific ones are in inline comments.

I'm requesting changes. The main reasons: a parser bug in `readMechanisms`, a backward-incompatible change to `BaseDataSource.getUrl()`, HikariCP's `dataSource.oauthToken` failing at pool start, a public SPI that can't grow, and RFC citations that don't say what the messages claim.

## Bugs

1. `readMechanisms` keeps reading after the terminator of the mechanism list. `\0OAUTHBEARER\0\0` is parsed as `["", "OAUTHBEARER"]` and the token is sent. `A\0\0B\0\0` becomes `[A, "", B]`. libpq stops at the first empty name (`fe-auth.c`, `pg_SASL_init`). See the inline comment.
2. `oauthIssuer` blocks a connection that never uses it. `resolveOAuthToken` validates the issuer before it looks at `oauthToken`, so `oauthToken=good-token&oauthIssuer=http://idp` fails with `OAuth issuer URL must use HTTPS` (22023), and a malformed URI fails with `OAuth issuer is not a valid URL`. The same issuer against a SCRAM server connects, because the check runs only on the OAuth path. The driver also never compares `oauthIssuer` with the issuer the server advertises: `oauthIssuer=https://other.example` connects to a server configured with `issuer=https://issuer.example`. `oauthAllowInsecureIssuer=true` skips the URI syntax check too.
3. HikariCP's JavaBean route fails. `dataSourceClassName=org.postgresql.ds.PGSimpleDataSource` with `dataSource.oauthToken=...` (or the same key in `hikari.properties`) fails at pool start with `Property oauthToken does not exist on target class org.postgresql.ds.PGSimpleDataSource`. HikariCP's `PropertyElf` looks for `setOauthToken`, and all eight new setters are spelled `setOAuth...`. Only `dataSource.OAuthToken` works, and nobody will guess that key. The API is not released yet, so please rename the setters and getters to `setOauthToken`, `getOauthToken`, and so on, rather than add aliases. That is what `java.beans.Introspector` derives from the property name `oauthToken`, and it matches [Google Java Style §5.3](https://google.github.io/styleguide/javaguide.html#s5.3-camel-case) and the rest of `BaseDataSource` (`setSslMode`, `setGssResponseTimeout`, `setTcpKeepAlive`). `PGPropertyTest.dataSourceProperties` misses it because it compares names with `CASE_INSENSITIVE_ORDER`.
4. The reason for a rejected token never reaches the caller. The server's RFC 7628 error result (`status`, `scope`, `openid-configuration`) goes only to a WARNING log. The exception says only `FATAL: OAuth bearer authentication failed for user "..."`. A Hikari pool that retries produced 6 of these WARNINGs in one second. The JSON is server-controlled and is logged verbatim, newlines included.

## Backward compatibility

- `BaseDataSource.getUrl()` and `getURL()` no longer include `sslpassword`. I reproduced the break with an encrypted client key: `copy.setURL(ds.getURL())` connects on master and fails on this PR with `Could not read password for SSL key file, console is not available.` The changelog mentions this at the end of a Security entry and does not mark it as breaking. `getReference()` and serialization still carry the token and `sslpassword`, so the change does not remove the secret from the DataSource either. I suggest masking the URLs that are logged and leaving `getUrl()` as it was.
- Commit 0b6a1442e changes `requireAuth` for connections that have nothing to do with OAuth. It fixes a defect present since `requireAuth` shipped in 42.7.11 (#3895): on a GSS-encrypted connection, `requireAuth=scram-sha-256` refused a connection that had authenticated with SCRAM. The fix matches libpq's `check_expected_areq`, and I agree with it, but it deserves its own PR so it can be released without OAuth. It also has no test at the call sites: moving `setFinishedAuthenticationRequests()` back into `enableGSSEncrypted`, or removing it from the JGSS branch, passes every test.
- The SASL rework changes SCRAM parsing: `ScramAuthenticator` no longer reads the mechanism list, the list is now bounded by the message length, and there are three new `08P01` errors. That is an improvement, but it is hidden inside the `feat:` commit, and the commit message doesn't mention it.

## Surprising behavior

- The transport check is stricter than libpq, which has no transport check for OAUTHBEARER at all (`fe-auth-oauth.c` on current master). With the default `sslmode=prefer`, and with `require`, every OAuth connection fails, including over TLS. That may be the right default for a bearer token, but the docs bury it. As written, `use.md` says `prefer` fails only when the server refuses TLS.
- The check trusts the value of `sslmode`, not what happened on the socket:
  - `sslmode=verify-full&sslfactory=org.postgresql.ssl.NonValidatingFactory` sends the token to an unverified server with no warning at all. The docs mention this, but the WARNING fires only for `oauthAllowInsecureConnection=true`.
  - The Cloud SQL and AlloyDB Java connectors require `sslmode=disable` and do TLS in their `socketFactory`. The check would refuse them with `sslmode=disable does not verify it`, which is wrong for that setup.
  - Over a Unix domain socket, OAuth works only with `oauthAllowInsecureConnection=true`, and then logs a WARNING on every connection.
- RFC 7628 §3 says only `TLS MUST be used for OAUTHBEARER to protect the bearer token`. It says nothing about verifying the certificate or about GSS. Certificate validation is RFC 6750 §5.3 ("Validate TLS certificate chains"). The citation is wrong in the two error messages, in `PGProperty`, in `use.md`, and in the changelog.
- When the server offers both SCRAM-SHA-256 and OAUTHBEARER, the driver picks OAUTHBEARER in either order. libpq picks the first of the two in server order (`fe-auth.c`). No PostgreSQL server offers both in one message, because the `pg_hba.conf` rule selects one method, and `oauth_get_mechanisms` advertises only OAUTHBEARER. `use.md` and the changelog nonetheless tell users that setting `oauthToken` makes `password` unusable unless they add `requireAuth=scram-sha-256`. Please drop that paragraph or describe the real rule: the `pg_hba.conf` entry decides.
- A `+` in a token passed through the JDBC URL is decoded to a space and then refused by the format check. The token has to be written as `%2B`.
- `PgConnection.getURL()` and `DatabaseMetaData.getURL()` return the URL with `oauthToken=...` in it, and HikariCP logs `oauthToken` and `oauthClientSecret` at DEBUG, because it masks only keys that contain "password". The driver can't fix HikariCP, but the docs should steer users towards the provider instead of a token in the URL.
- Pools:
  - The driver creates a new provider instance on every connection attempt. Please document that, and say that an implementation should be a lightweight bridge to a layer that caches the token, such as a cloud SDK credential or a token file, or keep its cache in a static field keyed by everything that affects the token.
  - A static `oauthToken` works until it expires. After that, the pool can't open any new connection and never recovers. Open sessions stay up, because the server checks the token only at connect.
  
  None of this is documented.
- Setting an IAM or Entra token as `oauthToken` against RDS, Aurora, Azure, or Cloud SQL fails with `The server requested password-based authentication, but no password was provided.`, because those services take the token as a password, not through OAUTHBEARER. None of the major managed services documents server-side OAUTHBEARER today. A hint in that error, when `oauthToken` or `oauthTokenProviderClassName` is set, would save users a support ticket. Please don't fall back to sending the token as a cleartext password.

## Public API

`OAuthTokenProvider` and `OAuthTokenRequest` become public API with this PR, so please settle them before merge:
- The public four-argument `OAuthTokenRequest` constructor fixes the field set. Adding a field later means another constructor, or a breaking change. A builder, or a package-private constructor, would keep it open.
- The request has no host, port, user, or database. The provider can read `PGHOST` from its `Properties` constructor, but with a multi-host URL that is the whole list, and it can't tell which host is being tried. Tokens from cloud identity providers are usually bound to exactly those values.
- Please rename the classes to `OauthTokenProvider` and `OauthTokenRequest` as well. The code is new, so it should follow the same camel-case rule as the setters.
- `oauthToken` is a convenience that neither libpq nor pgx has: libpq takes a process-global hook (`PQsetAuthDataHook`) or runs its built-in device flow, and pgx takes only a provider function. It works for a one-off connection, such as a desktop tool where the user pastes a token, and it breaks a pool once the token expires. The PR ships no provider implementation of its own. Have you considered a small built-in provider that rereads the token from a file on each connection instead? That is how Kubernetes projected service-account tokens and cloud workload-identity agents deliver rotated tokens, and it would serve both the paste-a-token case and pools without any cache.
- `oauthIssuer`, `oauthClientId`, `oauthClientSecret`, and `oauthScope` are pass-through properties the driver never reads, yet they become public connection properties, with validation on one of them. I asked about this earlier. If they stay, the driver should at least not reject a connection over an issuer it doesn't use (bug 2).
- `AuthenticationPlugin` is not connected to OAUTHBEARER, so a plugin such as Azure's `AzurePostgresqlAuthenticationPlugin` could not serve a bearer token. If you want that bridge, it has to be opt-in (a new `AuthenticationRequestType` value the plugin declares support for), because existing plugins ignore the request type and would return a password.

## Tests

The unit tests of the static helpers are solid: branch coverage of `selectSaslMechanism`, `validateOAuthIssuer`, `checkAuthenticationCompleted`, and `OAuthAuthenticator` is 100% from the DB-free tests. Mutation testing shows what the tests don't pin down: 131 mutants, 27 survived, of which about 17 are real gaps. The ones that matter for security:

- `oauthAllowInsecureConnection` forced to `true`, or its default changed to `"true"`, passes every test, because `OAuthHandshakeTest` always sets the flag (inline comment).
- Removing `Arrays.fill(clientMessage, (byte) 0)` passes every test. Only the `char[]` wipe is tested.
- Removing `setFinishedAuthenticationRequests()` after the OAuth initial response passes every DB-free test, yet it breaks `requireAuth=oauth` for every successful login. No test runs a successful OAUTHBEARER exchange with `requireAuth` set.
- `BaseDataSource.getConnectionProperties` has 0% coverage. Dropping every credential it passes (`setOAuthToken`, `setSslPassword`, `setOAuthClientSecret`) passes every test.
- The masking in `Driver` (`Unable to parse URL`, `Connecting with URL`, the two WARNINGs about a malformed URL) and in `BaseDataSource.setUrl` can be removed without a failing test. Only the FINE record for an undecodable parameter is pinned.

Other gaps: an empty `oauthToken=` counts as configured (it makes OAuth win over SCRAM and then fail), a `PSQLException` from the provider is passed through unwrapped but untested, a second AuthenticationSASL during SCRAM is not detected by any test, and a second AuthenticationSASLContinue after the OAuth error is not tested. `OAuthHandshakeTest.refusesSaslFinalAfterTheServerRejectedTheToken` also hit its 30-second timeout once under load.

Tests to rewrite are in inline comments: `SelectSaslMechanismTest` (act after assert, better as one parameterized decision table), `ReadMechanismsTest.stopsAtTheEndOfTheMessage` (verifies a stub that can't show the stream position), and `OAuthTest` (rejections asserted only by `CONNECTION_REJECTED`, which five other failures share). Every OAuth success path in CI runs with `oauthAllowInsecureConnection=true`, so the production configuration, `sslmode=verify-full`, is never tested end to end.

Coverage reporting: `pgjdbc-mockito-test` runs against the shaded `-all.jar`, so JaCoCo gives `ConnectionFactoryImpl` and `ScramAuthenticator` different class IDs there, and the root report drops that coverage. The Codecov diff coverage for this PR is understated because of that.

## Logging

- The two `oauthAllowInsecureConnection` WARNINGs fire on every connection. A pool of 50 prints 50 two-line blocks to stderr, because pgjdbc logs through `java.util.logging`, whose default console handler prints WARNING. Log once per JVM at WARNING and at FINE afterwards, include the host, and drop the RFC citation and "Do not use this configuration in production".
- Move the server's error result into the exception and log the JSON at FINEST, like the other `<=BE` trace lines (bug 4).
- `selectSaslMechanism` makes silent decisions. It prefers OAUTHBEARER, falls back to SCRAM under `channelBinding=require`, and falls back to SCRAM when the server doesn't offer OAUTHBEARER. A user who configured OAuth then sees only a SCRAM error. One FINE record naming the offered list, the choice, and the reason would help.
- A provider exception is chained as the cause and ends up in `Connection error:` at FINE. Please add a sentence to the `getToken` Javadoc saying the exception message must not contain the token or `clientSecret`.

## Documentation

- The OAuth introduction sits between `scramMaxIterations` and `oauthToken`, without a heading. Please move it to an `### OAuth authentication` section after the property list, as with `### Unix sockets`.
- The first thing a reader needs is missing: with the default `sslmode=prefer`, OAuth fails. Set `sslmode=verify-full`, or `verify-ca`, or use GSS encryption.
- No error text a user will search for appears on the page. Quote `OAUTHBEARER authentication requires ...`, `OAuth issuer URL must use HTTPS: {0}`, `The server requested OAuth authentication, but neither oauthToken nor oauthTokenProviderClassName is configured.`, `Invalid OAuth bearer token format...`, and the server's `OAuth bearer authentication failed for user "..."`.
- `oauthTokenProviderClassName` needs its contract on the page:
  - the class needs a `Properties` constructor or a no-argument constructor;
  - the driver creates a new instance for each attempt, including each host of a multi-host URL;
  - `getToken` runs only after the server asks for OAuth and the transport check passes;
  - the call counts against `loginTimeout` and the server's `authentication_timeout`;
  - it must return a new array every time.
- `oauthToken` needs its limits: the token expires, which breaks a pool (use a provider there), the `b64token` syntax, and the `%2B` for `+` in a URL.
- A short how-to with a URL example, a provider skeleton, and a pooled setup; "Since: 42.7.14" on every new entry and on the `oauth` value of `requireAuth`; and one sentence each in `sslmode`, `gssEncMode`, `sslfactory`, and `loginTimeout`, linking to the OAuth section.
- `TESTING.md` renumbers `## 11 - Credits and Feedback` to `## 12`, which changes its anchor. Placing the new section after it keeps the old number.
- The PR description no longer matches the code. It says "Two options were added" and "TLS or GSSAPI", while the code adds eight properties, a public SPI, and the verify-ca/verify-full requirement. It also doesn't mention the `getUrl()` change, the URL masking, or the `requireAuth` fix. The link text says RFC 7632 and links to RFC 7628, and `Solves #3816` does not close the issue (use `Fixes #3816`).

## Changelog

- The Added entry is about 330 words, and cites RFC 7628 §3 for certificate verification. Please cut it to what an upgrading user needs: the two token sources, `requireAuth=oauth`, the `sslmode` requirement with the error text, and the escape hatch.
- The Security entry says "`password` was never affected". That is not true for a `password` in the JDBC URL. On master, `Driver` logs the URL verbatim at WARNING when it has too many `/` or no `/` after the host, at FINE in `Connecting with URL: {0}`, and in the `Unable to parse URL {0}` exception. `oauthToken` and `oauthClientSecret` were never released, so listing them as fixed leaks overstates the entry. The `getUrl()` change needs a `**Breaking:**` marker, or better, no break at all.
- The Fixed entry for `requireAuth` should say the defect has been present since 42.7.11, and quote the new error text, which replaces `Authentication method is not allowed by requireAuth` for a trust server.

## Commit structure

The project merges by rebase, so each commit lands in `master` as it is. The seven commits are split by artifact type (feat, test, ci, docs, changelog), not by behavior:
- the feat commit has no docs or changelog, and they arrive four commits later;
- the changelog of `aa239e0f9` sits in a separate `docs:` commit;
- the two fixes of released code come last and depend on OAuth identifiers (`OAUTH_TOKEN`, `AuthMethod.OAUTH`), so neither can ship without the feature.

I suggest:

1. A separate PR for the `requireAuth` and GSS fix, based on `master`, with `CheckAuthenticationCompletedTest` minus the `OAUTH` row.
2. A separate PR for masking credentials in logged URLs and in the `Unable to parse URL` message, with `password` and `sslpassword` as the sensitive set, and without the `getUrl()` change.
3. This PR, rebased on both, as four commits:
   - `refactor(core): read the SASL mechanism list by the message's declared length`;
   - `feat(core): add OAUTHBEARER authentication for PostgreSQL 18`, with its unit tests, docs, changelog entry, and `Fixes #3816`;
   - `test: run OAuth integration tests against PostgreSQL 18 and Keycloak`, with the `smoke` CI axis;
   - `test: add a CI mode that authenticates the whole suite through OAUTHBEARER`, with the `all` axis and the `assumeNotOAuthMode` changes.

Each commit body should name the problem and carry `Caller sees:` lines for the new error texts.

I'm happy to help split the fixes out if you'd like.

view thread (168+ messages)  latest in thread

Message-ID: <gh-pgjdbc-pgjdbc-4251-r5287718997@github.com>
Permalink:  ../gh-pgjdbc-pgjdbc-4251-r5287718997@github.com/

 · 


This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox