Skip to content
Web

Embedding with iframes

Incomplete

Some Web features have not been fully documented and/or are under active development. See Not yet documented.

Show an external website inside a 3forge Enterprise application, or show a 3forge Enterprise application inside another website, using an HTML <iframe>.

Both directions are controlled by 3 Web properties, set in config/local.properties:

  • ami.content.security.policy: the Content-Security-Policy header the Web sends. Controls which external sites an application may frame.
  • ami.allow.same.site: the SameSite attribute on the Web's session cookie. Controls whether a login holds when the application is framed by another site.
  • ami.allow.site.framed: whether other sites may frame the Web at all. Defaults to true.

The Web reads these at startup, so restart after changing any of them.

Show an external site in an application

An HTML Panel can hold an iframe pointing at any site that permits framing.

Prerequisites

  • The external site allows itself to be framed. A site that sends X-Frame-Options or a frame-ancestors directive excluding your 3forge Enterprise address cannot be framed, and no 3forge Enterprise setting changes that.

Steps

  1. Turn on Layout Editor mode with the button at the top right of the menu bar.
  2. Add an HTML Panel to the layout: click a blank Panel's green button and select "Create HTML Panel".
  3. Click the HTML Panel's green button and select "Edit HTML".

  4. Enter the iframe, replacing https://example.com with the site's address, and click "Submit". A width and height of 100% fill the Panel:

    1
    <iframe width="100%" height="100%" src="https://example.com"></iframe>

    To place the iframe beside other fields instead of filling the Panel, use "Add Field/Button/Div" on the same menu to add a Div field, and enter the same HTML in that field's "Edit HTML" dialog.

  5. Add the site's origin to a frame-src directive in ami.content.security.policy. Setting the property replaces the whole default policy, so copy the default and add frame-src to it:

    1
2
    # Default policy, with frame-src added for the framed site
ami.content.security.policy=frame-src https://example.com; img-src 'self' https://*.mapbox.com data: w3.org/svg/2000; default-src https://*.mapbox.com 'self' 'unsafe-inline' 'unsafe-eval' blob:;font-src 'self' data:

    List several origins separated by spaces. A wildcard covers subdomains: https://*.example.com.

  6. Restart 3forge Enterprise.

Result

The external site loads inside the Panel. Until step 5 is done, the Panel shows "This content is blocked. Contact the site owner to fix the issue."

Show an application in another website

Another website can frame a saved layout by its URL.

Prerequisites

  • The layout is saved. "Info" in the "File" menu is unavailable until it is.

Steps

  1. Add the following line to config/local.properties:

    1
2
    # Send the session cookie as SameSite=None; Secure, so it is kept inside a cross-site frame
ami.allow.same.site=None

  2. Restart 3forge Enterprise.

  3. Open the layout and select File -> Info. Copy the value shown for "URL". It has the form https://<host>:33333/3forge?LAYOUT=CLOUD_<layout name>.ami.

  4. Add an iframe to the other website's page, using the copied URL as src:

    1
    <iframe src="https://your-3forge-host:33333/3forge?LAYOUT=CLOUD_my_layout.ami" title="3forge Enterprise"></iframe>

Result

The login page appears inside the frame, and after logging in the layout opens. Without step 1, logging in inside the frame returns to the login page.

HTTPS is required

ami.allow.same.site=None marks the session cookie SameSite=None; Secure, and browsers keep a Secure cookie only over HTTPS. 3forge Enterprise serves the Web over HTTPS on port 33333 by default, and requests to the HTTP port 33332 are redirected there. If the default listeners have been changed, keep HTTPS enabled: on a Web served over plain HTTP, the setting stops every browser login from holding, framed or not, unless the Web is opened as localhost.

Hide the menu bar

A framed application often has no need for the full menu bar.

  1. Turn on Layout Editor mode. The "Dashboard" menu appears only in this mode.
  2. Open Dashboard -> Dashboard Settings....
  3. Set "Menubar Position" to any option other than "Top Full" or "Bottom Full", and click "Submit".

The menu bar collapses to the 3forge logo and a menu button in the chosen corner. Clicking the button shows the full menu bar.

Frame a single Tab

The URL opens a whole layout. To frame only the content of one Tab, move that content into its own layout, save it, and frame that layout's URL.

Troubleshooting

The Panel shows "This content is blocked"

The framed site's origin is missing from the frame-src directive of ami.content.security.policy. Add it, including the scheme, and restart.

An external site's frame shows only a broken-page icon

The external site forbids framing through X-Frame-Options or its own frame-ancestors policy. The site's owner has to allow it.

3forge Enterprise shows only a broken-page icon inside another site

ami.allow.site.framed is set to false. The Web then sends X-Frame-Options: DENY, and browsers refuse to frame it. Remove the line or set it to true, and restart.

The frame returns to the login page after logging in

The session cookie is not being kept in the cross-site frame. Check that ami.allow.same.site=None is set and that the framed address uses HTTPS.