An IFRAME is a way of embedding a browser page within another browser page as a near-seamless part of the enclosing page, and has been around for a long time, but of late has been misused as an attack vector and subsequently now has strict restrictions in modern browsers.

This article discusses how to embed Omniscope in another webapp / website using an IFRAME, and the issues and limitations surrounding that.

How to

Typically you would embed an Omniscope report containing a specially designed dashboard as an IFRAME within another site or app. It may be possible to embed an Omniscope workflow in an IFRAME, but this is not expected or supported.

We'll assume you already have Omniscope configured as an external web server, and licensed as needed for your use case. This is not covered by this article. (A user consuming Omniscope in an IFRAME is no different from a user consuming Omniscope as a top-level page in the browser, from a licensing perspective.)

The server must be configured to allow the report being embedded as an IFRAME by ticking 

Admin > Settings > Allow render in any <iframe>

Your report should be shared externally, typically read-only:

You should then design your report for the fixed size you will be embedding it at, e.g. 800x600 pixels:

Copy the HTML <iframe> snippet also shown above, and paste into the enclosing website's HTML source (for example in Wordpress, click Plus and choose "Custom HTML"). Edit before saving to set the desired width and height. 

Here's an example of the result:

However, the deployment may be restricted for security reasons. The page may not load, behave correctly, allow you to login, or allow the correct number of concurrent viewers for your Omniscope license. You may need to change your Omniscope server deployment configuration to use the same domain name as the enclosing page (typically with a different sub-domain). Read on for details and your options.

Optional: in some cases you may wish to remove the report's toolbar, containing the breadcrumbs and other settings. You can achieve this by embedding the iframe with  &tab=tabName  in the URL.

Restrictions

"Same Origin"

By default, Omniscope only allows embedding as an IFRAME within the same origin. The origin is everything in the URL from http(s):// up to the next slash - e.g. for https://omniscope.me/some/folder/SomeProject.iox/r/SomeReport/ the origin is "https://omniscope.me/". 

Almost always, the top level site will have a different origin from Omniscope, unless using some complex reverse proxy to make Omniscope and the enclosing website both appear to be the same origin. Therefore you must tick "Allow render in any <iframe>" as documented above, which will allow embedding in a different origin.

"Same Site"

Often you will be embedding Omniscope within a different "site". Unlike "origin", "site" is more flexible, and refers to the registered domain. For example, these all have the same registered domain something.com:

• https://something.com/abc
• https://mainapp.something.com/
• http://www.something.com/pqr/xyz

When an IFRAME contains an app from a different site to the top-level site shown in the browser address bar, it is called a 3rd-party app, which places restrictions on the app and its ability to use cookies. In Omniscope, some publishing scenarios require the use of cookies to function correctly. For example, when using the "Unlimited viewers" server license add-on (as opposed to a fully unlimited enterprise license), or when using single-sign-on via OpenID Connect. 

Requirements for "3rd party" embedding

In "not same-site" i.e. "3rd party" situations, and when Omniscope requires cookies to operate (as above), all of the following conditions must hold for Omniscope to work correctly as an IFRAME:

• The visiting user must have a browser that permits 3rd-party cookies. Note that some browsers do not permit 3rd party cookies by default. Google Chrome is planning on blocking 3rd-party cookies by default from 2023. 
• Omniscope must be accessed securely via https(not http) with a valid certificate. Non-same-site cookies are only permitted by modern browsers in a secure context.
• Omniscope must be version 2022.1 "rock" or later. 3rd party support was not present before this time.
• The option "Allow render in any <iframe>" must also be ticked (as above).

Regardless, a non-same-site embedding is time-limited. Beyond 2023 it will be unworkable for typical audiences, and is already for some. 

Alternatives

So, to successfully embed Omniscope as an IFRAME, either:

• 3rd-party's ok, if you don't depend on cookies. Omniscope must be licensed with unlimited users (not just viewers), and the embedded report must be publicly accessible (no login required). This scenario tolerates 3rd-party embedding without needing cookies to work in Omniscope 2022.1.
• Or, host as same-site. you should configure your deployment such that Omniscope is indeed a "same site" as the top-level app, typically using a different sub-domain. For example, if the top-level app was "https://acme.co.uk" or "https://corporate.acme.co.uk", the Omniscope server might be "https://omniscope.acme.co.uk", which would be seen as the "same site" by the browser, and would remove the above restrictions. The option "Allow render in any <iframe>" must still be configured, however.