Single Sign On

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.

Prerequisites

You must request the following from your OpenWeb PSM:

• OpenWeb SSO enabled for your site
• Your secret access token

📘

If you do not currently have any user management solution implemented on your site, OpenWeb can also be used as your primary user management solution.

You can also enable single sign on through one of our third-party SSO partners.

SSO Handshake Overview

The following steps and diagram provide an overview of how an SSO handshake is initiated and 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 an SSO session ID (codeA).

3. Send the SSO session ID to your backend user management system.

4. Validate that a user is logged into your system. You must ensure that the current user logged into your site will also be the current user in the OpenWeb user session.

5. From your backend user management system, make a GET /sso/v1/register-user call to OpenWeb. The API call must include the following information:

   • Your secret access token (access_token)
   • Session ID generated after initiating the SSO session (code_a)
   • Required user details from your backend user management system (primary_key, user_name)

   OpenWeb logs in the user and returns a success response (codeB).
   

6. Pass codeB to OpenWeb. Successfully completing this process results in logging in a user.

Sample Implementation

You have the flexibility to implement the login process in a way that aligns with the design of your site. The following frontend and backend code samples show one approach to implement single sign on.

Frontend Login

Use the following recipe to add the frontend login code to your page.

Backend SSO Handshake

Your backend user management system must log in the current user into OpenWeb and communicate the result back to the frontend code above.

From your backend user management system, make a GET /sso/v1/register-user call to OpenWeb. The API call must include your secret access token (access_token), the session ID generated after initiating the SSO session (code_a), and required user details from your backend user management system (primary_key, user_name).

📘

• Each of these parameters is defined in the Add user information section.
• Also by making a modified GET /sso/v1/register-user call, you can configure email notifications that OpenWeb sends to your users on your behalf and add a user bio.
• Sending attributes through this call for existing users overrides existing attributes of the user.

GET https://www.spot.im/api/sso/v1/register-user?code_a={CODE_A}&access_token={ACCESS_TOKEN}&primary_key={PRIMARY_KEY}&user_name={USER_NAME}

The API returns code_b as raw text.

vzFQZwLz670glmBv9lIV0%

💡

The GET /sso/v1/register-user route enables you to add more information about the user:

• Add additional user information as query parameters
• Configure a user's notification settings, add a bio, or set user permissions as body parameters

Trigger your log-in screen

Certain OpenWeb features can require users to be logged in. These includes writing comments, voting on other comments and more. When such policy is active in SSO, you receive an event notification to initialize your login process:

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

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

Manage users

Through backend API calls, OpenWeb enables you to manage your registered users:

• Register a new user
• Retrieve user details
• Update user details
• Delete a user

⚠️

Making calls from the Partner backend to the OpenWeb backend ensures that the access token in the HTTP request header is not compromised. Use the secret access token provided to you by OpenWeb.

Update user details

Update the OpenWeb user data of an existing SSO user

In order to simplify the process, OpenWeb expects the full data of the user.

GET https://www.spot.im/api/sso/v1/update-user
Header: x-spotim-sso-access-token: ACCESS_TOKEN

Query Parameters

{
  "is_subscriber": true
}

{
  "is_subscriber": false
}

Body Parameters