Skip to main content
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
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.

​
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 Omni API key

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

Generate the user & session

You can also use the createSessionToken function in the TypeScript SDK to complete this step.
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 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.
POST /api/unstable/embed/sso/generate-session
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.
5

Generate the session redemption signature

If using the TypeScript SDK redeemSessionToken function, the signature will be automatically generated and included in the returned session redemption URL.
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: 
    login URL
nonce
sessionId
  2. Concatenate the optional properties in alphabetical order, delimited by a newline character. Omit any undefined properties. 
    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: 
    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 for more information about base64url.
    Node.js example
    const hmac = crypto.createHmac("sha256", secret);hmac.update(data);return hmac.digest("base64url");
6

Redeem the session

You can also use the redeemSessionToken function in the TypeScript SDK to complete this step.
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. 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)
    • Signature (signature)
  • Optional URL parameters:
Example URL
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 specified during session generation.