[DOCS]: iframe component session isolation issue #240

New Issue

2026-02-16T05:19:32-05:00

yindo commented

2026-02-16 05:19:32 -05:00

Originally created by @wjt123454321 on GitHub (Sep 10, 2025).

Type of Documentation Change

Error/Typo fix

Documentation Page URL or Path

No response

Current Content

Excuse me, how to implement user and session management? The iframe uses localStorage to store the session ID internally, which causes the frontend application to still display the session of the previous user even after switching login accounts.

Suggested Changes

give iframe options to control session

Reason for Change

No response

Code of Conduct

I agree to follow Dify's documentation contribution guidelines
I have searched for existing issues search for existing issues, including closed ones.
I confirm that I am using English to submit this report, otherwise it will be closed.
【中文用户 & Non English User】请使用英语提交，否则会被关闭：）
Please do not modify this template :) and fill in all the required fields.

Originally created by @wjt123454321 on GitHub (Sep 10, 2025). ### Type of Documentation Change Error/Typo fix ### Documentation Page URL or Path _No response_ ### Current Content Excuse me, how to implement user and session management? The iframe uses localStorage to store the session ID internally, which causes the frontend application to still display the session of the previous user even after switching login accounts. ### Suggested Changes give iframe options to control session ### Reason for Change _No response_ ### Code of Conduct - [x] I agree to follow Dify's documentation [contribution guidelines](https://github.com/langgenius/dify/blob/0277a37fcad5ad86aeb239485c27fffd5cd90043/CONTRIBUTING.md) - [x] I have searched for existing issues [search for existing issues](https://github.com/langgenius/dify/issues), including closed ones. - [x] I confirm that I am using English to submit this report, otherwise it will be closed. - [x] 【中文用户 & Non English User】请使用英语提交，否则会被关闭：） - [x] Please do not modify this template :) and fill in all the required fields.

yindo added the documentation enhancement labels 2026-02-16 05:19:32 -05:00

yindo closed this issue

2026-02-16 05:19:32 -05:00

yindo commented

2026-02-16 05:19:32 -05:00

@dosubot[bot] commented on GitHub (Sep 10, 2025):

Hi @wjt123454321! I'm Dosu and I’m helping the dify-docs team.

Dify's iframe embed manages session state using localStorage, keyed by both appId and userId. To isolate sessions for different users, you should pass a unique, properly encoded userId as a URL parameter (sys.user_id) when generating the iframe. This userId must be GZIP-compressed, Base64-encoded, and URI-encoded for Dify to recognize it and associate the correct session and history [docs reference].

However, the iframe embed does not currently offer built-in options to reset or clear session state when switching users. Session isolation relies on updating the userId in the iframe URL and ensuring localStorage is cleared or updated accordingly. The script-based embed method allows more granular session control, but the iframe method lacks these options [code reference].

For documentation, it would be helpful to clarify these limitations and recommend that developers explicitly reset the iframe and clear localStorage when switching users to avoid session leakage. There are no recent changes adding session isolation options for iframes, so this is a current architectural limitation.

To reply, just mention @dosu.

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

@dosubot[bot] commented on GitHub (Sep 10, 2025):  Hi @wjt123454321! I'm [Dosu](https://go.dosu.dev/dosubot) and I’m helping the dify-docs team.  Dify's iframe embed manages session state using localStorage, keyed by both appId and userId. To isolate sessions for different users, you should pass a unique, properly encoded userId as a URL parameter (`sys.user_id`) when generating the iframe. This userId must be GZIP-compressed, Base64-encoded, and URI-encoded for Dify to recognize it and associate the correct session and history [[docs reference]](https://github.com/langgenius/dify-docs/issues/422). However, the iframe embed does not currently offer built-in options to reset or clear session state when switching users. Session isolation relies on updating the userId in the iframe URL and ensuring localStorage is cleared or updated accordingly. The script-based embed method allows more granular session control, but the iframe method lacks these options [[code reference]](https://github.com/langgenius/dify/blob/70e4d6be340731ada69ff399c5eb9a5d7abc4615/web/app/components/base/chat/embedded-chatbot/hooks.tsx). For documentation, it would be helpful to clarify these limitations and recommend that developers explicitly reset the iframe and clear localStorage when switching users to avoid session leakage. There are no recent changes adding session isolation options for iframes, so this is a current architectural limitation.  *To reply, just mention [@dosu](https://go.dosu.dev/dosubot).* --- <sup>How did I do? [Good](https://app.dosu.dev/response-feedback/00f5fc13-7a64-4bda-9eb9-af0572728f16?feedback_type=great_response) | [Irrelevant](https://app.dosu.dev/response-feedback/00f5fc13-7a64-4bda-9eb9-af0572728f16?feedback_type=irrelevant_answer) | [Incorrect](https://app.dosu.dev/response-feedback/00f5fc13-7a64-4bda-9eb9-af0572728f16?feedback_type=incorrect_sources) | [Verbose](https://app.dosu.dev/response-feedback/00f5fc13-7a64-4bda-9eb9-af0572728f16?feedback_type=too_verbose) | [Hallucination](https://app.dosu.dev/response-feedback/00f5fc13-7a64-4bda-9eb9-af0572728f16?feedback_type=hallucination) | [Report 🐛](https://app.dosu.dev/response-feedback/00f5fc13-7a64-4bda-9eb9-af0572728f16?feedback_type=bug_report) | [Other](https://app.dosu.dev/response-feedback/00f5fc13-7a64-4bda-9eb9-af0572728f16?feedback_type=other)</sup>  [![Join Discord](https://img.shields.io/badge/join-5865F2?logo=discord&logoColor=white&label=)](https://go.dosu.dev/discord-bot) [![Share on X](https://img.shields.io/badge/X-share-black)](https://twitter.com/intent/tweet?text=%40dosu_ai%20helped%20me%20solve%20this%20issue!&url=https%3A//github.com/langgenius/dify-docs/issues/461)

yindo commented

2026-02-16 05:19:32 -05:00

@wjt123454321 commented on GitHub (Sep 10, 2025):

Thank you for your answer!
But when I use this method, there are 401 errors.
const iframeUrl = computed(() => { const baseUrl = '' const encodedUserId = encode(userId.value) return encodedSid ? ${baseUrl}?sys.user_id=${encodedUserId} : baseUrl })
And frontend port is diffefent from dify port, how can I delete the localstorage by js?
@dosu

@wjt123454321 commented on GitHub (Sep 10, 2025): Thank you for your answer! But when I use this method, there are 401 errors. `const iframeUrl = computed(() => { const baseUrl = '' const encodedUserId = encode(userId.value) return encodedSid ? `${baseUrl}?sys.user_id=${encodedUserId}` : baseUrl })` And frontend port is diffefent from dify port, how can I delete the localstorage by js? @dosu

yindo commented

2026-02-16 05:19:32 -05:00

@dosubot[bot] commented on GitHub (Sep 10, 2025):

The 401 errors are likely due to incorrect encoding of sys.user_id or CORS/auth issues. Dify expects the user ID to be GZIP-compressed, then Base64-encoded, then URI-encoded before adding it to the iframe URL—using just encode() won't work. Here’s a working example using pako:

import pako from 'pako';

function encodeUserId(userId) {
  const utf8 = new TextEncoder().encode(userId);
  const gzipped = pako.gzip(utf8);
  const base64 = btoa(String.fromCharCode(...gzipped));
  return encodeURIComponent(base64);
}

// Usage:
const encodedUserId = encodeUserId(userId.value);
const iframeUrl = `${baseUrl}?sys.user_id=${encodedUserId}`;

Dify will decode this as URI-decode → Base64-decode → GZIP-decompress [source].

For cross-origin localStorage: browsers block direct access from your frontend to the iframe’s localStorage if they’re on different ports/domains. You cannot clear it via JS from the parent. The only workaround is to reload the iframe with a new sys.user_id (which resets the session for that user), or use postMessage if both sides implement a message handler [source].

For 401 errors, double-check:

Your encoding matches the above steps exactly.
CORS settings (WEB_API_CORS_ALLOW_ORIGINS, etc.) allow your frontend’s origin.
API URLs are correct and accessible.
The app’s access mode is PUBLIC, and the user ID is unique per user [source].

If you switch users, reload the iframe with the new encoded user ID to isolate sessions. There’s no built-in way to clear the iframe’s localStorage from outside if cross-origin.

To reply, just mention @dosu.

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

@dosubot[bot] commented on GitHub (Sep 10, 2025):  The 401 errors are likely due to incorrect encoding of `sys.user_id` or CORS/auth issues. Dify expects the user ID to be GZIP-compressed, then Base64-encoded, then URI-encoded before adding it to the iframe URL—using just `encode()` won't work. Here’s a working example using [pako](https://www.npmjs.com/package/pako): ```js import pako from 'pako'; function encodeUserId(userId) { const utf8 = new TextEncoder().encode(userId); const gzipped = pako.gzip(utf8); const base64 = btoa(String.fromCharCode(...gzipped)); return encodeURIComponent(base64); } // Usage: const encodedUserId = encodeUserId(userId.value); const iframeUrl = `${baseUrl}?sys.user_id=${encodedUserId}`; ``` Dify will decode this as URI-decode → Base64-decode → GZIP-decompress [[source]](https://github.com/langgenius/dify/blob/70e4d6be340731ada69ff399c5eb9a5d7abc4615/web/app/components/base/chat/utils.ts). For cross-origin localStorage: browsers block direct access from your frontend to the iframe’s localStorage if they’re on different ports/domains. You cannot clear it via JS from the parent. The only workaround is to reload the iframe with a new `sys.user_id` (which resets the session for that user), or use `postMessage` if both sides implement a message handler [[source]](https://github.com/langgenius/dify/issues/16001#issuecomment-2735346619). For 401 errors, double-check: - Your encoding matches the above steps exactly. - CORS settings (`WEB_API_CORS_ALLOW_ORIGINS`, etc.) allow your frontend’s origin. - API URLs are correct and accessible. - The app’s access mode is PUBLIC, and the user ID is unique per user [[source]](https://github.com/langgenius/dify/issues/23666#issuecomment-3170555013). If you switch users, reload the iframe with the new encoded user ID to isolate sessions. There’s no built-in way to clear the iframe’s localStorage from outside if cross-origin.  *To reply, just mention [@dosu](https://go.dosu.dev/dosubot).* --- <sup>How did I do? [Good](https://app.dosu.dev/response-feedback/86f959a5-0862-4ce1-922e-4bab0df35d1e?feedback_type=great_response) | [Irrelevant](https://app.dosu.dev/response-feedback/86f959a5-0862-4ce1-922e-4bab0df35d1e?feedback_type=irrelevant_answer) | [Incorrect](https://app.dosu.dev/response-feedback/86f959a5-0862-4ce1-922e-4bab0df35d1e?feedback_type=incorrect_sources) | [Verbose](https://app.dosu.dev/response-feedback/86f959a5-0862-4ce1-922e-4bab0df35d1e?feedback_type=too_verbose) | [Hallucination](https://app.dosu.dev/response-feedback/86f959a5-0862-4ce1-922e-4bab0df35d1e?feedback_type=hallucination) | [Report 🐛](https://app.dosu.dev/response-feedback/86f959a5-0862-4ce1-922e-4bab0df35d1e?feedback_type=bug_report) | [Other](https://app.dosu.dev/response-feedback/86f959a5-0862-4ce1-922e-4bab0df35d1e?feedback_type=other)</sup>  [![Join Discord](https://img.shields.io/badge/join-5865F2?logo=discord&logoColor=white&label=)](https://go.dosu.dev/discord-bot) [![Share on X](https://img.shields.io/badge/X-share-black)](https://twitter.com/intent/tweet?text=%40dosu_ai%20helped%20me%20solve%20this%20issue!&url=https%3A//github.com/langgenius/dify-docs/issues/461)

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: langgenius/dify-docs#240