Skip to content

Commit df3948e

Browse files
authored
docs: fix id_token lifetime and document MCP OAuth limitations (#199)
## Summary - Add `id_token: '8h'` to all Authelia lifespan examples — the id_token (not access_token) gates session validity when `verify_id_token` is enabled - Add "Known Limitations: MCP OAuth token refresh" section to auth guide documenting the ecosystem-wide problem - Update design.md token lifetime recommendation to include id_token Closes #198 ## Root Cause Sessions drop after ~1h because Authelia defaults `id_token` to 1h. With `verify_id_token=True` (required for Authelia's opaque access tokens), the server re-validates the id_token `exp` on every request. Setting `access_token: '8h'` without `id_token: '8h'` creates a false sense of security. ## Upstream Context Token refresh is broken across the entire MCP ecosystem: - [claude-code#21333](anthropics/claude-code#21333) — refresh tokens stored but never used - [claude-code#7744](anthropics/claude-code#7744) — `offline_access` never requested - [python-sdk#1326](modelcontextprotocol/python-sdk#1326) — SSE refresh deadlock Long token lifetimes are the only viable workaround until these are resolved. ## Design Conformance No design documents conflict. Design doc updated alongside. ## Test plan - [x] Documentation only — no code changes - [x] All YAML examples updated consistently across 3 files 🤖 Generated with [Claude Code](https://claude.com/claude-code)
2 parents 4ef6514 + bd6a8cd commit df3948e

3 files changed

Lines changed: 73 additions & 12 deletions

File tree

‎docs/design.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1037,7 +1037,7 @@ When all four required vars are set (`BASE_URL`, `OIDC_CONFIG_URL`, `OIDC_CLIENT
10371037

10381038
**Token verification:** By default the server verifies the upstream `id_token` (always a standard JWT per OIDC Core) rather than the `access_token`. This works with all providers, including those that issue opaque (non-JWT) access tokens (e.g. Authelia). Set `MARKDOWN_VAULT_MCP_OIDC_VERIFY_ACCESS_TOKEN=true` to revert to access-token JWT verification when audience-claim validation on that token is required.
10391039

1040-
**Token lifetime recommendations:** MCP clients do not reliably re-authenticate after token expiry. Configure long token lifetimes on your identity provider (e.g. 8h access tokens, 30d refresh tokens) and include `offline_access` in the provider-side scopes. See the [authentication guide](guides/authentication.md#session-drops-after-token-expiry) for details and upstream issue links.
1040+
**Token lifetime recommendations:** MCP clients do not reliably refresh tokens (see [Known Limitations](guides/authentication.md#known-limitations-mcp-oauth-token-refresh)). Configure all token lifetimes on your identity provider: `access_token: '8h'`, `id_token: '8h'`, `refresh_token: '30d'`. The `id_token` lifetime is critical when using `verify_id_token` mode — if shorter than `access_token`, the session dies at the `id_token` expiry regardless of the access token setting. Include `offline_access` in provider-side scopes for when clients support refresh.
10411041

10421042
**Authelia client registration** (in your Authelia `configuration.yml`):
10431043
```yaml
@@ -1047,6 +1047,7 @@ identity_providers:
10471047
custom:
10481048
mcp_long_lived:
10491049
access_token: '8h'
1050+
id_token: '8h'
10501051
refresh_token: '30d'
10511052
clients:
10521053
- client_id: markdown-vault-mcp

‎docs/guides/authentication.md‎

Lines changed: 64 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -106,7 +106,7 @@ Client → markdown-vault-mcp (OIDCProxy) → OIDC Provider
106106
```
107107
108108
!!! tip "Long-running sessions"
109-
Configure `offline_access` scope on your identity provider to enable refresh tokens. Combined with long token lifetimes, this prevents session drops during extended use. See [Session drops after token expiry](#session-drops-after-token-expiry) in Troubleshooting.
109+
Current MCP clients do not reliably refresh tokens — see [Known Limitations](#known-limitations-mcp-oauth-token-refresh). Configure **all** token lifetimes (access, id, refresh) on your identity provider to cover a full workday (8h+). For simpler deployments, bearer token auth is unaffected by these limitations.
110110
111111
### Provider guides
112112
@@ -155,17 +155,74 @@ Authentication only works with HTTP transport. If you're using `--transport stdi
155155

156156
### Session drops after token expiry
157157

158-
**Symptom:** the MCP client works for a few hours, then starts returning 401 errors or stops responding. Restarting the client fixes it temporarily.
158+
**Symptom:** the MCP client works for a period (often ~1 hour), then starts returning 401 errors or stops responding. Restarting the client fixes it temporarily.
159159

160-
**Root cause:** MCP clients (Claude.ai, Claude Code) do not reliably re-authenticate when both access and refresh tokens expire. This is a known ecosystem-wide issue:
160+
**Root cause:** this is almost always a token lifetime issue, not a server bug. Check three things:
161161

162-
- Claude Code ignores `scopes_supported` and never requests `offline_access`, so no refresh token is issued ([claude-code#7744](https://github.com/anthropics/claude-code/issues/7744))
163-
- The MCP Python SDK can deadlock during token refresh inside an active SSE stream ([python-sdk#1326](https://github.com/modelcontextprotocol/python-sdk/issues/1326))
162+
1. **id_token lifetime** (most common): When using `verify_id_token` mode (the default for Authelia), the server re-validates the upstream `id_token` on every request. If your provider's `id_token` lifetime is shorter than the `access_token` lifetime, the session dies at the `id_token` expiry — even though the access token is still valid. Authelia defaults `id_token` to 1 hour. **Fix: set `id_token` lifetime to match `access_token`** in your provider config.
164163

165-
**Workaround:** configure long token lifetimes on your identity provider so tokens outlast a typical session. For example, set access tokens to 8 hours and refresh tokens to 30 days. Also include `offline_access` in the scopes configured on the provider side — even though current clients may not request it, future client updates may use it.
164+
2. **access_token lifetime**: If both `id_token` and `access_token` are set correctly but sessions still drop, check that the provider's `expires_in` response matches your configured lifetime.
166165

167-
See the [Authelia provider guide](oidc-providers.md#authelia) for specific configuration.
166+
3. **No refresh token**: See [Known Limitations](#known-limitations-mcp-oauth-token-refresh) below — current MCP clients cannot refresh tokens, so sessions are limited to the token lifetime.
167+
168+
**Workaround:** configure **all** token lifetimes on your identity provider to cover a full workday:
169+
170+
```yaml
171+
# Authelia example
172+
lifespans:
173+
custom:
174+
mcp_long_lived:
175+
access_token: '8h'
176+
id_token: '8h' # must match access_token for verify_id_token mode
177+
refresh_token: '30d'
178+
```
179+
180+
See the [Authelia provider guide](oidc-providers.md#authelia) for the full configuration.
168181
169182
### Opaque access tokens (Authelia)
170183
171184
Authelia issues opaque (non-JWT) access tokens. This is handled automatically — the server verifies the `id_token` instead. No extra configuration needed. See the [Authelia guide](oidc-providers.md#authelia) for details.
185+
186+
---
187+
188+
## Known Limitations: MCP OAuth token refresh
189+
190+
!!! warning "Ecosystem-wide issue"
191+
The limitations below affect **all** OAuth-protected MCP servers, not just markdown-vault-mcp. They are caused by issues in the MCP client implementations (Claude Code, Claude.ai, Claude Desktop) and the MCP Python SDK. Check the linked tracking issues for current status.
192+
193+
### The problem
194+
195+
MCP clients cannot maintain sessions beyond the token lifetime because token refresh does not work. When tokens expire, the session drops and requires manual re-authentication. This affects every provider — Authelia, Keycloak, Google, Slack, Notion, Atlassian, and others.
196+
197+
### Why refresh doesn't work
198+
199+
Three independent issues prevent token refresh:
200+
201+
| Layer | Issue | Impact |
202+
|-------|-------|--------|
203+
| **Claude Code** | Stores refresh tokens but never uses them ([claude-code#21333](https://github.com/anthropics/claude-code/issues/21333)) | Refresh tokens are obtained and saved but never sent back to refresh expired access tokens |
204+
| **Claude Code** | Never requests `offline_access` scope ([claude-code#7744](https://github.com/anthropics/claude-code/issues/7744)) | Most OIDC providers won't issue a refresh token without this scope |
205+
| **MCP Python SDK** | Token refresh deadlocks inside SSE streams ([python-sdk#1326](https://github.com/modelcontextprotocol/python-sdk/issues/1326)) | Even with a valid refresh token, the SDK hangs when attempting refresh during an active stream |
206+
207+
The server-side refresh architecture (FastMCP's `OAuthProxy.exchange_refresh_token()`) is correctly implemented and would work — but it requires the client to initiate the refresh, which none of the current clients do reliably.
208+
209+
### What works today
210+
211+
**Bearer token auth** is unaffected by all of the above. If your deployment allows it (e.g., Claude Code with env vars, or API clients), bearer tokens are the simplest and most reliable option.
212+
213+
**Long token lifetimes** are the only viable workaround for OIDC. Set all three lifetimes (access, id, refresh) to cover your typical session duration:
214+
215+
- `access_token: '8h'` — covers a workday
216+
- `id_token: '8h'` — **must match access_token** when using `verify_id_token` mode (critical for Authelia)
217+
- `refresh_token: '30d'` — ready for when clients support refresh
218+
- Include `offline_access` in provider-side scopes — no effect today, but will enable refresh when clients are fixed
219+
220+
### Tracking
221+
222+
These upstream issues are actively tracked:
223+
224+
- [anthropics/claude-code#21333](https://github.com/anthropics/claude-code/issues/21333) — refresh tokens stored but never used
225+
- [anthropics/claude-code#7744](https://github.com/anthropics/claude-code/issues/7744) — `offline_access` scope never requested
226+
- [modelcontextprotocol/python-sdk#1326](https://github.com/modelcontextprotocol/python-sdk/issues/1326) — SSE refresh deadlock
227+
228+
When these are resolved, OIDC sessions should persist indefinitely via automatic token refresh with no changes needed to markdown-vault-mcp.

‎docs/guides/oidc-providers.md‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -28,13 +28,16 @@ Add the client and a custom lifespan under `identity_providers.oidc` in your Aut
2828
identity_providers:
2929
oidc:
3030
# Custom lifespan for long-running MCP sessions.
31-
# Default Authelia lifespans: access_token=1h, refresh_token=90m.
32-
# MCP clients do not reliably re-authenticate after token expiry,
33-
# so longer lifetimes prevent session drops.
31+
# Default Authelia lifespans: access_token=1h, id_token=1h, refresh_token=90m.
32+
# MCP clients do not reliably refresh tokens (see Known Limitations in
33+
# the authentication guide), so all lifetimes must cover a full workday.
34+
# IMPORTANT: id_token must match access_token — when verify_id_token=true
35+
# (the default for Authelia), the id_token exp claim gates session validity.
3436
lifespans:
3537
custom:
3638
mcp_long_lived:
3739
access_token: '8h'
40+
id_token: '8h'
3841
refresh_token: '30d'
3942
clients:
4043
- client_id: markdown-vault-mcp
@@ -61,7 +64,7 @@ identity_providers:
6164
```
6265
6366
!!! tip "Token lifetimes"
64-
MCP clients (Claude.ai, Claude Code) do not reliably re-authenticate when tokens expire. The `mcp_long_lived` custom lifespan sets `access_token` to 8 hours and `refresh_token` to 30 days so tokens outlast a typical session. See [Authelia OIDC Provider — Lifespans](https://www.authelia.com/configuration/identity-providers/openid-connect/provider/#lifespans) for the full reference.
67+
MCP clients (Claude.ai, Claude Code) do not reliably refresh tokens — see [Known Limitations](authentication.md#known-limitations-mcp-oauth-token-refresh). The `mcp_long_lived` custom lifespan sets both `access_token` and `id_token` to 8 hours so tokens outlast a typical work session. The `id_token` lifetime is critical when using `verify_id_token` mode (the default for Authelia) — if omitted, Authelia defaults it to 1 hour regardless of the `access_token` setting. See [Authelia OIDC Provider — Lifespans](https://www.authelia.com/configuration/identity-providers/openid-connect/provider/#lifespans) for the full reference.
6568

6669
### 2. Generate and hash a client secret
6770

0 commit comments

Comments
 (0)