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).
This commit is contained in:
splitsec2 authored and GitHub committed 2026-10-27 11:06:51 -06:00
1 parent 947ce7bfe5
commit 7583f997bb
4 files changed
+38 -3

No files matched your search

+3
View File
@@ -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.
+2 -2
View File
@@ -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:
+31 -1
View File
@@ -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
Generated
+2
View File
@@ -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'" },