Third-party single sign on

Use a third-party identity management provider to authenticate your users.

To simplify the single sign on implementation process, OpenWeb has created out-of-the-box integrations with the following third-party identity management providers:

  • Auth0
  • Gigya


Zephr offers it’s own single sign on integration with OpenWeb. For more information, see Zephr’s documentation on their OpenWeb SSO Extension.

If your identity management solution is not listed above, please see our standard Single Sign On implementation guide.


Request the following from your OpenWeb PSM:

  • OpenWeb SSO enabled for your site

Request the information in the following table from your third-party SSO provider:

ProviderRequired information
Auth0   • Auth0 Domain
   • Resp_Prefix
   • User ID
Gigya   • Api_Key
   • Secret
   • Data_Center
   • Account ID
   • User ID   • App ID
   • API Token
   • Private Key
   • User ID

Log in a user


Third-party single sign on sequence diagram

When logging in a user, the following actions must be completed:

  1. Listen for the spot-im-api-ready event. (You can also listen for other OpenWeb events.)
  2. Initiate an OpenWeb SSO session. OpenWeb generates and shares an SSO session ID with the third-party SSO partner. Once a user has been validated, the user is logged in to the Conversation.


Configure a third-party SSO partner

  1. From your OpenWeb Admin Dashboard, click Settings > SINGLE SIGN ON.
  2. From the User Management Platform drop-down menu, select a third-party SSO provider.
  3. Enter your third-party SSO provider information in the fields that are displayed.
  4. Click Test Connection to validate the third-party SSO provider settings.
  5. Click Save Changes.

Add single sign on to a site

You have the flexibility to implement the login process in a way that aligns with the design of your site and implementation of a Conversation. The following process shows one approach to implement single sign on with a Conversation under the following condition:

  • The Partner listens for spot-im-api-ready.

  1. Add the following code to pages containing a Conversation. You can also listen for other Conversation events to initiate the SSO process.
if (window.SPOTIM && window.SPOTIM.startSSOForProvider) {
} else {
    document.addEventListener('spot-im-api-ready', startSSO, false);

function startSSO() {
    window.SPOTIM.startSSOForProvider({provider: 'gigya | piano | auth0',token: token}).then(function(userData) {
        // userData contains information about the logged in user
    .catch(function(reason) {
        // reason contains error details

  1. Set the supported third-party SSO provider.
  2. Define token with the token provided to you by the third-party. This token is a JWT or any other token used to identify the current user on page. When OpenWeb contacts the third-party, this enables OpenWeb to identify the user.

Log out a user

When a registered user logs out from your system, the same user must be logged out from OpenWeb. Use window.SPOTIM.logout() to end a registered user’s OpenWeb session.

if (window.SPOTIM && window.SPOTIM.logout) {
} else {
    document.addEventListener('spot-im-api-ready', function() {
    }, false);

Update a user

If you need to update the details of user, you can use one of the following approaches listed in the following sections: Log out / log in or Update user details.

Log out / log in

  1. Log out the user.
  2. Log in the user with an updated token.

Update user details

You can update OpenWeb user details with the update user details endpoint.

Integrate "Require Login" moderation policy

OpenWeb allows moderators to activate a moderation policy that requires users to be logged in before writing comments. Usually, the user is prompted with an OpenWeb login dialog when this policy is active.

With SSO, the OpenWeb login UI does not activate. You need to initialize the login process.

You receive an event notification when a user attempts to send a message.

document.addEventListener('spot-im-login-start', function(event) {
    // trigger your login flow here

Third-party tips

Managing the Conversation display name

If you use as your third-party single-sign on, you can control the user name that is displayed in the Conversation.

In your dashboard, create a custom field. The custom field you create must have the following value: display_name.

During the single sign on authentication, the integration passes the display_name value to OpenWeb. OpenWeb will use the display_name value as the user's name in the Conversation.

Verifying email addresses

OpenWeb only sends email notifications to user verified emails.

Asking users to verify their emails is possible using's double opt-in feature. OpenWeb automatically retrieves the user's current verification status to decide if to send emails to that user.

Piano also offers to check the user's email verification status using these methods.