> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omni.co/llms.txt
> Use this file to discover all available pages before exploring further.
## Submitting Feedback
If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:
POST https://docs.omni.co/feedback
```json
{
"path": "/embed/setup/standard-sso",
"feedback": "Description of the issue"
}
```
Only submit feedback when you have something specific and actionable to report.
# Setting up embed with standard SSO
> Set up standard SSO for Omni embedding by generating a signed URL that creates an embed user session with a single request.
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. Navigate to **Settings > Embed > Admin** in your Omni instance.
2. Click the **Add Secret** button below the secrets table.
3. In the dialog that appears:
* A 32-character secret key is automatically generated for you
* Enter a descriptive **Name** to identify the secret's purpose (e.g., "Production", "Staging", or "Partner Integration")
Use descriptive names for your secrets to make them easier to identify and manage, especially when rotating secrets or managing multiple environments.
4. Click **Add secret** to save the new secret.
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**.
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](/embed/setup/url-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:
Omni has a supported Typescript SDK and some unsupported examples in other languages.
* **Supported** - [Typescript](https://www.npmjs.com/package/@omni-co/embed)
* **Unsupported** - [Ruby](https://gist.github.com/n8agrin/72295c9ad29283b6e02908b5d6837529)
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:
```text theme={null}
https:///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](/embed/setup/url-parameters) for a complete list of available parameters.
```bash wrap title="POST /embed/sso/generate-url" theme={null}
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:
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:
```text theme={null}
login URL
contentPath
externalId
name
nonce
```
Concatenate the optional properties in alphabetical order, delimited by a newline character **in the exact order enumerated below**:
```markdown theme={null}
accessBoost
connectionRoles
customTheme
customThemeId
email
entity
entityFolderContentRole
entityFolderGroupContentRole
entityFolderLabel
entityGroupLabel
filterSearchParam // must be URI encoded
groups
linkAccess
mode
modelRoles
prefersDark
preserveEntityFolderContentRole
theme
uiSettings
userAttributes
```
**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:
```shell wrap theme={null}
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](/embed/setup/url-parameters) for more information about available parameters.
Sign the string using your secret key with an HMAC sha256 digest algorithm, encoded as a base64url string:
```javascript wrap title="Node.js example" theme={null}
const hmac = crypto.createHmac("sha256", secret);hmac.update(data);return hmac.digest("base64url");
```
Refer to [the Base64 spec](https://datatracker.ietf.org/doc/html/rfc4648#page-7) for more information about base64url.
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://.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:
```shell wrap theme={null}
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
```
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](/embed/setup/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:
```markdown wrap theme={null}
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/`
* **For workbooks**: `/w/`
* **External ID** - Any alphanumeric value
* **Name** - Any alphanumeric value
4. Generate your URL and embed!