Single Sign On

OpenWeb’s single sign-on (SSO) process allows using your existing identity management solutions with OW products.

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.

1131

Single sign on sequence diagram


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:

⚠️

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

ParameterDescription
display_nameNon-unique personal identifier used prominently throughout the platform

A display name has the following characteristics:
   • Cannot exceed 30 characters
   • Is comprised of a combination of letters, numbers, special characters, or spaces
primary_key*Unique user ID generated by a Partner’s backend user management system
user_name*Unique personal identifier used to differentiate between different users

A username has the following characteristics:
   • Is greater than 3 characters, but less than 30 characters
   • Can be comprised of foreign-language characters
   • Cannot be comprised of delimiters, such as spaces, tabs, and other ASCII delimiters (/t, /r, and /n)
   • Cannot be comprised of special characters, such as < and >
   • Is preceded by the @ symbol when displayed

If a username is already taken, OpenWeb appends random letters or numbers to generate a unique version of that username and registers it to the user.

If a username is not provided, OpenWeb creates a username from the display_name, appends random letters or numbers to generate a unique version of that username, and registers it to the user.
emailEmail of the user
email_verifiedIndicates that the email of the user has been verified by the user

Possible values:
   • true
   • false

OpenWeb only sends email notifications to verified email addresses.

When not set, this is set to false. To update this value, the user's email address must be sent as part of the update request.
image_urlURL of the profile image of the user

This image is the avatar used for all comments created by the user. If the image_url is not set, OpenWeb selects a random avatar from the avatar scheme for the user.

To delete a set user image, send an empty string for this parameter.
locationLocation of the user
private_profileIndicates whether the user's commenting history and profile can be viewed by others

Possible values:
   • false (default)
   • true
user_metadataIndicates if the user is a subscriber or not and enables the segmentation of data by subscribers and non-subscribers

If a user's subscriber status changes, you must log out the user and complete a new SSO flow. This ensures that a user's previous cached client state for user_metadata.is_subscriber is not used.

Possible values (values must be Base64-encoded):

{
  "is_subscriber": true
}

When this value is passed for a user, you can also show a customized subscriber badge next to the user's name in the Conversation. Please contact Support to enable and customize the subscriber badge.



{
  "is_subscriber": false
}

Body Parameters
PropertyDescription
bio stringUser bio

When configuring a user bio, the bio cannot exceed 200 characters.

This property can be passed with or without the role or settings object.
role stringPermission level of the user

Possible values
   • admin: Access to all sections of the system
   • moderator: Access only to the moderation section
   • community-moderator: Ability to moderate comments within a Conversation, but no Admin Panel access
   • journalist: Ability to select top comments, but no Admin Panel access
   • viewer: View-only access to the moderation section:
   • registered: Regular user with no assigned role (This is the default permission that is set when no role is specified.)

This property can be passed with or without the bio or settings object.
settings objectEmail and in-app notification settings

Possible notification values:
   • immediately: Notifications sent instantly
   • never: Notifications not sent

Within either the settings.notifications.email or settings.notifications.in_app object, the notification values can be set for the following notifications:
   • liked_your_message
   • message_approved
   • message_rejected
   • replied_to_message
   • used_mentioned

When a notification setting is not specified, immediately is set by default.

The settings object can be passed with or without the bio or role property.