fix: treat Keycloak refresh_expires_in=0 as never-expires sentinel

[strawgate]

Fixes handling of Keycloak's refresh_expires_in=0 for offline tokens.

The bug: Keycloak returns refresh_expires_in=0 for offline_access tokens to mean "this refresh token never expires." The original code used Python's int truthiness (if int(val):), so 0 was treated as falsy and fell through to the 1-year wall-clock fallback. On subsequent refresh cycles the code inherited the decaying remaining time from that original timestamp — after ~1 year the FastMCP RT would be issued with a near-zero TTL, forcing re-authentication even though the Keycloak offline token was still valid.

Why not handle this globally: refresh_expires_in is not defined by RFC 6749 — it's a Keycloak extension. No spec-compliant provider would send 0 to mean "never expires." Treating 0 as a special sentinel in the base OAuthProxy would change behavior for all providers in an undocumented way.

The fix: KeycloakOAuthProxy(OAuthProxy), a new subclass in providers/keycloak.py, overrides _upstream_refresh_token_never_expires() to return True for val == 0. This keeps all Keycloak-specific knowledge in the Keycloak provider and leaves OAuthProxy unchanged for every other provider. A refresh_token_never_expires: bool field on UpstreamTokenSet persists the intent in stored state so that all three refresh paths (initial exchange, exchange_refresh_token, transparent access-token refresh) consistently issue a fresh full-TTL FastMCP RT on every cycle.

KeycloakOAuthProxy also provides a convenience constructor: pass realm_url and it derives the authorization, token, and revocation endpoints automatically.

from fastmcp import FastMCP
from fastmcp.server.auth.providers.keycloak import KeycloakOAuthProxy

auth = KeycloakOAuthProxy(
    realm_url="https://keycloak.example.com/realms/myrealm",
    upstream_client_id="my-client",
    upstream_client_secret="my-secret",
    base_url="https://my-mcp-server.example.com",
    jwt_signing_key="some-secret",
)

mcp = FastMCP("My App", auth=auth)

Refs #4054 — fixes Bug 3 (Keycloak refresh_expires_in=0). Bugs 1, 2 and 4 are tracked separately on that issue. Note this also introduces KeycloakOAuthProxy as a first-class provider with realm_url-based endpoint derivation.

[marvin-context-protocol]

Edited to reflect the latest CI run (#25815958614). The previous TTL test failure is fixed; a new static-analysis failure has appeared.

tl;dr: ruff check fails on tests/server/auth/oauth_proxy/test_tokens.py:1025 with F811: Redefinition of unused proxy from line 661 — two @pytest.fixtures named proxy exist inside the same TestUpstreamTokenStorageTTL class (line 644). ruff format also wants to reformat the same file.

Root Cause: Both fixture definitions live inside TestUpstreamTokenStorageTTL — the original at tests/server/auth/oauth_proxy/test_tokens.py:661 (def proxy(self, jwt_verifier)) and a newly added one at line 1025 (def proxy(self, mock_verifier)). There is no intervening class statement (the next class boundary in the file is TestUpstreamTokenStorageTTL itself at line 644), so the second proxy shadows the first within the same class scope. Ruff catches this as F811. Ruff format separately wants a small reformat of the same file.

Fix: Move the new transparent-refresh tests (and their mock_verifier + second proxy fixture, starting around line 1024) into a new class — e.g. class TestTransparentUpstreamRefresh: — so each fixture lives in its own class scope. Then run uv run prek run --all-files locally and commit both the moved tests and the auto-applied ruff-format fix.

Log excerpt

F811 Redefinition of unused `proxy` from line 661
    --> tests/server/auth/oauth_proxy/test_tokens.py:1025:9
     |
1024 |     @pytest.fixture
1025 |     def proxy(self, mock_verifier):
     |         ^^^^^ `proxy` redefined here
...
 660 |     @pytest.fixture
 661 |     def proxy(self, jwt_verifier):
     |         ----- previous definition of `proxy` here
Found 1 error.

ruff format ... Failed
1 file reformatted, 760 files left unchanged

Related files

• tests/server/auth/oauth_proxy/test_tokens.py:644 — class TestUpstreamTokenStorageTTL: (only class containing both fixtures)
• tests/server/auth/oauth_proxy/test_tokens.py:660-662 — first proxy fixture (uses jwt_verifier)
• tests/server/auth/oauth_proxy/test_tokens.py:1024-1037 — duplicate proxy fixture (uses mock_verifier) — likely belongs in a new test class for the transparent-refresh tests below it

[strawgate]

I'm a little worried about handling this 0 sentinel globally, will investigate

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f19df2dce7

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".