OAuth2: actionable error when openid scope lacks OAUTH2_SERVER_METADATA_URL (pgadmin-org#10007)

When OAUTH2_SCOPE contains 'openid' but OAUTH2_SERVER_METADATA_URL is
not set, Authlib fails deep inside id_token verification with a cryptic
`Missing "jwks_uri" in metadata` error that names neither the config
knob nor the fix.

Add a pre-flight check at the entry of _authorize_access_token: if the
scope includes 'openid' and no (non-whitespace) metadata URL is set,
raise a RuntimeError with actionable guidance before any network
round-trip. server_metadata_url is the only way pgAdmin feeds JWKS to
Authlib, so this carries no regression risk for correctly-configured
providers. Clarify the OAUTH2_SERVER_METADATA_URL comment in config.py
and add regression coverage.

Author: asheshv

docs/en_US/release_notes_9_9.rst

@@ -35,6 +35,7 @@ Bug fixes
 *********
 
   | `Issue #9098 <https://github.com/pgadmin-org/pgadmin4/issues/9098>`_ -  Fixed an issue where the query tool displayed 'default' instead of 'null' for null text data in the data output.
+  | `Issue #9988 <https://github.com/pgadmin-org/pgadmin4/issues/9988>`_ -  Provide an actionable error when 'openid' is in OAUTH2_SCOPE but OAUTH2_SERVER_METADATA_URL is not set, instead of a cryptic Authlib failure.
   | `Issue #9125 <https://github.com/pgadmin-org/pgadmin4/issues/9125>`_ -  Fixed an issue where the pgAdmin configuration database wasn't being created on a fresh install when an external database was used for the configuration.
   | `Issue #9157 <https://github.com/pgadmin-org/pgadmin4/issues/9157>`_ -  Fixed an issue where shortcuts are not working as expected on multiple keyboard layouts.
   | `Issue #9158 <https://github.com/pgadmin-org/pgadmin4/issues/9158>`_ -  Fixed an issue where saving the newly changed preferences was not reflecting on the preferences tab.

web/config.py

@@ -822,7 +822,10 @@
         # URL is used for authentication,
         # Ex: https://github.com/login/oauth/authorize
         'OAUTH2_AUTHORIZATION_URL': None,
-        # server metadata url might optional for your provider
+        # OpenID Connect discovery URL for the provider. Required when
+        # OAUTH2_SCOPE contains 'openid' (so pgAdmin can fetch the JWKS
+        # to verify the id_token); optional otherwise.
+        # Example: https://<issuer>/.well-known/openid-configuration
         'OAUTH2_SERVER_METADATA_URL': None,
         # Oauth base url, ex: https://api.github.com/
         'OAUTH2_API_BASE_URL': None,

web/pgadmin/authenticate/oauth2.py

@@ -284,6 +284,33 @@ def _read_workload_identity_assertion(self, provider_name, provider):
         return token
 
     def _authorize_access_token(self, provider_name, provider, client):
+        # Pre-flight: if the provider's scope includes 'openid', the
+        # OAuth server will return an id_token that pgAdmin must
+        # verify. Verification requires JWKS, which Authlib fetches
+        # via the discovery document. Without OAUTH2_SERVER_METADATA_URL,
+        # verification fails deep inside Authlib with a cryptic
+        # `Missing "jwks_uri" in metadata` error. Catch the misconfig
+        # here with actionable guidance, before any network round-trip.
+        scope = provider.get('OAUTH2_SCOPE') or ''
+        scope_parts = scope.split() if isinstance(scope, str) else []
+        metadata_url = provider.get('OAUTH2_SERVER_METADATA_URL')
+        if isinstance(metadata_url, str):
+            metadata_url = metadata_url.strip()
+        if 'openid' in scope_parts and not metadata_url:
+            guidance = gettext(
+                "OAuth2 provider '%(name)s' is configured with 'openid' "
+                "in OAUTH2_SCOPE but OAUTH2_SERVER_METADATA_URL is not "
+                "set. pgAdmin needs the provider's OpenID Connect "
+                "discovery URL to verify the id_token. Either set "
+                "OAUTH2_SERVER_METADATA_URL to the discovery URL "
+                "(e.g. https://<issuer>/.well-known/openid-"
+                "configuration), or remove 'openid' from OAUTH2_SCOPE."
+            ) % {'name': provider_name}
+            current_app.logger.error(
+                "OAuth2 (%s): %s", provider_name, guidance
+            )
+            raise RuntimeError(guidance)
+
         client_auth_method = provider.get(
             'OAUTH2_CLIENT_AUTH_METHOD', 'client_secret'
         )

web/pgadmin/browser/tests/test_oauth2_with_mocking.py

@@ -138,6 +138,12 @@ class Oauth2LoginMockTestCase(BaseTestGenerator):
             profile={},
             id_token_claims=None,
         )),
+        ('OAuth2 openid Scope Without Metadata URL Fails Fast', dict(
+            oauth2_provider='oidc-no-metadata',
+            kind='openid_without_metadata_url',
+            profile={},
+            id_token_claims=None,
+        )),
     ]
 
     @classmethod
@@ -320,6 +326,8 @@ def runTest(self):
             self._test_session_state_after_redirect(self.oauth2_provider)
         elif self.kind == 'callback_missing_provider_state':
             self._test_oauth2_callback_missing_provider_state()
+        elif self.kind == 'openid_without_metadata_url':
+            self._test_openid_scope_without_metadata_url_fails_fast()
         else:
             self.fail(f'Unknown test kind: {self.kind}')
 
@@ -776,6 +784,72 @@ def _test_oauth2_callback_missing_provider_state(self):
         # an unhandled exception.
         self.assertLess(res.status_code, 500)
 
+    def _test_openid_scope_without_metadata_url_fails_fast(self):
+        """'openid' in OAUTH2_SCOPE without OAUTH2_SERVER_METADATA_URL must
+        fail fast with actionable guidance, before any network round-trip.
+
+        Also covers the whitespace-only metadata URL bypass and proves the
+        check does not false-positive when the metadata URL is set.
+        """
+        app_config.OAUTH2_CONFIG = [{
+            'OAUTH2_NAME': 'oidc-no-metadata',
+            'OAUTH2_DISPLAY_NAME': 'OIDC No Metadata',
+            'OAUTH2_CLIENT_ID': 'testclientid',
+            'OAUTH2_CLIENT_SECRET': 'testclientsec',
+            'OAUTH2_TOKEN_URL': 'https://idp.example/token',
+            'OAUTH2_AUTHORIZATION_URL': 'https://idp.example/auth',
+            'OAUTH2_API_BASE_URL': 'https://idp.example/',
+            'OAUTH2_SCOPE': 'openid email profile',
+            # OAUTH2_SERVER_METADATA_URL deliberately omitted.
+        }]
+
+        with patch('pgadmin.authenticate.oauth2.OAuth.register'):
+            from pgadmin.authenticate.oauth2 import OAuth2Authentication
+            auth = OAuth2Authentication()
+
+        provider_name = 'oidc-no-metadata'
+
+        # The client must never be touched — the pre-flight raises first.
+        client = MagicMock()
+
+        with self.app.test_request_context():
+            # (a) Metadata URL entirely absent -> RuntimeError.
+            provider = {
+                'OAUTH2_SCOPE': 'openid email profile',
+            }
+            with self.assertRaises(RuntimeError) as cm:
+                auth._authorize_access_token(provider_name, provider, client)
+            msg = str(cm.exception)
+            self.assertIn('OAUTH2_SERVER_METADATA_URL', msg)
+            self.assertIn(provider_name, msg)
+
+            # (b) Whitespace-only metadata URL must be treated as missing.
+            provider = {
+                'OAUTH2_SCOPE': 'openid email profile',
+                'OAUTH2_SERVER_METADATA_URL': '   ',
+            }
+            with self.assertRaises(RuntimeError):
+                auth._authorize_access_token(provider_name, provider, client)
+
+            client.authorize_access_token.assert_not_called()
+
+            # (c) No false-positive: metadata URL set -> pre-flight passes
+            # and the call proceeds to the (mocked) client.
+            provider = {
+                'OAUTH2_SCOPE': 'openid email profile',
+                'OAUTH2_SERVER_METADATA_URL':
+                    'https://idp.example/.well-known/openid-configuration',
+            }
+            auth._authorize_access_token(provider_name, provider, client)
+            client.authorize_access_token.assert_called_once()
+
+            # (d) No false-positive: 'openid' absent -> pre-flight skipped
+            # even without a metadata URL.
+            client.reset_mock()
+            provider = {'OAUTH2_SCOPE': 'email profile'}
+            auth._authorize_access_token(provider_name, provider, client)
+            client.authorize_access_token.assert_called_once()
+
     def tearDown(self):
         self.tester.logout()