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](doc:identity). You can also enable single sign on through one of our [third-party SSO partners](doc:implement-third-party-single-sign-on).

## 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](doc:event-listener-reference#conversation-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}

### 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. {/* 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)`.
```javascript Code example: frontend login 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: }).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](doc:implement-single-sign-on#add-user-information) section. _ Also by making a modified `GET /sso/v1/register-user` call, you can [configure email notifications](doc:implement-single-sign-on#configure-additional-user-settings) that OpenWeb sends to your users on your behalf and [add a user bio](doc:implement-single-sign-on#configure-additional-user-settings)._ Sending attributes through this call for existing users overrides existing attributes of the user. ```http GET /sso/v1/register-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. ```text API response 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 {/* ##### 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, OpenWeb creates a Display Name from the `user_name`.
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): ```json { "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. ```json { "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. 1. Configure the following JSON object. ```json { "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. |
2. Add the `Content-Type: application/json` header to the `GET /sso/v1/register-user` call and append the JSON object from the previous step. ```http Set email notifications and add user bio 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:

```javascript Code example 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. ```javascript 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](ref:post_sso-v1-user) * [Retrieve user details](ref:get_sso-v1-user-primary-key) * [Update user details](ref:get_sso-v1-update-user) * [Delete a user](ref:delete_sso-v1-user-primary-key) 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. {/*
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 ```http 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, OpenWeb creates a Display Name from the `user_name`.
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): {`{\n "is_subscriber": true\n}`} 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. {`{\n "is_subscriber": false\n}`}

#### 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 ```http retrieve user details 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 ```json { "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. ```http Update user details 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**
• Can contain letters, numbers, special characters, or spaces

When not provided, OpenWeb creates a display name from the `user_name`. | | **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 users.

A username has the following characteristics:

• Is greater than **3 characters** and fewer than **30 characters**
• Can contain foreign-language characters
• Cannot contain delimiters such as spaces, tabs, or other ASCII delimiters (`\t`, `\r`, and `\n`)
• Cannot contain 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 create and register a unique version.

If a username is **not provided**, OpenWeb creates one from the `display_name`, appends random letters or numbers, and registers it to the user. | | **email** | Email address of the user. | | **email_verified** | Indicates whether the user's email address has been verified.

**Possible values:**

• `true`
• `false`

OpenWeb only sends email notifications to verified email addresses.

When not provided, this value defaults to `false`. | | **image_url** | URL of the user's profile image.

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

To delete an existing 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 whether the user is a subscriber and enables data segmentation between subscribers and non-subscribers.

If a user's subscriber status changes, you must [log out the user](implement-single-sign-on#log-out-a-user) and complete a new SSO flow. This ensures that the previously cached client value for `user_metadata.is_subscriber` is not reused.

**Possible values must be Base64-encoded:**

`{ "is_subscriber": true }`

When this value is passed, you can display a customized subscriber badge next to the user's name in the Conversation. Contact Support to enable and customize the 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. ```http delete 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 | \*/}
{/* Removes navigation at the bottom of the page */} {` `}