You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit df3948e
Browse filesBrowse the repository at this point in the historyBrowse files
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)
Copy file name to clipboardExpand all lines: docs/design.md
+2-1Lines changed: 2 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1037,7 +1037,7 @@ When all four required vars are set (`BASE_URL`, `OIDC_CONFIG_URL`, `OIDC_CLIENT
1037
1037
1038
1038
**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.
1039
1039
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.
1041
1041
1042
1042
**Authelia client registration** (in your Authelia `configuration.yml`):
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.
110
110
111
111
### Provider guides
112
112
@@ -155,17 +155,74 @@ Authentication only works with HTTP transport. If you're using `--transport stdi
155
155
156
156
### Session drops after token expiry
157
157
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.
159
159
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:
161
161
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.
164
163
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.
166
165
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.
168
181
169
182
### Opaque access tokens (Authelia)
170
183
171
184
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
# 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.
34
36
lifespans:
35
37
custom:
36
38
mcp_long_lived:
37
39
access_token: '8h'
40
+
id_token: '8h'
38
41
refresh_token: '30d'
39
42
clients:
40
43
- client_id: markdown-vault-mcp
@@ -61,7 +64,7 @@ identity_providers:
61
64
```
62
65
63
66
!!! 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.
0 commit comments