Skip to content

[Access] Clarify Managed OAuth token format, multi-domain behavior, and session tuning#30825

Open
kennyj42 wants to merge 1 commit into
cloudflare:productionfrom
kennyj42:kjohnson/managed-oauth-clarifications
Open

[Access] Clarify Managed OAuth token format, multi-domain behavior, and session tuning#30825
kennyj42 wants to merge 1 commit into
cloudflare:productionfrom
kennyj42:kjohnson/managed-oauth-clarifications

Conversation

@kennyj42
Copy link
Copy Markdown
Contributor

@kennyj42 kennyj42 commented May 14, 2026

Summary

Clarifies Managed OAuth behavior based on customer feedback and internal engineering review.

Changes

Managed OAuth page (managed-oauth.mdx):

  • Token format section: Documents that Managed OAuth issues opaque tokens (not JWTs), explains why (by design — clients act on behalf of users without seeing identity), and how the token is resolved server-side. Links to Linked App Token as the pattern for downstream requests.
  • Multi-domain applications section: Documents that an OAuth token obtained via one domain is valid for all domains in the same Access application — single auth, multiple endpoints without a proxy.
  • Session tuning guidance: Adds a callout recommending short access token lifetime (5–15 min) + long grant session duration (1–2 weeks) for CLI/agent use cases, explaining the practical impact on user experience (silent refresh vs. re-authentication prompts).

Linked App Token known limitations (linked-app-token-known-limitations.mdx):

  • Adds a limitation noting that Managed OAuth opaque tokens cannot be forwarded directly as Cf-Access-Token to downstream apps. Documents the proxy pattern (origin reads Cf-Access-Jwt-Assertion and forwards) and points to multi-domain apps as an alternative.

Context

A customer built a custom Go OAuth client for CLI access to their Access-protected internal tools and hit several points of confusion that the current docs don't address: opaque vs JWT token format, how tokens work across multiple domains, and how to tune session settings to minimize re-authentication prompts. These doc updates address those gaps for all customers.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants