Embedding infrastructure setup

Omni is where the permissions are defined and content is managed and created; however, the application where the content is embedded should dynamically map the user to the right underlying data by generating a script. Make sure your data security is set up correctly in Omni before you start.

There are two options for external embedding:

Standard SSO embed: Generate and use a single URL to create an embed user and session. This is the simplest way to embed Omni for your external users.
2-step SSO embed: First, send a POST request to generate the embed user and session. Then, generate and use a URL to authenticate into the session. This requires more setup, but has a few advantages over the Standard SSO Embed experience.

Understanding the embed URL

Omni embed 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.

Embed parameters

The parameters below can be included in embed requests to customize the resulting embed user or session. Note that these parameters are included as URL parameters on a valid embed request. Refer to the the Example URL Parameter column for an example.

Parameter	URL Parameter	Required	Description	Example Input(s)	Example URL Parameter
Content Path	contentPath	✅	Define the starting page when the embed user logs into the iframe.	`/dashboards/<dashboard-id>` (Dashboard), `/w/<dashboard-id>/duplicate` (Workbook), `/my` (My Content Page), `/entity-folder` (Entity Folder), `/root` (Hub)	contentPath=%2Fdashboards%2Fa6908f35
External ID	externalId	✅	Required parameter creating a unique ID. This can be any alphanumeric value.	`sugar`, `&spice123` or `123+EveryThingNice`	externalId=ohtani17
Name	name	✅	Required parameter and can contain a non-unique name for the embed user's name property.	`Bubbles Power`, `Buttercup Puff` or `Blossom Girls`	name=Shohei+Ohtani
Nonce	nonce	✅	Required 32-character string. Must be unique for each embed login url or else the session will fail to load. If using the sdk or `/embed/sso/generate-url` endpoint, nonce will be automatically added to your generated urls if one is not provided.	`abcdefghijklmnopqrstuvwxyz123456`	nonce=abcdefghijklmnopqrstuvwxyz123456
Access Boost	accessBoost	❌	Boolean setting to enable Access Boost for the embedded dashboard.	true or false	accessBoost=true
Connection Roles	connectionRoles	❌	Strongly recommended. Defines the connection roles available for embed users. Restricted queriers can create new content, Viewers can only consume dashboards	`{"connection-id-1":"RESTRICTED_QUERIER", "connection-id-2":"VIEWER"}`	connectionRoles=%7B%2265b10d2a-473b-4486-92c8-0ba628c7d1cb%22%3A%22RESTRICTED_QUERIER%22%7D
Custom Theme	customTheme	❌	Allows you to stylize embedded dashboards based on JSON blob composed of custom theme properties.	Custom theme example	customTheme=%7B%22dashboard-background%22%3A%22blue%22%7D
Custom Theme ID	customThemeId	❌	Allows you to stylize embedded dashboards based on a predefined theme ID from your Omni instance	abcdefgh-ijkl-mnop-qrst-123456789123	customThemeId=abcdefgh-ijkl-mnop-qrst-123456789123
Embed Entity	entity	❌	User group identifier used to associate the resulting embed user with a larger group. This will also create the shared entity folder using whatever name is set in the value	Any alphanumeric value	entity=Dodgers
Entity Folder Content Role	entityFolderContentRole	❌	Specifies the content role the embed user will be given to their shared entity folder Viewer - can see content in shared folder, can’t save to it Editor - can see and save content in the shared folder Manager - can control other users’ permissions to the shared folder	VIEWER, EDITOR, or MANAGER	entityFolderContentRole=EDITOR
Email	email	❌	Will populate the emails from the users in the entity for sharing and deliveries	myemail@emaildomain.co	email=shoheiohtani17%40dodgersforever.com
Filter Search Param	filterSearchParam	❌	Specify which filters to apply for this embedded content.	`f--order_items.status=closed`	filterSearchParam=f--order_items.status%3D%257B%22values%22%253A%255B%22Complete%22%255D%252C%22appliedLabels%22%253A%257B%257D%257D
Groups	groups	❌	An array of group names that allows you to associate the resulting embed user with existing groups on your Omni instance.	["Blah 1"]	groups=%5B%22Blah+1%22%5D
Link Access	linkAccess	❌	Allows you to customize which other Omni dashboards can be linked to from the embedded dashboard.	Input `__omni_link_access_open` for all links on the embedded dashboard to be permissed and shown; input a list of dashboard IDs: `abcd1234,efgh5678,ijkl9999` to only permit those specific dashboard IDs to be shown; leave the parameter blank for all links to other Omni dashboards links to be restricted; Note that links to anything other than an Omni Dashboard will be shown and permissed regardless of the values specified in the `linkAccess` parameter.	linkAccess=__omni_link_access_open
Mode	mode	❌	Application - allows embed users to access the full content system and navigate through the Omni app in an iframe Single content - only embeds an individual dashboard or workbook. No content navigation or app headers	APPLICATION or SINGLE_CONTENT	mode=APPLICATION
Prefers Dark	prefersDark	❌	Allows you to control whether the resulting embed session has a dark mode or light mode appearance	true, false, system	prefersDark=false
Built-in Theme	theme	❌	Allows you to style the resulting embed session with a built-in Omni application	vibes, dawn, breeze, blank	theme=vibes
User Attributes	userAttributes	❌	Reference which user attributes you want applied to this particular embed user.	`{"country":"Townsville", "associated_ids":[9,10,11]}`	userAttributes=%7B%22country%22%3A%22Townsville%22%2C%22associated_ids%22%3A%5B9%2C10%2C11%5D%7D

Option 1: Standard SSO embed

There are three ways to generate standard signed embed URLs in Omni:

Typescript SDK for Typescript and JavaScript server implementations (Node, Deno, Bun, etc)
API endpoint
Writing your own script to generate the signed embed URL

Step 1: Generate a signed embed URL

SDK (Recommended)

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

Supported:

Typescript

Unsupported:

Ruby

API (Second best)

While the Typescript SDK is the preferred method for generating signed URLs, you may not be able to leverage it if your backend is not running a Javascript runtime. For other languages and environments we offer a simple 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.

Returns a signed URL for an embedded piece of content.

Additional properties accepted or required

Property	Post Body Param	Description	Required
secret	secret	Your embed secret, obtainable from the Admin > Embed section of omni	✔️

Requirements & comments:

The endpoint does not accept a signature param, since that is what it is generating
The endpoint requires a secret param (the one in your admin > embed panel)
The nonce param is optional. If not included, we'll generate one for you
JSON encoded parameter values (userAttributes, connectionRoles) should be URL encoded

POST https://example.omniapp.co/embed/sso/generate-url

{
  contentPath: '/dashboards/12345678',
  externalId: '12345678',
  name: 'foo',
  secret: '12345678901234567890123456789012',
  userAttributes: '%7B%22shop_id%22%3A%22123%22%7D',
}

Manually generate a signature & URL (Hard mode)

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

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):
- access boost
- connection roles
- custom theme
- custom theme id
- email
- entity
- entity folder content role
- filter search param
  - Must be URI encoded unless pulled from Omni dashboard URL (in which case the string is already URI encoded).
- groups
- link access
- mode
- prefers dark
- theme
- user attributes
There must be no leading or trailing spaces, and only a single newline between each part of the signature. Example below that includes optional parameters custom theme, entity, filter search param, prefers dark, link access, theme, and user attributes:
```
https://example.embed-omniapp.co/embed/login
/embed/dashboards/123abc
luke@example.com
Luke Skywalker
hN38NgtnV2B3PMILhKQOpwLyJRP4qVv4
{"dashboard-background":"#00FF00","dashboard-tile-title-font-size":"1.5rem"}
Acme Corp
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
true
__omni_link_access_open
vibes
{"planet": "tatooine"}
```
Sign the string using your secret key (available in the Admin > Embed section) 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");
```

Step 2: Craft 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 typical URL form:

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
&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

Note: Newlines are not required. In this example, they were added to enhance readability.

By now, 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
&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

Note: Newlines are not required. In this example, they were added to enhance readability.

Test your URL with the embed URL builder

To test and make sure the format of parameters you're passing through as you expect you can use the url builder (intended for internal embedding predominantly).

First, you'll need your content's unique ID:
- Dashboards: 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://myorg.omniapp.co/dashboards/12db1a0a
- Workbooks: The workbook content ID is the same as the dashboard ID if the workbook is tied to a dashboard. If the workbook is only saved as a workbook, 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.
Navigate to Admin > Embed > URL Builder tab.
Fill in the required fields, noted below:
- Content Path
  - Dashboards: /dashboards/ID_value
  - Workbooks: /w/ID_value
- External ID - Any alphanumeric value
- Name - Any alphanumeric value
Generate your URL and embed!

Option 2: 2-step SSO Embed

An alternative approach to the standard SSO embed experience is the 2-step SSO embed login flow. Rather performing an SSO embed login via a single login URL, the 2-step login flow divides the process into 2 steps:

Generate an SSO embed user and session via POST request, returning a session token to be redeemed at a later time.
Redeem the generated session token and redirect to the specified content via a login URL.

Advantages

While the standard SSO embed experience is more straightforward, there a few reasons you might opt to use the 2-step SSO embed login flow over standard login URLs:

Sensitive user data: If using the userAttributes parameter with sensitive user data, you may prefer creating SSO embed users and sessions via POST request for added security.
URL length: While generally unlikely, there is more risk of standard SSO embed URLs exceeding a browser's URL character limit. 2-step login URLs are more compact and thus have no risk of hitting the limit.

Setup

Step 1: Generate the user and session

The first step of the 2-step SSO login flow is to generate the SSO embed user and session. This is done by sending a POST request to the /api/unstable/embed/sso/generate-session endpoint. This will return a token that will be redeemed later.

Most parameters listed in the Embed parameters section can be passed in the JSON body of the request. The only exceptions are theme and prefersDark, which can be set via URL parameters in the login URL, and nonce, which isn't necessary at this step. Like the standard SSO login flow, contentPath, externalId, and name are required.

Note: As with all other API endpoints, an Authorization header with an Omni API key as a Bearer token is necessary for authentication purposes. Refer to the API docs for more information.

POST /api/unstable/embed/sso/generate-session
curl -X POST 'https://test.embed-thundersalmon.com/api/unstable/embed/sso/generate-session' \
-H 'Authorization: Bearer <YOUR_API_KEY>' \
-H 'Content-Type: application/json' \
-d '{
  "contentPath": "/my",
  "externalId": "dodgers-21",
  "name": "Walker Buehler",
  "connectionRoles": {
    "abcd1234-abcd-efgh-ijkl-abcdef123456": "RESTRICTED_QUERIER"
  },
  "entity": "Dodgers",
  "entityFolderContentRole": "EDITOR",
}'

Once a successful request is made, a few things will happen:

The endpoint will return a JSON payload with a single sessionId property. This sessionId will be used in the next step during session redemption.
An embed user will be upserted into your organization based on the request body's values.
An embed session will be created for this embed user with a 5 minute expiry. For security purposes, if the session isn't redeemed within 5 minutes of creation, the session will no longer be usable.

Step 2: Redeem the session

With the sessionId returned from Step 1, you can now create a 2-step session redemption URL.

Like standard SSO embed login URLs, session redemption URLs should be passed into the src attribute of an iframe HTML element. In addition, 2-step SSO embed login URLs must be signed using the request host, a nonce, and other URL parameters. Refer to the Session redemption signature section for details on how to generate the signature.

Required URL parameters:
- Session ID
- Nonce
- Signature
Optional URL parameters:
- Prefers dark
- Theme

Example URL
https://test.embed-thundersalmon.com/embed/sso/redeem-session
?prefersDark=false
&theme=vibes
&nonce=XxDcs01bnenbOyJTNAAUHheXRVFTVDOA
&sessionId=abcd1234-abcd-efgh-ijkl-abcdef123456
&signature=7Gk9LmN2oP3QrStUvWxYzA1BcDeFgHiJkLmNoPqRsTu

Once the URL is passed into an iframe and a successful session redemption request is made, the following will happen:

The associated embed session will update its expiry from 5 minutes to 24 hours, or to the custom Session Length specified in the Admin > Embed section of your Omni organization.
The iframe will redirect to the contentPath specified in Step 1 during session generation.

Using the SDK

The simplest way to implement the 2-step SSO embed login flow is using the TypeScript SDK. The createSessionToken and redeemSessionToken functions are included in the TypeScript SDK and correspond to Step 1 and Step 2, respectively.

TypeScript SDK
// Step 1
const { success, sessionToken } = await createSessionToken({
  apiKey: "<YOUR API KEY>",
  connectionRoles: {
  "abcd1234-abcd-efgh-ijkl-abcdef123456":
    EmbedConnectionRoles.RESTRICTED_QUERIER,
  },
  contentPath: "/dashboards/abcd1234",
  externalId: "dodgers-17",
  host: "myorg.embed-omniapp.co",
  mode: EmbedSessionMode.Application,
  name: "Shohei Ohtani",
});
if (!success) throw new Error("Failed to generate session");

// Step 2
const redeemSessionUrl = await redeemSessionToken({
  host: "myorg.embed-omniapp.co",
  prefersDark: "false",
  theme: "vibes",
  secret: "<YOUR EMBED SECRET>",
  sessionToken,
});

...

<iframe src={redeemSessionUrl} />

Session redemption signature

note

If using the TypeScript SDK redeemEmbedSsoSession function, the signature will be automatically generated and included in the returned session redemption URL.

Like with standard SSO embed login URLs, the signature is generated using the request URL and the URL parameters. To generate the signature, the following steps must be followed exactly:

Concatenate the properties, delimited by a newline character in the exact order enumerated below. Note: The parameters are in alphabetical order, with the exception of the leading login URL:
- Request URL
- Nonce
- Session ID
Concatenate the optional properties, again in alphabetical order. Any undefined optional properties must be omitted - no space, no extra newline, etc:
- Prefers dark
- Theme
There must be no leading or trailing spaces, and 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:
Example signature
```
https://example.embed-omniapp.co/embed/sso/redeem-session
XxDcs01bnenbOyJTNAAUHheXRVFTVDOA
abcd1234-abcd-efgh-ijkl-abcdef123456
true
vibes
```
Sign the string using your secret key (available in Admin > Embed section) with an HMAC sha256 digest algorithm, encoded as a base64url string. Refer to this standard for more information about base64url.
Node.js example
```
const hmac = crypto.createHmac("sha256", secret);
hmac.update(data);
return hmac.digest("base64url");
```

Understanding the embed URL​

Generating a secret​

Embed parameters​

Option 1: Standard SSO embed​

Step 1: Generate a signed embed URL​

Step 2: Craft the URL​

Test your URL with the embed URL builder​

Option 2: 2-step SSO Embed​

Advantages​

Setup​

Step 1: Generate the user and session​

Step 2: Redeem the session​

Using the SDK​

Session redemption signature​