docs: Fix the "Could not open websocket" / multiple-accounts OAuth troubleshooting

[MarcSkovMadsen]

Summary

Addresses the documentation half of #8634 ("Azure OAuth not working with multiple accounts").

The OAuth troubleshooting guide currently attributes the "Could not open websocket" failure to "multiple accounts" and recommends incognito / clearing cookies / a different browser. Investigation of #8634 shows that description is misleading:

• The real cause is request-header size. Bokeh embeds the originating request's OAuth cookies into the session token, which the browser sends back in the Sec-WebSocket-Protocol header on the /ws upgrade. When that header exceeds the proxy's per-request-header buffer (nginx large_client_header_buffers, default 8 KB) the proxy returns HTTP 400 and the upgrade never reaches the Panel server.
• "Multiple accounts" don't enlarge the app's request headers (those cookies live on the identity provider's domain). Incognito / another browser only appear to fix it because they carry slightly smaller headers and slip back under the limit — not a reliable fix.

Changes

doc/how_to/authentication/trouble_shooting.md

• Replace Cause: Token Too Big + Cause: Multiple Accounts with Cause: Request Headers Too Big, explaining the mechanism, how to diagnose it (DevTools / net-export, the HTTP 400, the Sec-WebSocket-Protocol/Cookie header sizes), and real fixes:
  1. raise the proxy request-header buffer (incl. the ingress-nginx ConfigMap caveat — it isn't a per-Ingress annotation);
  2. --exclude-cookies access_token id_token refresh_token (with the pn.state.* tradeoff);
  3. reduce token size (fewer scopes, Azure group overage);
  4. drop the encryption key.
• Add "A note on multiple accounts" clarifying they aren't the cause, and pointing to prompt for controlling account selection.

doc/how_to/authentication/providers/azure.md

• Add a "Handling multiple accounts" section documenting oauth_extra_params prompt=select_account / prompt=login (enabled by Forward additional oauth_extra_params to the OAuth authorization endpoint #8635), with a note that Could not open websocket is a header-size issue rather than an account issue.

Related

• Forward additional oauth_extra_params to the OAuth authorization endpoint #8635 makes prompt actually reach the authorize endpoint (referenced from the new Azure docs).
• Token size issue when using oauth encryption key #7909 is the original report of the token-size/proxy-buffer issue.

🤖 Generated with Claude Code