From 7583f997bb260a275e2538b5e3bf9bcf3127d53a Mon Sep 17 00:00:00 2001 From: splitsec2 <35583321+splitsec2@users.noreply.github.com> Date: Tue, 27 Oct 2026 11:06:51 -0600 Subject: [PATCH] fix(oidc): catch joserfc's InvalidClaimError so the issuer guidance shows (#1603) A wrong OIDC issuer, which is the usual IdP setup mistake, sends the user back to the login page with a bare "Authentication failed". The callback has a handler that explains it ("OIDC issuer validation failed. Verify your discovery URL and IdP issuer/external URL configuration."), and it never runs. Authlib validates the ID token with joserfc now, so the error that comes out of `authorize_access_token()` is `joserfc.errors.InvalidClaimError`. The handler catches the one in `authlib.jose.errors`, which is a different class with a different base, so the isinstance check is False. I confirmed it by validating a real `CodeIDToken` with a wrong `iss` on Authlib 1.9.1. I haven't run it against a live IdP. The existing tests passed because they raise the old class from a mock. The new one raises the error from a real `CodeIDToken`, and it fails on the old import with `'Authentication failed'` in place of the guidance. Two small things come with it: - The new class names its attribute `claim` where the old one used `claim_name`, so that read changes. - `authlib.jose` is deprecated in favour of joserfc and Authlib's own warning says it goes in 2.0. This was the only place Shelfmark used it, so the import moving also takes us off the module that is going away. joserfc is already installed as an Authlib requirement, so I added it to `pyproject.toml` (`>=1.6.8`, Authlib's own floor) and the lock gets the one entry. No new package. Ruff, basedpyright and the backend suite pass (5424 passed). --- pyproject.toml | 3 +++ shelfmark/core/oidc_routes.py | 4 ++-- tests/core/test_oidc_routes.py | 32 +++++++++++++++++++++++++++++++- uv.lock | 2 ++ 4 files changed, 38 insertions(+), 3 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index ce619eba..b3dc285e 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -22,6 +22,9 @@ dependencies = [ "qbittorrent-api>=2026.10.1", "transmission-rpc", "authlib>=1.9.1,<1.10", + # Authlib validates ID tokens with joserfc and raises its errors, so the OIDC routes + # catch joserfc's InvalidClaimError. authlib.jose is deprecated and goes in Authlib 2.0. + "joserfc>=1.6.8", "apprise>=2.0.1", # HTTP/2 client for RFC 8484 DoH: quad9 rejects HTTP/1.1 outright (505), which # requests cannot speak. See shelfmark/download/doh_wireformat.py. diff --git a/shelfmark/core/oidc_routes.py b/shelfmark/core/oidc_routes.py index 0fd19400..b407d646 100644 --- a/shelfmark/core/oidc_routes.py +++ b/shelfmark/core/oidc_routes.py @@ -12,8 +12,8 @@ from urllib.parse import urlencode, urlsplit, urlunsplit from authlib.integrations.base_client.errors import OAuthError from authlib.integrations.flask_client import OAuth -from authlib.jose.errors import InvalidClaimError from flask import Flask, jsonify, redirect, request, session +from joserfc.errors import InvalidClaimError from shelfmark.core.config import config as app_config from shelfmark.core.logger import setup_logger @@ -261,7 +261,7 @@ def register_oidc_routes(app: Flask, user_db: UserDB) -> None: try: token = client.authorize_access_token() except InvalidClaimError as e: - claim_name = getattr(e, "claim_name", "unknown") + claim_name = getattr(e, "claim", "unknown") discovery_url = str(config.get("OIDC_DISCOVERY_URL", "")) provider_issuer = "" try: diff --git a/tests/core/test_oidc_routes.py b/tests/core/test_oidc_routes.py index 8f716950..dbabc370 100644 --- a/tests/core/test_oidc_routes.py +++ b/tests/core/test_oidc_routes.py @@ -6,8 +6,9 @@ from unittest.mock import Mock, patch from urllib.parse import parse_qs, urlparse import pytest -from authlib.jose.errors import InvalidClaimError +from authlib.oidc.core import CodeIDToken from flask import Flask, redirect +from joserfc.errors import InvalidClaimError from shelfmark.core.user_db import UserDB @@ -463,6 +464,35 @@ class TestOIDCCallbackEndpoint: assert error is not None assert "issuer validation failed" in error + @patch("shelfmark.core.oidc_routes._get_oidc_client") + def test_callback_gives_issuer_guidance_for_the_error_authlib_really_raises( + self, mock_get_client, client + ): + # Authlib validates the ID token with joserfc, so the error that reaches the route is + # joserfc's. Raising it from a real CodeIDToken keeps this test honest if the class moves. + def validate_wrong_issuer(*_args, **_kwargs): + CodeIDToken( + { + "iss": "https://other.example.com", + "sub": "u", + "aud": "a", + "exp": 4102444800, + "iat": 1, + }, + {}, + {"iss": {"essential": True, "value": "https://auth.example.com"}}, + ).validate() + + fake_client = Mock() + fake_client.authorize_access_token.side_effect = validate_wrong_issuer + fake_client.load_server_metadata.return_value = {"issuer": "https://auth.example.com"} + mock_get_client.return_value = (fake_client, MOCK_OIDC_CONFIG) + + resp = client.get("/api/auth/oidc/callback?code=abc123&state=test-state") + error = _get_oidc_error(resp) + assert error is not None + assert "issuer validation failed" in error + @patch("shelfmark.core.oidc_routes._get_oidc_client") def test_callback_redirects_with_signing_key_guidance_on_empty_jwks( self, mock_get_client, client diff --git a/uv.lock b/uv.lock index d0d8a817..b3df1bc8 100644 --- a/uv.lock +++ b/uv.lock @@ -1562,6 +1562,7 @@ dependencies = [ { name = "gevent-websocket" }, { name = "gunicorn" }, { name = "httpx", extra = ["http2"] }, + { name = "joserfc" }, { name = "psutil" }, { name = "publicsuffixlist" }, { name = "python-socketio" }, @@ -1606,6 +1607,7 @@ requires-dist = [ { name = "gevent-websocket" }, { name = "gunicorn" }, { name = "httpx", extras = ["http2"], specifier = ">=0.28.1" }, + { name = "joserfc", specifier = ">=1.6.8" }, { name = "psutil" }, { name = "publicsuffixlist", specifier = ">=1.1.2.20261023" }, { name = "pyautogui", marker = "extra == 'browser'" },