> ## Documentation Index
> Fetch the complete documentation index at: https://docs.curator.interworks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Embedding Curator in Other Systems

> Allow Curator to be displayed inside an iframe in another website or application, and troubleshoot embeds that fail to load.

Curator can be displayed inside an iframe in another website or application, such as an intranet, a SharePoint
site, or an electronic health record system. By default, Curator blocks this to protect users from
[clickjacking](https://owasp.org/www-community/attacks/Clickjacking). Embedding Curator needs three things to line
up:

1. Curator must allow itself to be framed (the **Allow iframe embedding** setting).
2. Every web server, proxy, load balancer, or firewall in front of Curator must also allow it to be framed.
3. The system that hosts the iframe must allow Curator's domain to be loaded in a frame, and your users' browsers
   must be able to reach Curator.

If any one of these is missing, the iframe shows a blank area or a "refused to connect" message, even when the
others are correct.

<Note>
  This page is about putting Curator **inside** another system. To embed content from another system inside a
  Curator page, see [Manual Embed - (iFrames)](/site_content_design/pages/manual_embed_iframes) instead.
</Note>

## Enabling Iframe Embedding in Curator

1. Navigate to the backend of the system (e.g. `https://curatorexample.com/backend`) and log in if prompted.
2. Navigate to **Settings** > **Curator** > **Portal Settings**.
3. On the **General** tab, scroll to the **Security** section.
4. Enable **Allow iframe embedding** and save.

This setting is off by default. While it is off, Curator sends the header `X-Frame-Options: sameorigin` with every
page, which tells browsers to show Curator in a frame only when the surrounding page is on the same Curator domain.
Turning the setting on stops Curator from sending that header on its frontend pages. It does not add any header that
names which sites may embed Curator; if you want to restrict that, add a `frame-ancestors` policy at your web server
as described below.

The setting also changes how the login session cookie is sent. Over HTTPS, the session cookie is sent as
`SameSite=None; Secure` when this setting is on, and also when the authentication type is Portal, so a user who logs
in inside the iframe stays logged in. Over plain HTTP the cookie cannot be marked this way, and browsers do not send
it inside a frame on another site, so users cannot stay logged in. Serve Curator over HTTPS before embedding it.

<Warning>
  The backend (`/backend`) always sends `X-Frame-Options: sameorigin`, whatever this setting says. Only the
  frontend can be embedded in another system.
</Warning>

Allowing embedding lets any website frame Curator unless you restrict it at the web server. Only enable this if you
need it.

## Web Server, Proxy, Load Balancer, and Firewall Requirements

Curator's setting only controls the headers that Curator itself sends. Web servers (IIS, Apache, Nginx), reverse
proxies, load balancers, and web application firewalls (WAFs) in front of Curator often add their own security
headers, and any of them can still block the embed. Check every layer between users and Curator:

* **Remove or adjust `X-Frame-Options`.** If any layer adds `X-Frame-Options: DENY` or `X-Frame-Options:
  SAMEORIGIN`, the browser refuses to show Curator inside another site. Remove the header from that layer.
  `X-Frame-Options` has no supported way to name another site, so it cannot be used to allow a specific host.
* **Add or adjust `Content-Security-Policy: frame-ancestors`.** This header lists the sites that may frame Curator.
  If a layer already sends `frame-ancestors 'self'` or `frame-ancestors 'none'`, add the embedding host to it. For
  example, to allow Curator to be framed by its own domain and by `https://intranet.example.com`:

  ```text theme={null}
  Content-Security-Policy: frame-ancestors 'self' https://intranet.example.com
  ```

  Using `frame-ancestors` is the recommended way to limit which systems can embed Curator once the
  **Allow iframe embedding** setting is on.

You can check which headers actually reach the browser by opening Curator directly, opening the browser's developer
tools (F12), selecting the page request on the **Network** tab, and reading its **Response Headers**.

If your Curator instance is hosted by InterWorks, contact InterWorks support to review the headers sent by the
hosting environment.

## Embedding System Requirements

The system that contains the iframe can also block it. Many applications send their own `Content-Security-Policy`
header with a `frame-src` (or the older `child-src`) directive that lists which sites may be loaded in frames on its
pages. If that list does not include your Curator domain, the browser blocks the iframe before it contacts Curator.

Ask the administrator of the embedding system to add your Curator address, for example
`https://curatorexample.com`, to its allowed frame sources. Some applications, especially desktop applications with
a built-in browser, keep this list in their own configuration rather than in a web server header.

## Network Requirements

The iframe is loaded by each user's browser, not by the embedding system's server. Every user's device must be able
to reach Curator directly:

* **DNS:** the Curator hostname must resolve on the user's network.
* **VPN and firewalls:** if Curator is only reachable on an internal network or over a VPN, users outside that
  network cannot load the iframe.
* **Certificate trust:** the Curator SSL certificate must be valid for the hostname used in the iframe and trusted
  by the user's device. Browsers do not offer a "proceed anyway" option inside an iframe, so a certificate error
  shows as a blank or failed frame.

A quick check is to open the Curator URL from the iframe directly in a new browser tab on an affected user's device.
If it does not load there, the problem is the network or certificate, not the embedding settings.

## Logging In Within an Iframe

When Curator is embedded on a different site than the one Curator is served from, the browser treats it as a
third-party site, so login depends on the browser allowing third-party cookies. An iframe on the same site as
Curator, such as HTTPS subdomains of the same registrable domain, is generally not third-party and is not affected.
Some browsers, such as Safari, block third-party cookies by default, which can cause users to be asked to log in
again and again. See [Third Party Cookies](/site_administration/user_notifications/third_party_cookies) for how to
warn users about this and how to allow cookies in Safari.

## Troubleshooting

Open the page that contains the iframe, open the browser's developer tools (F12), and reload the page. Look for the
Curator request on the **Network** tab and for messages on the **Console** tab. In the table below, the **Side**
column shows where the fix belongs:

* **Curator**: Curator's **Allow iframe embedding** setting, or the web server, proxy, load balancer, or WAF in
  front of Curator.
* **Embedding system**: the website or application that contains the iframe.
* **Network**: DNS, VPN, firewalls, or certificate trust between the user's device and Curator.

| Message | Side | What to do |
| - | - | - |
| `ERR_BLOCKED_BY_RESPONSE` on the Curator request (Network tab) | Curator | Enable the setting, then check headers |
| `Refused to display '...' in a frame because it set 'X-Frame-Options'` | Curator | Remove `X-Frame-Options` |
| `Refused to frame '...' because an ancestor violates ... frame-ancestors` | Curator | Add host to `frame-ancestors` |
| `Refused to frame '...' because it violates ... frame-src` (or `child-src`) | Embedding system | Allow Curator |
| `ERR_NAME_NOT_RESOLVED` | Network | Fix DNS for the Curator hostname |
| `ERR_CONNECTION_REFUSED`, `ERR_CONNECTION_TIMED_OUT`, other `ERR_CONNECTION_*` | Network | Check VPN, firewalls |
| `ERR_CERT_AUTHORITY_INVALID`, `ERR_CERT_DATE_INVALID`, other `ERR_CERT_*` | Network | Fix the certificate |
| The iframe loads, but keeps showing the login page | Curator | Use HTTPS, allow third-party cookies |

For any other message that says `violates the following Content Security Policy directive`, the directive name shows
the side: `frame-ancestors` is sent by the Curator side, while `frame-src` and `child-src` come from the embedding
system. A certificate error means the Curator SSL certificate is not trusted by the device, does not match the
hostname in the iframe, or has expired. For repeated login prompts, see
[Logging In Within an Iframe](#logging-in-within-an-iframe).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.