Skip to main content

Embedding to Customers and Partners

Single sign-on (SSO) embedding enables delivering data to users outside of the business, living in other applications. Reporting can be mapped to row level permissions, allowing many users to access identical reports filtered to only their own data.

SSO embedding works by creating an authorized Omni URL that you will use in an iframe. The URL contains the content you want to share, the ID of the user in your system, and the attributes you want that user to have. You'll then sign the URL with a secret key provided by Omni.

Building an Omni Embed SSO URL

Omni embed sso URLs are composed of a few parts. These parts are concatenated into a single string and signed with a unique secret key used only by your organization. The signature is then added to a url with all the parts specified as query parameters in the URL. When an Omni server receives the request in the URL, we will attempt to generate the same signature. If the passed in signature matches the signature generated in our servers, the request is honored.

Generating a secret

Generate a secret by going to the Admin > Embed section of your Omni instance.

Press the “Reset Secret” button to generate your random secret key. Resetting an existing secret key will invalidate the previous one, so be sure to update any scripts with the latest secret.

Generating a signed URL is complex and error prone. It is highly recommended you use an example script to generate embed URLs.

Omni has a supported Typescript SDK and some unsupported examples in other languages. Overtime the supported libraries will expand:

Supported:

Unsupported:

(Hard Mode) Manually Generating a Signature and URL

The following pieces of data are used to generate a signature:

PropertyDescriptionRequired
URLThe URL to your Omni instances embed login route.yes
Content pathThe path to the content you wish to embed.yes
External idAn external id to reference the external user. This should be unique for your external definition of user.yes
NameHuman readable name for the useryes
Nonce32 character (byte) unique stringyes
EntityAn id to reference the entity the user belongs to. Commonly is the customer name or other identifying organization for this userno
User attributesJSON serialized, key value pairs matching defined user attributes in your system.no
Prefers DarkDark mode setting. Can be "true", "false" or "system"no
ThemeVisual theming options. One of "dawn", "vibes", "breeze" or "blank".no
Filter Search ParamEncoded string representing dashboard filter values. This can be derived by copying the substring after the "?" from a dashboard URL with non-empty filter values.no
Link AccessA string that allows you to customize which other Omni dashboards can be linked to from the embedded dashboard. If set to "__omni_link_access_open", all links on the embedded dashboard are permissed and shown. Alternatively, a comma-separated list of dashboard IDs can be passed (i.e. "abcd1234,efgh5678,ijkl9999") to only permiss to specific dashboard IDs. Finally, if the parameter is undefined, all links to other Omni dashboards are restricted. Note that link URLs to anything other than an Omni Dashboard will be shown and permissed regardless of the linkAccess parameter.no

To generate the signature, the follow steps must be followed exactly:

  1. Concatenate the properties, delimited by a newline character in the exact order enumerated below. Note they are in alphabetical order, with the exception of the leading login URL:
  • login URL
  • content path
  • external id
  • name
  • nonce

Next, concatenate the optional properties, again in alphabetical order. Any undefined optional properties must be omitted (no space, no extra newline, etc):

  • entity
  • prefers dark
  • theme
  • user attributes
    • Must be JSON stringified
  • filter search param
    • Must be manually URI encoded unless pulled from Omni dashboard URL (in which case the string is already URI encoded).

There must be no leading or trailing spaces, and only a single newline between each part of the signature. Example:

https://example.embed-omniapp.co/embed/login
/embed/dashboards/123abc
luke@example.com
Luke Skywalker
hN38NgtnV2B3PMILhKQOpwLyJRP4qVv4
Acme Corp
vibes
{"planet": "tatooine"}
f--users.country=%7B"kind"%3A"EQUALS"%2C"type"%3A"string"%2C"values"%3A%5B"USA"%5D%2C"is_negative"%3Afalse%7D&f--users.state=%7B"kind"%3A"EQUALS"%2C"type"%3A"string"%2C"values"%3A%5B%5D%2C"is_negative"%3Afalse%7D&f--inventory_items.cost=%7B"kind"%3A"GREATER_THAN"%2C"type"%3A"number"%2C"values"%3A%5B"20"%5D%2C"is_negative"%3Afalse%2C"is_inclusive"%3Afalse%7D
  1. Sign the string using your secret key (available in your admin portal) with an HMAC sha256 digest algorithm, encoded as a base64url string. See https://datatracker.ietf.org/doc/html/rfc4648#page-7 for more information about base64url. Node.js example:
const hmac = crypto.createHmac("sha256", secret);
hmac.update(data);
return hmac.digest("base64url");

Crafting the URL

To generate the signed url, take the parts from above, URL encode them as part of a URL query string and attach the generated signature.

The URL form usually:

https://<your org name>.embed-omniapp.co/embed/login

Search params are then url encoded and appended. Order of params is irrelevant when generating the login url.

?contentPath=%2Fembed%2Fdashboards%2F123abc
&externalId=luke%40example.com
&name=Luke%20Skywalker
&nonce=hN38NgtnV2B3PMILhKQOpwLyJRP4qVv4
&entity=Acme+Corp
&theme=vibes
&userAttributes=%7B%22planet%22%3A%22tatooine%22%7D
&filterSearchParam=f--order_items.status%3D%257B%22kind%22%253A%22EQUALS%22%252C%22type%22%253A%22string%22%252C%22topic%22%253A%22order_items%22%252C%22values%22%253A%255B%22Returned%22%255D%252C%22base_view%22%253A%22order_items%22%252C%22is_negative%22%253Afalse%257D
&signature=rpf-YbMMTd2XzO_HRyP1E_RiYpQYqBkU-X9iUMplEz4

Note: newlines are not required, they were added to enhance readability.

All together this should look like:

https://example.embed-omniapp.co/embed/login
?contentPath=%2Fembed%2Fdashboards%2F123abc
&externalId=luke%40example.com
&name=Luke%20Skywalker
&nonce=hN38NgtnV2B3PMILhKQOpwLyJRP4qVv4
&entity=Acme+Corp
&theme=vibes
&userAttributes=%7B%22planet%22%3A%22tatooine%22%7D
&filterSearchParam=f--order_items.status%3D%257B%22kind%22%253A%22EQUALS%22%252C%22type%22%253A%22string%22%252C%22topic%22%253A%22order_items%22%252C%22values%22%253A%255B%22Returned%22%255D%252C%22base_view%22%253A%22order_items%22%252C%22is_negative%22%253Afalse%257D
&signature=rpf-YbMMTd2XzO_HRyP1E_RiYpQYqBkU-X9iUMplEz4

Note: newlines are not required, they were added to enhance readability.

Map of Property Names to URL names

PropertyURL variant
Content PathcontentPath
External IdexternalId
Namename
Noncenonce
Prefers DarkprefersDark
Themetheme
Signaturesignature

Viewing Embed Sessions

View ongoing and expired embed sessions by going to the Admin > Embed Sessions section of your Omni instance. Note that expired and deleted sessions will mean the embed url used to create the session will render an error and no longer display content.

To manually delete a session, click on the options button (i.e. the vertical three dots button) to the right of the session to open the options menu. Then press “Delete Session”.

You can also filter sessions based on user name. Simply type a search string in the input above the sessions table.

Safari, Mobile Safari and Mobile iOS Chrome Support

Omni currently uses cookies to manage it's authentication sessions. When embedded in iframes, browsers like Safari view these as third-party cookies. By default, Safari takes a privacy-minded stance on these cookies and blocks them, effectively blocking access to Omni content.

Safari provides a complicated meet-and-greet handshake to enable third-party cookies in supported contexts. This requires explicit action by the user. The steps are:

  1. Attempt to load the Omni dashboard. If cookies are not permitted display, a button that, when clicked, will send the user directly to the Omni instance being embedded.
  2. Once the embedded Omni instance has been visited in a non-embedded context, send the user back to the embedded context.
  3. Present the form again which will now prompt the user to allow access to "use cookies and website data". Clicking "Allow" will then redirect again, and display the embedded dashboard.

This process should only be required the first time a user accesses embedded content in Safari. Occasionally Safari may ask the user to authorize access again, displaying the form the user must click on.

The steps look like the following:

Step 1 - Visit Embed URL, Click "Allow Access"

Step 2 - Visit embedded site directly, click "Back to access page"

Step 3 - Just as in step 1, Click "Allow Access"

Click "Allow"

And you're in!

Current Limitations

  • Session length - At the moment, using a valid embed url will create an embed session that lasts 24 hours. That embed session will be unusable after 24 hours. Visiting a new, valid embed sso url at any time will create a new session.
  • Incognito Chrome - Icognito chrome requires allowing 3rd-party cookies. These can be found under Chrome > Settings... > Privacy and Security > Third-party cookies. Then set the option to Allow third-party cookies.