> ## 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.

<AgentInstructions>

## 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/two-step-sso",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# Setting up embed with 2-step SSO

> Set up 2-step SSO for Omni embedding using a POST request to generate a session token, then redeem it via a login URL.

In this guide, we'll walk you through setting up **2-step SSO** for Omni embed. Rather than performing an SSO embed login via a single login URL, the 2-step login flow divides the process into 2 steps:

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

<Tip>
  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.
</Tip>

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

<Steps>
  <Step title="Generate an embed secret">
    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")

             <Tip>
               Use descriptive names for your secrets to make them easier to identify and manage, especially when rotating secrets or managing multiple environments.
             </Tip>
    4. Click **Add secret** to save the new secret.
  </Step>

  <Step title="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**.
  </Step>

  <Step title="Generate an Omni API key">
    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](/api/authentication) for more information.
  </Step>

  <Step title="Generate the user & session">
    <Tip>
      You can also use the `createSessionToken` function in the [TypeScript SDK](https://www.npmjs.com/package/@omni-co/embed) to complete this step.
    </Tip>

    In this step, you'll generate the 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 reference](/embed/setup/url-parameters) can be passed in the JSON body of the request. The only exceptions are:

    * [`theme`](/embed/setup/url-parameters/theme) and [`prefersDark`](/embed/setup/url-parameters/prefersDark), which can be set via URL parameters in the login URL, and
    * [`nonce`](/embed/setup/url-parameters/nonce), which isn't necessary at this step

    Like the standard SSO login flow, [`contentPath`](/embed/setup/url-parameters/contentPath), [`externalId`](/embed/setup/url-parameters/externalId), and [`name`](/embed/setup/url-parameters/name) are required.

    ```json wrap title="POST /api/unstable/embed/sso/generate-session" theme={null}
    curl -X POST 'https://test.blobsrus.com/api/unstable/embed/sso/generate-session' \
    -H 'Authorization: Bearer <YOUR_API_KEY>' \
    -H 'Content-Type: application/json' \
    -d '{
      "contentPath": "/my",
      "externalId": "artiste1322",
      "name": "Blob Ross",
      "connectionRoles": {
        "abcd1234-abcd-efgh-ijkl-abcdef123456": "RESTRICTED_QUERIER"
      },
      "entity": "Happy Trees",
      "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>

  <Step title="Generate the session redemption signature">
    <Note>
      If using the TypeScript SDK `redeemSessionToken` function, the signature will be automatically generated and included in the returned session redemption URL.
    </Note>

    Signatures are generated using the request URL and URL parameters. To generate the signature, the following steps must be followed exactly:

    1. Concatenate the required 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:

       ```markdown theme={null}
       login URL
       nonce
       sessionId
       ```
    2. Concatenate the optional properties in alphabetical order, delimited by a newline character. **Omit any undefined properties**.

       ```markdown theme={null}
       prefersDark
       theme
       ```

       **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/sso/redeem-sessionXxDcs01bnenbOyJTNAAUHheXRVFTVDOAabcd1234-abcd-efgh-ijkl-abcdef123456falsevibes
       ```
    3. Sign the string using the **Embed secret** you created in step 1 with an HMAC sha256 digest algorithm, encoded as a base64url string. Refer to [this standard](https://datatracker.ietf.org/doc/html/rfc4648#page-7) for more information about base64url.

       ```javascript wrap title="Node.js example" theme={null}
       const hmac = crypto.createHmac("sha256", secret);hmac.update(data);return hmac.digest("base64url");
       ```
  </Step>

  <Step title="Redeem the session">
    <Tip>
      You can also use the `redeemSessionToken` function in the [TypeScript SDK](https://www.npmjs.com/package/@omni-co/embed) to complete this step.
    </Tip>

    With the `sessionId`, 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](/embed/setup/url-parameters). You'll use the signature you generated in the previous step to sign the embed login URL.

    * **Required URL parameters**:

      * Session ID (`sessionId`)
      * Nonce ([`nonce`](/embed/setup/url-parameters/nonce))
      * Signature (`signature`)

    * **Optional URL parameters**:

      * Prefers dark ([`prefersDark`](/embed/setup/url-parameters/prefersDark))
      * Theme ([`theme`](/embed/setup/url-parameters/theme))

    ```shell wrap title="Example URL" theme={null}
    https://test.embed-blobsrus.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`](/embed/setup/url-parameters/contentPath) specified during session generation.
  </Step>
</Steps>