fix(b2b_learner_records): verify the bearer JWT instead of trusting X-Userinfo

[blarghmatey]

What are the relevant tickets?

N/A. Copilot raised this on mitodl/ol-infrastructure#5939. Implements the decision now recorded in docs/b2b-learner-records-provider-authorization.md.

Description (What does it do?)

The learner-records tenant authorized entirely from X-Userinfo. core/auth/userinfo.py decodes whatever header arrives, and APISIX rebuilds that header only for traffic that goes through APISIX. Nothing forces a caller to: the pod security group admits the whole pod subnet (applications/ol_analytics_api/__main__.py:412, get_default_psg_ingress_args), and aws-eks-nodeagent runs with --enable-network-policy=false on both data clusters (checked 2026-09-18; infrastructure/aws/eks/__main__.py:414 sets it), so the clickhouse and jupyter-data NetworkPolicies are no-ops. A compromised in-cluster workload could post a forged X-Userinfo carrying learner-records:read and any organization UUID and read identifiable learner records.

This verifies the token in the app. tenants/b2b_learner_records/token.py reads the bearer from Authorization (falling back to X-Access-Token, which the gateway sets and its own plugin accepts as a bearer), checks RS256 against the realm JWKS, and checks issuer, audience, token class and exp/nbf/iat. require_organization_grant then takes scope, learner_records_organizations and azp from the verified payload. This tenant does not read X-Userinfo at all. Every failure gets the same 401, which doesn't say which check failed.

The token class matters more than it looks: an ID token minted for ol-analytics-api-client carries the realm's signature, this issuer and this audience, so without typ it clears verification and is stopped only by carrying no organization claim. That is one claim deep.

The key set is cached for a TTL and refetched once on an unseen kid, so a realm key rotation costs one fetch rather than a TTL of 401s; a cooldown keeps forged kids from turning the endpoint into an amplifier pointed at Keycloak, and it starts only once a freshly fetched set really lacked the kid. A fetch failure holds off further attempts briefly and falls back on the key set already in hand. Realm keys turn over on the order of months, so refusing every request because a refresh failed would be an outage this service inflicted on itself. With no key set at all it refuses. Anything the endpoint can answer with that isn't a usable key set is a 401, not a 500.

Config derives token_url and jwks_url from a single issuer, and the tenant refuses to start if issuer is left at the production realm in any other deployed environment, because every failure mode of that setting is a silent 401 that reads like a bad credential. mitodl/ol-infrastructure#5939 templates issuer and audience out of secret-operations/sso/ol-analytics-api, the same Vault entry the route's openid-connect plugin reads for its discovery URL and client id, so the gateway and the app can't end up checking different realms.

b2b_dashboard still reads X-Userinfo. Its exposure is aggregate and k-anonymized and it has a browser session flow, so that is a separate call, not a follow-up to this one.

How can this be tested?

• uv run pytest: 312 passed. tests/test_learner_records_token.py covers a valid token accepted; a forged X-Userinfo alone refused; a forged X-Userinfo failing to widen a valid narrow token; wrong audience, wrong issuer, expired, not-yet-valid, missing exp, missing typ, an ID token, missing kid, alg=none, HS256 signed with the public key out of the JWKS, and a token signed by an impostor key all refused; the multi-audience shape Keycloak actually emits accepted; the X-Access-Token path accepted and verified; and the caching, rotation-refetch, cooldown, TTL, stale-fallback, unreachable-JWKS and unusable-key-set behaviour.
• tests/conftest.py mints real RS256 tokens from a test realm, so tests/test_learner_records.py now drives the tenant with signed tokens rather than a base64 claims blob. All 34 of its existing cases pass unchanged otherwise.
• uv run ruff check, ruff format --check, and uv run mypy src: clean.
• Not verified against a real Keycloak token. The APISIX header behaviour was read out of the openid-connect plugin source at 3.18.0, not observed on QA: rewrite clears a client-supplied X-Userinfo/X-Access-Token, and the plugin only ever writes Authorization when access_token_in_authorization_header is set, which this route does not set. Worth confirming on QA with a real client-credentials token once #5939 is applied, including that Keycloak emits typ: "Bearer" on these tokens, which this now requires.

Additional Context

A security review pass ran against this branch before it opened. It found no way to authorize without a validly-signed, unexpired token for the right issuer and audience. The second commit is its other findings: the 500-instead-of-401 path, the fetch-failure pile-up, the missing token-class check, and a concurrency test that pinned the cache rather than the lock (it passed with the lock removed, because a mocked transport never suspends).

Reading the token from X-Access-Token as well as Authorization is broader than strictly needed. It costs nothing (both go through the same signature check) and it keeps this working if the route is ever configured the other way, but it is worth an explicit look.

Checklist:

• Merge feat(keycloak): issue per-contract learner-records clients ol-infrastructure#5939 (which carries the issuer/audience env vars) before or with this. Without it a QA or CI pod now fails to start, by design.
• Fetch a token from a QA learner-records client and confirm a 200, and a 401 for a token from another olapps client

🤖 Generated with Claude Code

https://claude.ai/code/session_01Qoz9pfQxUU8VLsRxr1tTnm

[Copilot]

Copilot review overview

🟡 Changes recommended

Failed JWKS refreshes can incorrectly suppress recovery after key rotation, and the documented 401 body does not match runtime behavior.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 2

Open (2)

• Error schema requires code but runtime 401 responses only return detail · New
• Failed key refresh incorrectly triggers unknown-kid cooldown · New

What changed in this PR

Adds application-level JWT verification for learner-record endpoints, removing their reliance on trusted X-Userinfo headers.

Changes:

• Verifies RS256 tokens against cached realm JWKS.
• Authorizes using verified scope and organization claims.
• Adds configuration, documentation, and comprehensive authentication tests.

File	Description
src/​ol_analytics_api/​tenants/​b2b_learner_records/​token.py	Implements JWT verification and JWKS caching.
src/​ol_analytics_api/​tenants/​b2b_learner_records/​config.py	Adds issuer, audience, and JWKS settings.
src/​ol_analytics_api/​tenants/​b2b_learner_records/​auth.py	Authorizes from verified token claims.
tests/​conftest.py	Provides signing keys and JWT fixtures.
tests/​test_learner_records.py	Migrates endpoint tests to signed tokens.
tests/​test_learner_records_token.py	Tests verification, caching, and failure handling.
pyproject.toml	Adds JWT and cryptography dependencies.
uv.lock	Locks new cryptographic dependencies.
README.md	Documents the revised trust boundary.
docs/​openapi/​b2b-learner-records-v1.yaml	Updates authentication API documentation.
docs/​b2b-learner-records-provider-authorization.md	Records the authorization decision.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.