Repository navigation
Open
Labels
area:auth-securityKeycloak, secrets, JWT, timeouts, resilience of external callsKeycloak, secrets, JWT, timeouts, resilience of external callseffort:MMedium: one layer (backend or frontend), a few daysMedium: one layer (backend or frontend), a few dayspolishAdmin/UI surfacing or refinement of existing capability, not new functionalityAdmin/UI surfacing or refinement of existing capability, not new functionalitypriority:P2Valuable, not urgentValuable, not urgenttype:improvementMakes an existing capability better/safer/more completeMakes an existing capability better/safer/more complete
Description
Context
Same audit as #68 (docs/CONFIG_AUDIT_2026-09-04.md, Part 2) found a second cluster of hardcoded operational knobs, this time around JWKS caching and outbound HTTP timeouts for Keycloak and the doc-search MCP client. None of these are covered by the existing SystemSettings-backed config (LLM/embedding provider, retention, guardrails, tracing, rate-limiting).
Gaps found
JWKS caching (auth):
backend/app/core/auth.py:20—_JWKS_CACHE_TTL = 600(10 min)mcp-servers/doc-search/app/auth.py:26—_JWKS_CACHE_TTL = 600(duplicated in the second deployable, own cache)mcp-servers/doc-search/app/auth.py:40—_JWKS_REFETCH_COOLDOWN_SECONDS = 30(rate-limits forced refetch on an unknownkid, protecting Keycloak from being hammered)
Outbound HTTP timeouts:
backend/app/api/auth.py:141—timeout=10.0on the Keycloak token-exchange POST (login/refresh)mcp-servers/doc-search/app/auth.py:79—timeout=10.0on the JWKS fetchbackend/app/mcp_client/doc_search_client.py:30—MCP_CALL_TIMEOUT = timedelta(seconds=30)(the actualsearch_knowledge_basetool call)backend/app/mcp_client/doc_search_client.py:63—_CONNECT_TIMEOUT_SECONDS = 30.0backend/app/mcp_client/doc_search_client.py:64—_SSE_READ_TIMEOUT_SECONDS = 300.0
All are plain numeric values, resolved (or read) fresh on every call/request — none require a process restart to take effect, unlike tracing_enabled.
Why bundle these together
Same resolver pattern, same "Timeouts & Caching" Settings UI section, and an operator tuning one (e.g. a slower Keycloak, or doc-search under heavier load) plausibly wants to tune several together.
Scope
- Add nullable
SystemSettingscolumns for each value above (7 fields total; the two_JWKS_CACHE_TTLconstants should share one setting since they're the same knob duplicated across two deployables — doc-search already resolves its own DB-backed config independently the wayembedding_providerdoes, so this is a proven pattern to copy). resolve_timeout_config(or fold into an existing resolver if a smaller shape emerges during implementation) followingdocs/BACKEND_SERVICES.md.- Wire each into its call site, replacing the module constants.
- Settings UI: new "Timeouts & Caching" section, tooltips per field.
- Audit-log on change, following the existing pattern.
Non-goals
keycloak_client_secretandrate_limit_trusted_proxy_countare explicitly excluded — they were reviewed in the same audit and judged not to be configurability gaps: the former is a credential (DB-storing it via this pattern would be a security regression), the latter is fixed deployment topology that's security-sensitive if misconfigured. Do not add these here or elsewhere without a separate, explicit design discussion.- No retry/backoff logic is added here — see the separate retry/backoff issue. This issue is timeout values only, not retry behavior.
Definition of Done
- New nullable
SystemSettingscolumns + Alembic migration for the 6 distinct knobs (JWKS TTL shared across both deployables, JWKS refetch cooldown, Keycloak token-exchange timeout, doc-search JWKS fetch timeout, MCP call/connect/SSE timeouts). - Resolver service function(s), unit-tested.
- All knobs wired into their actual call sites in both
backend/andmcp-servers/doc-search/. - Settings UI section with tooltips; component-tested.
- Audit logging on change.
- RBAC call-out per
AGENTS.mdTDD Discipline step 0: admin feature, gated byrequire_admin. - Standard merge gate from
AGENTS.md's Definition of Done applies in full.
Metadata
Metadata
Assignees
Labels
area:auth-securityKeycloak, secrets, JWT, timeouts, resilience of external callsKeycloak, secrets, JWT, timeouts, resilience of external callseffort:MMedium: one layer (backend or frontend), a few daysMedium: one layer (backend or frontend), a few dayspolishAdmin/UI surfacing or refinement of existing capability, not new functionalityAdmin/UI surfacing or refinement of existing capability, not new functionalitypriority:P2Valuable, not urgentValuable, not urgenttype:improvementMakes an existing capability better/safer/more completeMakes an existing capability better/safer/more complete
Activity