Implement third-party single sign on

Use a third-party single single on provider to log in your users.

OpenWeb’s single sign on (SSO) enables your registered users to participate in members-only conversations without an extra registration. To provide this user experience, your backend user management system must securely inform OpenWeb that a user is actively logged into your site.

OpenWeb has integrated with the following third-party single sign on providers:

  • Auth0
  • Gigya
  • Piano.io

These third-party SSO provider partners simplify managing your users.

If you would like to work with a third-party SSO provider that is not listed above, please contact your OpenWeb PSMPSM - Partner Success Manager.

📘

TIP

You can also enable single sign on without a third-party partner.

OpenWeb also allows your users to login with their Facebook, Google, Twitter, or email credentials. If you are interested in this option, contact your PSM and ask about Social Login.



Requirements

You must request the following from your OpenWeb PSM:

  • OpenWeb SSO enabled for your site

You request the information in the following table from your third-party SSO provider.

ProviderRequired information
Auth0   • Auth0 Domain
   • Resp_Prefix
   • User ID

Contact your Auth0 representative if you need assistance locating this information.
Gigya   • Api_Key
   • Secret
   • Data_Center
   • Account ID
   • User ID

Contact your Gigya representative if you need assistance locating this information.
Piano.io   • App ID
   • API Token
   • Private Key
   • User ID

Contact your Piano.io representative if you need assistance locating this information.


Log in a user

Third-party single sign on sequence diagramThird-party single sign on sequence diagram

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.


Implementation


Configure a third-party SSO partner

  1. From your Spot.IM 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) {
    startSSO();
} else {
    document.addEventListener('spot-im-api-ready', startSSO, false);
}

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

  1. Replace {PROVIDER_NAME_FROM_OPENWEB} with the name of a 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 Spot.IM. Use window.SPOTIM.logout() to end a registered user’s Spot.IM session.

if (window.SPOTIM && window.SPOTIM.logout) {
    window.SPOTIM.logout();
} else {
    document.addEventListener('spot-im-api-ready', function() {
        window.SPOTIM.logout();
    }, 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

Piano.io

Managing the Conversation display name

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

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


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



Did this page help you?