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.

Requirements

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:

Listen for the spot-im-api-ready event. (You can also listen for other OpenWeb events.)
Initiate an OpenWeb SSO session. OpenWeb generates an SSO session ID (codeA).
Send the SSO session ID to your backend user management system.
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.
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).
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 example and table to add the frontend login code to your page.

This code example listens for spot-im-api-ready. Depending on the user experience you want to create, you can also listen for other frontend events to initiate the SSO handshake process.

When the SSO API is ready, the SSO process is initiated by window.SPOTIM.startSSO(callback,userId).

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

// In case of token expiration we need to renew sso
document.addEventListener('spot-im-renew-sso', startSSO, false);

// Prior to initiating this function, ensure that the user
// is actively logged into your site
function startSSO() {
    var callback = function(codeA, completeSSOCallback) {
        // call your backend to receive codeB and return it
        // to OpenWeb via completeSSOCallback function
        fetch('YOUR_BACKEND_URL', {
            method: 'POST',
            body: {
                code_a: codeA,
            }
        }).then(res => res.json()).then(codeB => {
            if(codeB){
                completeSSOCallback(codeB)
            }
        }).catch(err => {
            completeSSOCallback(null, err)
        });
    };
    window.SPOTIM.startSSO({callback: callback, userId: <unique-user-id>}).then(function(userData) {
        // userData contains information about the logged in user
    })
    .catch(function(reason) {
        // reason contains error details
    });
}

window.SPOTIM.startSSO ({callback: callback, userId: })

Argument Description

callback* function Function that initiates and completes the login handshake

The codeA argument calls your backend endpoint. The backend endpoint asks to register a user with or log in a user to OpenWeb and receives codeB to confirm the success of the process.

The completeSSOCallback argument accepts codeB and an error (if one exists) to complete the login handshake.

userId* string Enables OpenWeb to handle the login and logout logic

OpenWeb compares the userId passed into the method with the userId that exists in local storage when window.SPOTIM.startSSO() is executed. This is one approach to ensure that the OpenWeb session is always synced.

If the userId matches, no additional steps are required. The user is the same.

If the userId does not match, OpenWeb performs the following actions:
• Run window.SPOTIM.logout() to log out the existing user.
• Log in the new user.
• Replace the current userId attribute in local storage.

Argument	Description
callback* `function`	Function that initiates and completes the login handshake The `codeA` argument calls your backend endpoint. The backend endpoint asks to register a user with or log in a user to OpenWeb and receives `codeB` to confirm the success of the process. The `completeSSOCallback` argument accepts `codeB` and an error (if one exists) to complete the login handshake.
userId* `string`	Enables OpenWeb to handle the login and logout logic OpenWeb compares the `userId` passed into the method with the `userId` that exists in local storage when `window.SPOTIM.startSSO()` is executed. This is one approach to ensure that the OpenWeb session is always synced. If the `userId` matches, no additional steps are required. The user is the same. If the `userId` does not match, OpenWeb performs the following actions: • Run `window.SPOTIM.logout()` to log out the existing user. • Log in the new user. • Replace the current userId attribute in local storage.

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.

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%

Add user information

In addition to the required parameters, additional user information that you can append to the GET /sso/v1/register-user call are listed in the following table.

Parameter	Description
access_token*	Secret access token provide by OpenWeb
code_a*	Session ID returned after initiating an SSO session
display_name*	Non-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 When not provided, the name will be Guest.
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.
email	Email of the user
email_verified	Indicates 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`.
image_url	URL 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.
location	Location of the user
private_profile	Indicates whether the user's commenting history and profile can be viewed by others Possible values: • `false` (default) • `true`
user_metadata	Indicates 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 }`

Configure additional user settings

You can also use GET /sso/v1/register-user to configure a user's notification settings, add a bio, or set the user permissions.

Configure the following JSON object.

{
    "bio": "This is my personal bio",
    "role": "admin|moderator|journalist|viewer|community-moderator|registered",
    "settings": {
        "notifications": {
            "email": {
                "liked_your_message": "immediately|never",
                "message_approved": "immediately|never",
                "message_rejected": "immediately|never",
                "replied_to_message": "immediately|never",
                "user_mentioned": "immediately|never"
            },
            "in_app": {
                "liked_your_message": "immediately|never",
                "message_approved": "immediately|never",
                "message_rejected": "immediately|never",
                "replied_to_message": "immediately|never",
                "user_mentioned": "immediately|never"
            }
        }
    }
}

Property	Description
bio `string`	User 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 `string`	Permission 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 `object`	Email and in-app notification settings Possible notification values: • `immediately`: Notifications are sent instantly • `never`: Notifications are 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.

Add the Content-Type: application/json header to the GET /sso/v1/register-user call and append the JSON object from the previous step.

curl -X 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}
 -H 'Content-Type: application/json' \
 -d '{"bio":"This is my personal bio","role":"admin|moderator|journalist|viewer|community-moderator|registered","settings":{"notifications":{"email":{"liked_your_message":"immediately|never","message_approved":"immediately|never","message_rejected":"immediately|never","replied_to_message":"immediately|never","user_mentioned":"immediately|never"},"in_app":{"liked_your_message":"immediately|never","message_approved":"immediately|never","message_rejected":"immediately|never","replied_to_message":"immediately|never","user_mentioned":"immediately|never"}}}}'

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.

Register a new user

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

Query Parameters

Parameter	Description
display_name	Non-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 When not provided, the name will be Guest.
primary_key*	Unique user ID generated by a Partner’s backend user management system
spot_id*	Your OpenWeb account identifier
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.
email	Email of the user
email_verified	Indicates 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`.
image_url	URL 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.
location	Location of the user
private_profile	Indicates whether the user's commenting history and profile can be viewed by others Possible values: • `false` (default) • `true`
user_metadata	Indicates 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

Property	Description
bio `string`	User 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 `string`	Permission 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 `object`	Email 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.

Retrieve user details

Retrieve the OpenWeb user data of an existing SSO user

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

Path Parameter

Parameter	Description
primary_key*	Unique user ID generated by a Partner's backend user management system

Sample Response

{
    "success": true,
    "user": {
        "primary_key": "PRIMARY_KEY",
        "spotim_user_id": "USER_ID",
        "user_name": "USER_NAME",
        "display_name": "DISPLAY_NAME",
        "bio": "BIO",
        "role": "admin|moderator|journalist|viewer|community-moderator|registered",
        "location": "LOCATION",
        "private_profile": false,
        "image_url": "IMAGE_URL",
        "email": "USER_EMAIL",
        "email_verified": true,
        "livefyre_user_id": null,
        "user_metadata": {
            "is_subscriber": false
        },
        "settings": {
            "notifications": {
                "email": {
                    "liked_your_message": "never|immediately",
                    "user_mentioned": "never|immediately",
                    "replied_to_message": "never|immediately",
                    "message_approved": "never|immediately",
                    "message_rejected": "never|immediately"
                },
                "in_app": {
                    "liked_your_message": "immediately|never",
                    "message_approved": "immediately|never",
                    "message_rejected": "immediately|never",
                    "replied_to_message": "immediately|never",
                    "user_mentioned": "immediately|never"
                }
            }
        }
    }
}

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

Parameter	Description
display_name	Non-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.
email	Email of the user
email_verified	Indicates 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_url	URL 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.
location	Location of the user
private_profile	Indicates whether the user's commenting history and profile can be viewed by others Possible values: • `false` (default) • `true`
user_metadata	Indicates 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

Property	Description
bio `string`	User 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 `string`	Permission 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 `object`	Email 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.

Delete user

Delete the OpenWeb user data of an existing SSO user

When requested by a user, you must delete the user’s OpenWeb account to remain GDPR compliant. Once the user has been deleted, comments by the deleted user remain and are linked to a random guest user.

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

Path parameter

Parameter	Description
primary_key* `string`	Unique user ID generated by a Partner's backend user management system