Repository navigation
docs: fix id_token lifetime and document MCP OAuth limitations - #199
Conversation
Add id_token: '8h' to all Authelia lifespan examples — the id_token lifetime (not access_token) gates session validity when verify_id_token is enabled. Authelia defaults id_token to 1h, causing sessions to drop after 1 hour despite 8h access tokens. Add "Known Limitations" section to auth guide documenting the upstream MCP OAuth token refresh problem affecting all providers: - Claude Code stores refresh tokens but never uses them (#21333) - Claude Code never requests offline_access scope (#7744) - MCP SDK SSE refresh deadlock (python-sdk#1326) Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
|
Claude finished @pvliesdonk's task in 1m 2s —— View job PR Review
Documentation-only PR. Changes are accurate, well-structured, and internally consistent across all three files. What's good
Minor observations (no blockers)
VerdictLGTM. The fix addresses a real, user-visible problem with a minimal, focused change. No code paths affected — safe to merge. |
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request significantly enhances the documentation regarding OpenID Connect (OIDC) token lifetimes and addresses common session drop issues experienced by users. It clarifies the critical role of the Highlights
Changelog
Activity
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
There was a problem hiding this comment.
Code Review
This pull request significantly improves the documentation around OIDC authentication, specifically addressing token lifetime issues with Authelia and documenting the broader ecosystem limitations with MCP OAuth token refresh. The changes are clear, well-structured, and provide valuable context and workarounds for users. I've found one minor issue with a future date in the documentation that could cause confusion.
|
|
||
| ## Known Limitations: MCP OAuth token refresh | ||
|
|
||
| !!! warning "Ecosystem-wide issue (as of March 2026)" |
There was a problem hiding this comment.
The date "March 2026" appears to be a typo, as it refers to a future date. This could be confusing to readers. I suggest replacing it with the current year or removing the date to prevent the documentation from becoming outdated.
| !!! warning "Ecosystem-wide issue (as of March 2026)" | |
| !!! warning "Ecosystem-wide issue" |
There was a problem hiding this comment.
Fixed in bd6a8cd. The date was technically correct (today is March 2026) but hardcoded dates age poorly. Removed the date and added "Check the linked tracking issues for current status" instead.
|
/gemini review |
|
Claude encountered an error —— View job I'll analyze this and get back to you. |
There was a problem hiding this comment.
Code Review
This pull request provides crucial documentation updates regarding OIDC authentication, particularly for Authelia. It clarifies the necessity of aligning the id_token lifetime with the access_token lifetime to prevent unexpected session termination, a common pitfall. The changes are consistently applied across the design document and user guides. A new 'Known Limitations' section is a valuable addition, detailing the broader MCP ecosystem challenges with OAuth token refresh and offering clear workarounds. These improvements will significantly enhance user experience and reduce troubleshooting time. The changes are well-written and thorough.
Summary
id_token: '8h'to all Authelia lifespan examples — the id_token (not access_token) gates session validity whenverify_id_tokenis enabledCloses #198
Root Cause
Sessions drop after ~1h because Authelia defaults
id_tokento 1h. Withverify_id_token=True(required for Authelia's opaque access tokens), the server re-validates the id_tokenexpon every request. Settingaccess_token: '8h'withoutid_token: '8h'creates a false sense of security.Upstream Context
Token refresh is broken across the entire MCP ecosystem:
offline_accessnever requestedLong token lifetimes are the only viable workaround until these are resolved.
Design Conformance
No design documents conflict. Design doc updated alongside.
Test plan
🤖 Generated with Claude Code