Warn when OAuth2 provider settings are misplaced at the top level of the config

[dpage]

Summary

pgAdmin reads OAuth2 provider settings only from the OAUTH2_CONFIG list; each provider is a single dictionary entry within it. Settings supplied at the top level of the configuration (for example a bare OAUTH2_CLIENT_ID or OAUTH2_SSL_CERT_VERIFICATION) are silently ignored.

This is an easy trap in container deployments: nearly every other option is set with an individual PGADMIN_CONFIG_<KEY> environment variable, so it is natural to assume PGADMIN_CONFIG_OAUTH2_CLIENT_ID, PGADMIN_CONFIG_OAUTH2_SSL_CERT_VERIFICATION and friends will behave the same way. They do not: OAuth2 must be configured through a single PGADMIN_CONFIG_OAUTH2_CONFIG holding the whole provider list. The result is that a user's settings, including their attempt to disable SSL certificate verification for a self-signed provider, are dropped without any feedback.

This change:

• Adds warn_on_misplaced_oauth2_config(), called once at startup from the OAuth2 module's init_app, which logs an actionable warning when per-provider OAUTH2_* keys are present at the top level of the configuration and no provider is configured in OAUTH2_CONFIG. There is no behavioural change: a correctly configured deployment, or one with no OAuth2 settings at all, stays silent.
• Documents the supported container-deployment approach in oauth2.rst, making clear that individual PGADMIN_CONFIG_OAUTH2_* variables do not configure a provider.

This is deliberately a fail-loud fix rather than a compatibility shim: OAUTH2_CONFIG remains the single source of truth, and we avoid quietly expanding the supported configuration surface (and the reach of verify=False).

Note on the "regression" in the linked issue: the OAuth2 verify handling did not change in code between the affected releases. The actual trigger is stricter certificate verification (OpenSSL/urllib3) in the newer image rejecting a CA certificate whose Basic Constraints extension is not marked critical; the user's OAUTH2_SSL_CERT_VERIFICATION=False escape hatch never took effect because it was supplied as an individual environment variable. This change makes that misconfiguration visible.

Test plan

• New test test_oauth2_misplaced_config.py covering: warns on misplaced keys + unconfigured OAUTH2_CONFIG; quiet when a provider is configured; quiet for legitimate top-level settings only; quiet with no OAuth2 config.
• Existing test_oauth2_with_mocking still passes (58/58).
• pycodestyle clean on changed Python files.

Closes #10053

Summary by CodeRabbit

• Documentation

  • Expanded the OAuth2 setup guide to clarify that provider settings must be defined within the OAUTH2_CONFIG list; other top-level OAuth2 keys are ignored.
  • Added notes for container usage, including PGADMIN_CONFIG_OAUTH2_CONFIG, and described the startup warning behavior.

• New Features

  • Added startup-time validation that detects misplaced OAuth2 settings and logs a warning listing the ignored keys.

• Tests

  • Added automated coverage to verify warning conditions across multiple configuration scenarios.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: c9f89908-d1b9-447a-9b86-aa099b62d4e3

📥 Commits

Reviewing files that changed from the base of the PR and between 2609227 and f1a6684.

📒 Files selected for processing (1)

• web/pgadmin/browser/tests/test_oauth2_misplaced_config.py

🚧 Files skipped from review as they are similar to previous changes (1)

• web/pgadmin/browser/tests/test_oauth2_misplaced_config.py

---

📝 Walkthrough

Walkthrough

Adds warn_on_misplaced_oauth2_config(app) to oauth2.py, which detects top-level OAUTH2_* configuration keys that pgAdmin ignores (only OAUTH2_CONFIG list entries are read), logs a startup warning listing the ignored keys, and is invoked from init_app. Includes four-scenario unit tests and a documentation warning block.

Changes

OAuth2 misplaced config detection

Layer / File(s)	Summary
warn_on_misplaced_oauth2_config helper and init_app wiring web/pgadmin/authenticate/oauth2.py	Defines _TOP_LEVEL_OAUTH2_SETTINGS (the allowed top-level keys) and warn_on_misplaced_oauth2_config(app), which scans config for OAUTH2_* keys outside the allowed set. Suppresses the warning if OAUTH2_CONFIG has a configured provider; otherwise logs the ignored keys with guidance. Adds the call to this helper inside init_app.
Tests and documentation web/pgadmin/browser/tests/test_oauth2_misplaced_config.py, docs/en_US/oauth2.rst	Oauth2MisplacedConfigTestCase covers four scenarios via unittest.mock.patch on oauth2.config: misplaced keys with unconfigured provider (expects one warning containing specific keys), misplaced keys with a configured provider (no warning), only allowed top-level keys (no warning), and no OAuth2 config (no warning). The docs add a .. warning:: block explaining that only OAUTH2_CONFIG list entries are read, with container-specific PGADMIN_CONFIG_OAUTH2_CONFIG guidance.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐰 Top-level keys were lost and ignored,
But pgAdmin now warns what's been poured!
OAUTH2_CONFIG is the proper way,
No SSL cert failures today! 🔐

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 25.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: adding a warning when OAuth2 provider settings are misplaced at the top-level configuration.
Linked Issues check	✅ Passed	The PR implements a warning system for misplaced OAuth2 settings as described in issue #10053, addressing the root cause by making the misconfiguration visible to users.
Out of Scope Changes check	✅ Passed	All changes are scoped to documenting and detecting OAuth2 misconfiguration; no unrelated modifications are present.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}