Security and embedding

These environment variables shape DIAL Chat's Content Security Policy (CSP): which origins can embed Chat, which ones Chat can embed or connect to, and which custom visualizers and MCP Apps it renders. Each origin you allow widens what runs next to the user's session, so list only origins you trust. This reference is for platform engineers who harden or integrate Chat; it assumes you know how DIAL Chat is configured.

Content Security Policy

Variable	Default	Description
CSP_MODE	report-only	report-only keeps the current enforced policy, which still allows inline CSS, and reports a stricter candidate policy. enforce blocks inline styles, inline JavaScript, inline event handlers, and eval().
CSP_REPORT_URI	—	The HTTPS URL of your CSP reporting service. It turns on both report-uri and the Reporting API. Chat hosts no report collector.
ALLOWED_CONNECT_ORIGINS	[]	Comma-separated trusted origins added to CSP connect-src, for previews of PDF and Office documents hosted elsewhere. A leading *. matches subdomains.

Roll out in two steps: deploy with report-only, exercise sign-in, chat, files, every document preview, themes, and embedding, review the violations, then switch to enforce. Returning to report-only restores the inline CSS allowance.

In enforce mode, a frontend build without the CSP nonce marker is rejected at startup. Reverse proxies must keep the CSP headers and must not cache or rewrite the HTML, which carries a fresh nonce on every response.

Document previews from other origins

PDF and Office previews fetch the document from the browser. For a document on another origin:

1. List the document server's origin in ALLOWED_CONNECT_ORIGINS.
2. On the document server, allow the Chat origin through CORS: Access-Control-Allow-Origin with the exact origin, and Access-Control-Allow-Credentials: true. A wildcard origin does not work, because PDFs from a listed origin are fetched with browser cookies.
3. Serve the document directly; these requests reject redirects.
4. Restart chat-api, and reload Chat or the overlay iframe.

Iframe origins

ALLOWED_IFRAME_ORIGINS is a comma-separated list of origins that can frame Chat and that Chat can frame. It feeds both CSP frame-ancestors and frame-src.

• Each entry is an origin only, scheme://host[:port], with https://, or http:// for local development.
• A single leading *. label allows a subdomain family: https://*.example.com matches https://portal.example.com but not https://example.com.
• It is required for the Chat Overlay, for iframe integrations such as Quick Apps editors, and for the origin of every visualizer below.

Because one list serves both directions, adding a visualizer's origin also lets that origin embed Chat.

Visualizers

A visualizer is an iframe app that renders attachments of a given MIME type inside Chat. List each visualizer's origin in ALLOWED_IFRAME_ORIGINS too, or the browser blocks it.

Variable	Default	Description
CUSTOM_VISUALIZERS	[]	A JSON array of MIME type to visualizer mappings, opened in the attachment canvas. See below.
APPLICATION_VISUALIZERS	{}	A JSON object keyed by application ID. Every attachment an entry claims is delivered to one iframe, rendered inline in the message. An entry wins over CUSTOM_VISUALIZERS for the attachments it claims.
ALLOW_VISUALIZER_SEND_MESSAGES	false	When true, a visualizer can post SEND_MESSAGE, and its text is sent as a user message. Only true, 1, and yes turn it on.

CUSTOM_VISUALIZERS='[{"title":"my-viz","url":"https://viz.example.com","contentType":"application/x-my-viz,application/x-my-viz-v2"}]'
APPLICATION_VISUALIZERS='{"my-app":{"title":"my-viz","url":"https://viz.example.com","contentType":"application/x-my-viz","height":600,"mobileHeight":400}}'

• title is the message namespace and must equal the appName the visualizer passes to ChatVisualizerConnector; a mismatch loads the iframe but never sends it data.
• In APPLICATION_VISUALIZERS, contentType is optional; without it, the entry claims every attachment that has a URL. borderless and withoutTitle are JSON booleans that drop the frame's border or its header title.
• A registered visualizer gets iframe privileges in Chat, such as downloads, popups, and clipboard access. Invalid entries are dropped and logged; Chat still starts.

warning

With ALLOW_VISUALIZER_SEND_MESSAGES on, a visualizer can send messages as the user. Turn it on only for visualizers you trust.

To build a visualizer, see Create a custom visualizer.

MCP Apps

MCP Apps render inside a sandbox proxy, deployed separately from Chat on its own origin with the epam/ai-dial-chat-mcp-app-sandbox image.

Variable	When unset	Description
MCP_APP_SANDBOX_URL	MCP Apps cannot open	The base URL of the sandbox proxy.
MCP_APP_THEME	The active Chat theme	light or dark, passed to MCP Apps as the host theme.
MCP_APP_USER_AGENT	The browser's user agent	The identifier passed to MCP Apps as the host user agent.
MCP_APP_HOST_NAME	ai-dial-chat	The host name passed to MCP Apps during initialization.

The sandbox's own embedding allowlist is MCP_APP_SANDBOX_ALLOWED_HOST_ORIGINS, set on the sandbox deployment. See the sandbox deployment guide.

Further reading

• Chat Overlay — embed Chat in another application
• DIAL Chat configuration: Authentication — cookie and session security
• Security hardening — the production checklist
• Create a custom visualizer — build a visualizer that renders custom content in DIAL Chat