Skip to content

docs: fix id_token lifetime and document MCP OAuth limitations - #199

Merged
pvliesdonk merged 2 commits into
mainfrom
198-oidc-token-docs
Mar 14, 2026
Merged

pvliesdonk merged 2 commits into
mainfrom
198-oidc-token-docs

Conversation

@pvliesdonk

Copy link
Copy Markdown
Owner

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:

Long token lifetimes are the only viable workaround until these are resolved.

Design Conformance

No design documents conflict. Design doc updated alongside.

Test plan

  • Documentation only — no code changes
  • All YAML examples updated consistently across 3 files

🤖 Generated with Claude Code

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]>
@chatgpt-codex-connector

Copy link
Copy Markdown

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

@claude

claude Bot commented Mar 14, 2026 •

Copy link
Copy Markdown
Contributor

Claude finished @pvliesdonk's task in 1m 2s —— View job


PR Review

  • Get PR diff
  • Read changed files
  • Review for accuracy and consistency
  • Post review feedback

Documentation-only PR. Changes are accurate, well-structured, and internally consistent across all three files.

What's good

  • The root cause is correct: verify_id_token mode re-validates id_token.exp on every request, so a 1h id_token kills sessions even with an 8h access_token. The fix (id_token: '8h') is the right call.
  • All three files (design.md, authentication.md, oidc-providers.md) are updated consistently — no file is left with stale examples.
  • The "Known Limitations" table is a good addition. The three upstream issues are accurately described and linked.
  • Anchor links (#known-limitations-mcp-oauth-token-refresh, #session-drops-after-token-expiry) are correctly formatted for GitHub Markdown rendering.

Minor observations (no blockers)

docs/guides/authentication.md line 207 — The server-side method is named OAuthProxy.exchange_refresh_token(). This is a FastMCP internal. If FastMCP renames it, this reference goes stale. Consider dropping the method name and just saying "the server-side refresh implementation is correct" — the point still lands without the fragile implementation detail.

docs/guides/authentication.md line 162 — "the server re-validates the upstream id_token on every request" is slightly overstated. The server validates the token on each authenticated request, but validation is typically of the local JWT (issued by FastMCP using OIDC_JWT_SIGNING_KEY), with the upstream id_token checked during the initial exchange. The practical effect is the same (session lifetime = id_token lifetime), but the phrasing may confuse readers who expect a round-trip to the IdP on each call. This is a pre-existing accuracy question, not introduced by this PR — fine to leave.

docs/guides/oidc-providers.md line 121 (unchanged line) — Links to authentication.md#session-drops-after-token-expiry. The heading still exists and the anchor is valid. No action needed.

Verdict

LGTM. The fix addresses a real, user-visible problem with a minimal, focused change. No code paths affected — safe to merge.

@gemini-code-assist

Copy link
Copy Markdown
Contributor

Summary of Changes

Hello, 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 id_token lifetime, especially when using Authelia's default verify_id_token mode, and provides comprehensive guidance on configuring token lifespans. Furthermore, it documents known, ecosystem-wide limitations of MCP clients regarding OAuth token refresh, offering workarounds and tracking information for these upstream issues to improve user understanding and troubleshooting.

Highlights

  • Authelia Lifespan Examples: Added id_token: '8h' to all Authelia lifespan examples to correctly reflect session validity when verify_id_token is enabled, preventing premature session drops.
  • MCP OAuth Limitations Documented: Introduced a new 'Known Limitations: MCP OAuth token refresh' section in the authentication guide, detailing ecosystem-wide issues with token refresh in MCP clients.
  • Design Document Update: Updated the design.md token lifetime recommendation to explicitly include id_token alongside access_token and refresh_token for comprehensive guidance.
Changelog
  • docs/design.md
    • Updated token lifetime recommendations to include id_token and a link to known limitations.
    • Added id_token: '8h' to the Authelia custom lifespan example.
  • docs/guides/authentication.md
    • Revised the 'Long-running sessions' tip to highlight MCP client refresh issues and recommend configuring all token lifetimes.
    • Expanded the 'Session drops after token expiry' section to detail id_token lifetime as a primary cause and provide a comprehensive workaround.
    • Added a new 'Known Limitations: MCP OAuth token refresh' section, explaining the problem, its causes across different MCP client layers, current workarounds, and tracking links.
  • docs/guides/oidc-providers.md
    • Updated comments and the mcp_long_lived custom lifespan example for Authelia to explicitly include and emphasize the id_token lifetime.
    • Revised the 'Token lifetimes' tip to clarify the importance of id_token and link to the new limitations section.
Activity
  • Documentation was updated to address session drops related to OIDC token lifespans.
  • All YAML examples across three files were consistently updated.
  • No code changes were introduced, as this PR is documentation-only.
Using Gemini Code Assist

The 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 /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature Command Description
Code Review /gemini review Performs a code review for the current pull request in its current state.
Pull Request Summary /gemini summary Provides a summary of the current pull request in its current state.
Comment @gemini-code-assist Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help /gemini help Displays a list of available commands.

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 .gemini/ folder in the base of the repository. Detailed instructions can be found here.

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

  1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread docs/guides/authentication.md Outdated

## Known Limitations: MCP OAuth token refresh

!!! warning "Ecosystem-wide issue (as of March 2026)"

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

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.

Suggested change
!!! warning "Ecosystem-wide issue (as of March 2026)"
!!! warning "Ecosystem-wide issue"

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@pvliesdonk

Copy link
Copy Markdown
Owner Author

/gemini review

@claude

claude Bot commented Mar 14, 2026 •

Copy link
Copy Markdown
Contributor

Claude encountered an error —— View job


I'll analyze this and get back to you.

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@pvliesdonk
pvliesdonk merged commit df3948e into main Mar 14, 2026
18 checks passed
@pvliesdonk
pvliesdonk deleted the 198-oidc-token-docs branch March 14, 2026 20:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: fix Authelia id_token lifetime and document upstream MCP OAuth limitations

1 participant