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.
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.
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 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. |
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 displayedIf 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 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):
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.
|
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 sentWithin 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 theGET /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
Register a new SSO user to OpenWeb
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 displayedIf 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 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):
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.
|
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 sentWithin 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 displayedIf 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 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):
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.
|
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 sentWithin 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 |
Updated 9 months ago