Embedding Dashboards

Squirro dashboards can be embedded into other web applications or even desktop software. The basis for this is iFrame technology.

How to Embed Using iFrames

To embed a dashboard into a third-party application, select the dashboard within the user interface. On the right-hand side, open the menu and select Embed iFrame or Share. The only difference between the two commands is that Embed iFrame generates the full HTML code for an iFrame, while Share simply returns a URL to use.

That URL can be used for embedding, or it can simply be shared in chat apps, email, etc.

If you select the Automatically login into this account checkbox, a token is generated and appended to the dashboard URL. With this token, anybody can access the dashboard impersonating the current user in read-only mode.

Parameters

The URL generated by the user interface always embeds the dashboard in its saved state. This means that any dashboard query and time limits configured in the dashboard are applied. These can be overwritten with URL parameters.

For example, the user interface may have returned the following URL:

https://squirro.example.com/app/dashboard/OuKRZuhmTXCA0mAfwSVm2g/hMcTiqacTIa0mXYvVh5N9Q

To extend this URL and pass in a custom query, use the query parameter as follows:

https://squirro.example.com/app/dashboard/OuKRZuhmTXCA0mAfwSVm2g/hMcTiqacTIa0mXYvVh5N9Q?query=test

Further parameters are added, separated by an ampersand. An example with a query and a token:

https://squirro.example.com/app/dashboard/OuKRZuhmTXCA0mAfwSVm2g/hMcTiqacTIa0mXYvVh5N9Q?query=test&token=abc

Parameter Reference

All URL parameters are processed by the dashboard state system, which converts them into interactive selection chips that appear in the search interface. These selections can be removed or modified by users through the UI.

Reference: For detailed information about how URL parameters are converted to dashboard selections, see the Dashboard Editor page (Dashboard URL API Reference section).

Parameter	Documentation
token	Token for authentication. The token generated with that checkbox only grants the privileges needed to visit dashboards.
query	Items visualized in the dashboard are limited to the ones returned by this query. For query syntax details, see the Query Syntax page.
relative_start	Only return items that were created after this date and time. Uses the relative date and time format. Relative time is a number followed by a unit, for example 1w for 1 week (ago).\ Valid units are: Unit Description y Years M Months w Weeks d Days h Hours m Minutes s Seconds
created_after	Only return items that were created after this date and time. Uses the standard date and time format.
relative_end	Only return items that were created after this date and time. Uses the relative date and time format (see the relative_start parameter for more details).
created_before	Only return items that were created before this date and time. Uses the standard date and time format.
query_params	Query parameters injected into all API requests from the dashboard as template_params. This is a JSON-encoded dictionary of key/value pairs that can be used for query transformation in the Jinja template.
chatter_token	A Salesforce.com access token. If the Share on Chatter feature is turned on and this option is set, the Share on Chatter option is displayed in the horizontal result list.
chatter_url	A Salesforce.com instance URL used for the share on Chatter function.

Sandboxing

If the iframe is used with the sandbox attribute, modal dialogs and JavaScript are blocked. Learn more

Set the sandbox attribute to allow-scripts allow-modals to avoid this.

Chat Widget Considerations

When a dashboard containing the Chat widget is embedded in an external website, some agent types require access to Squirro-internal endpoints that are not available in that context. Requests to those endpoints will fail, and users may see error messages in the embedded widget.

To avoid this, turn off the following agents before embedding a dashboard with the Chat widget:

• Collection agent

  Collection agents query the Collections endpoint to scope the conversation to a specific document collection. That endpoint is not accessible from external websites, which causes errors in the embedded widget.

• Favorite Filter agent

  Favorite Filter agents query the Favorite Filters widget endpoint to narrow the conversation to a saved search. That endpoint is not accessible from external websites, which causes errors in the embedded widget.

Cross-Origin Embedding

When the parent website and the Squirro instance are served from different origins, the default configuration prevents the form-login flow from completing inside an iframe. Browsers apply SameSite=Lax to the Flask session cookie by default. The browser strips that cookie on the cross-site redirect that follows a successful login, causing the iframe to loop back to the login form indefinitely.

Two configuration changes resolve this: setting SameSite=None; Secure on the session cookie, and adding a Content-Security-Policy: frame-ancestors response header that explicitly permits the parent origin to embed Squirro. No code changes or new container images are required.

Prerequisites

Confirm the following before applying the fix:

• Both the Squirro instance and the parent website are served over HTTPS. Browsers reject SameSite=None on insecure connections.

• You know the parent origin, for example https://yourcompany.example.com.

• You have access to the Squirro instance UI and shell access to the server to edit configuration files.

Configuration Steps

Step 1: set the CSP frame-ancestors directive

In the Squirro instance UI, navigate to the Server space, open Configuration, and search for security.content-security-policy. Add the frame-ancestors directive to the existing value. For example, if the current value is:

style-src 'self' 'unsafe-inline'; worker-src blob:; img-src 'self' data: blob:; script-src 'self' 'wasm-unsafe-eval';

Append the frame-ancestors directive to produce:

style-src 'self' 'unsafe-inline'; worker-src blob:; img-src 'self' data: blob:; script-src 'self' 'wasm-unsafe-eval'; frame-ancestors https://yourcompany.example.com;

Replace https://yourcompany.example.com with your actual parent origin. To allow multiple parent origins, use a space-separated list:

frame-ancestors https://a.example https://b.example;

Warning

Do not use frame-ancestors * in production environments. That value allows any website to embed your Squirro instance in an iframe.

For full details on configuring the CSP header, see the Content Security Policy (CSP) section of the Secure Configuration Guide page.

Step 2: update the session cookie settings

On the Squirro server, open /etc/squirro/frontend.ini and add the following two lines under the [flask_app] section:

[flask_app]
session_cookie_secure = true
session_cookie_samesite = None

For the full frontend.ini reference, see the frontend.ini page.

Step 3: restart the frontend service

sudo systemctl restart sqfrontendd

Step 4: verify

Confirm that the session cookie and CSP header are both present in the response:

curl -sk -I https://localhost/ | grep -iE 'set-cookie|content-security'

Expected output:

set-cookie: session=...; Secure; HttpOnly; Path=/; SameSite=None
content-security-policy: frame-ancestors https://yourcompany.example.com;

Limitations

• SSO deployments

  This fix addresses the Squirro session cookie only. For SSO deployments (SAML, OIDC with Okta, Azure AD, Keycloak, and similar providers), the login flow redirects the browser to the identity provider. Most identity providers set X-Frame-Options: DENY on their login pages to prevent clickjacking, which blocks the login form from loading inside an iframe.

  Two alternative authentication options are available in the Embed iFrame dialog for those deployments:

  • Automatically login into this account — generates a read-only token appended to the embed URL. Anyone with the URL can view the dashboard without logging in.

  • Use Parent Window Authentication (for iframe embedding) — the parent application passes a Squirro token to the iframe via the browser postMessage API. Use this option when the parent application already holds a valid Squirro session token and can deliver it to the embedded frame on demand.

• Safari Intelligent Tracking Prevention

  Safari may block third-party cookies on a user’s first visit even with SameSite=None; Secure set. Ask the user to open the Squirro instance URL directly in a browser tab once to establish a first-party context. Subsequent iframe loads in that browser then inherit the cookie state.

Troubleshooting

Automatic Logout

When embedding a dashboard integration with a token (automatic login) the user may be automatically logged out from the system when they access Squirro standalone the next time. This is because the read-only token only grants access to the dashboard, but not to the standalone application.

To prevent this from happening, you can point a second domain name to the Squirro application and use that domain for integrations. That approach avoids clashes between the embedded iFrames and the standalone application usage.