Skip to main content
In this guide, we’ll walk you through setting up standard SSO for Omni embed. As the simplest way to embed Omni, this involves generating and using a single URL to create an embed user session.

​
Requirements

To follow the steps in this guide, you’ll need:
  • Organization Admin permissions
  • To have the Embed feature enabled in your Omni instance

​
Setup

1

Generate an embed secret

The first step is to generate an embed secret:
  1. Navigate to Settings > Embed > Admin in your Omni instance:
  2. Click 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.
2

Optional: Customize session length

In the Embed settings of your Omni instance, you can also customize the length of embed sessions using the Session Length setting. In this field, enter the number of hours you want sessions to be and click Change.
3

Generate an embed URL

Because embed URLs are signed using your Omni organization’s embed secret, it is crucial that your embed URLs are generated server-side rather than client-side. From a security perspective, this protects your embed secret from being exposed to attackers.Also note that the Omni Typescript SDK utilizes Node’s crypto module, which is only available in Node environments. Attempting to use the Omni Typescript SDK functions in a client-side context will likely lead to the SDK functions generating improperly signed embed URLs.
Omni embed URLs are composed of a few parts. These parts, used to customize the resulting embed user or session, are concatenated into a 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, it will attempt to generate the same signature. If the passed in signature matches the signature generated in Omni’s servers, the request is honored.There are three ways to generate standard signed embed URLs in Omni:
While the Typescript SDK is the preferred method for generating signed URLs, you may not be able to leverage it if your backend isn’t running a JavaScript runtime. For other languages and environments, Omni offers a stateless API as an escape hatch:
https://<YOUR OMNI HOSTNAME>/embed/sso/generate-url
The /embed/sso/generate-url endpoint only accepts POST requests. For POST operations, parameters are passed as a JSON object in the request body.This endpoint returns a signed URL for an embedded piece of content. Additionally:
  • The endpoint does not accept a signature param, as that is what’s being generated
  • The endpoint requires a secret parameter in the request body. The value should be the Embed secret you created in step 1.
  • The nonce param is optional. If not included, one will be automatically generated.
  • JSON encoded parameter values (userAttributes, connectionRoles) should be URL encoded. Refer to the Embed parameters reference for a complete list of available parameters.
POST /embed/sso/generate-url
curl -X POST https://blobsrus.omniapp.co/embed/sso/generate-url \
-d '{
  contentPath: '/dashboards/12345678',
  externalId: 'abcd1234',
  name: 'foo',
  secret: '12345678901234567890123456789012',
  userAttributes: '%7B%22shop_id%22%3A%22123%22%7D',
}'
The steps outlined in this section must be followed exactly to be successful.
To generate the signature:
  1. Concatenate the required properties, delimited by a newline character in the exact order enumerated below. Note: The properties are in alphabetical order, with the exception of the leading login URL: 
    login URL
contentPath
externalId
name
nonce
  2. Concatenate the optional properties in alphabetical order, delimited by a newline character in the exact order enumerated below: 
    accessBoost
connectionRoles
customTheme
customThemeId
email
entity
entityFolderContentRole
filterSearchParam          // must be URI encoded
groups
linkAccess
mode
prefersDark
theme
userAttributes
entityFolderGroupContentRole
uiSettings
    Do not include leading or trailing spaces. Include only a single newline between each part of the signature. The following example includes optional parameters for custom theme, entity, filter search param, prefers dark, link access, theme, and user attributes: 
    https://example.embed-omniapp.co/embed/login/embed/dashboards/123abcluke@example.comLuke SkywalkerhN38NgtnV2B3PMILhKQOpwLyJRP4qVv4{"dashboard-background":"#00FF00","dashboard-tile-title-font-size":"1.5rem"}Acme Corpf--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%7Dtrue__omni_link_access_openvibes{"planet": "tatooine"}
    Refer to the Embed parameters reference for more information about available parameters.
  3. Sign the string using your secret key with an HMAC sha256 digest algorithm, encoded as a base64url string:
Node.js example
const hmac = crypto.createHmac("sha256", secret);hmac.update(data);return hmac.digest("base64url");
Refer to the Base64 spec for more information about base64url.
4

Generate a signed embed 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 typical URL form:
https://<your-org-name>.embed-omniapp.co/embed/login
Search params are then URL encoded and appended. The order of parameters is irrelevant when generating the login URL.By now, the URL should look something like the following:
https://blobsrus.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&linkAccess=__omni_link_access_open&prefersDark=true&customTheme=%7B%22dashboard-background%22%3A%22%2300FF00%22%2C%22dashboard-tile-title-font-size%22%3A%221.5rem%22%7D&signature=rpf-YbMMTd2XzO_HRyP1E_RiYpQYqBkU-X9iUMplEz4
5

Optional: Test the URL with the Embed URL Builder

While primarily intended for internal embedding - such as embedding Omni in Notion - , you can use Omni’s embed URL builder to test the format of your URL parameters.
  1. First, you’ll need your content’s unique ID:
    You can find the dashboard ID by:
    • Opening the document settings. Navigate to File > Document settings in the dashboard and then click Settings. The Identifier field contains the dashboard ID.
    • Using the dashboard’s URL. The string after /dashboards is the dashboard’s ID; for example: 
      https://blobsrus.omniapp.co/dashboards/12db1a0a
    • If the workbook is attached to a dashboard, its content ID is the same as the dashboard
    • If the workbook doesn’t have a dashboard, you can find the ID by navigating to File > Document settings, then clicking Settings. The Identifier field contains the document ID. Note: Embedding a workbook creates a copy of the workbook for that embed user so their changes are not reflected back into the application’s production version of the workbook.
  2. Navigate to Admin > Embed > URL Builder tab.
  3. Fill in the required fields, noted below:
    • Content Path
      • For dashboards: /dashboards/<content_id>
      • For workbooks: /w/<content_id>
    • External ID - Any alphanumeric value
    • Name - Any alphanumeric value
  4. Generate your URL and embed!