Skip to content

Latest commit

 

History

History
202 lines (148 loc) · 7.31 KB

README.md

File metadata and controls

202 lines (148 loc) · 7.31 KB
Raw

SSO (Single Sign On) with Spot.IM

Single Sign On (SSO) enables the partner user to auto-login to Spot.IM when he's logged into the Partner's site. To accomplish this, the partner needs to let Spot.IM know which user is currently logged into his site, in a secure manner. Understanding the technical flow is the sole challenge of performing a successful SSO implementation.

The following diagram demonstrates the generic flow:

SSO Flow

  1. Spot.IM lets the Partner know that it has been loaded and is now ready

  2. Partner asks Spot.IM to start an SSO session

  3. Spot.IM gives the SSO session a unique identifier called codeA

  4. Partner passes the codeA to his backend

  5. Partner passes the codeA to Spot.IM backend, alongside the user details

  6. Spot.IM logs the user in (registers it too if needed)

  7. Spot.IM acknowledges the success by providing the success codeB

  8. Partner passes the success codeB to his Front End

  9. Partner passes the success codeB to Spot.IM FED

  10. Spot.IM FED logs in the user and displays his avatar as logged in

Frontend Login integration

This code sample corresponds to the steps given above:

if (window.SPOTIM && window.SPOTIM.startSSO) {
  startSSO();
} else {
  document.addEventListener('spot-im-api-ready', startSSO, false);
}
function startSSO(){
  var callback = function(codeA, completeSSOCallback) {
        // call your backend to receive codeB and return it
        // to Spot.IM via completeSSOCallback function
        $.ajax({
            method: 'POST',
            url: '/spotim-sso/', // put your backend endpoint here
            data: {'code_a': codeA},
            success : function(codeB){
                if(codeB){
                    completeSSOCallback(codeB);
                }
            }
        });
  };
  window.SPOTIM.startSSO(callback).then(function(userData) {
    // userData contains information about the logged in user
  })
  .catch(function(reason){
    // reason contains error details
  });
}

Backend SSO Handshake Integration

The Partner's backend is responsible to log in the current user into Spot.IM and communicate the result back to the Front End.

It gathers the parameters listed in the table below, and issues a GET request to Spot.IM, which returns a codeB in exchange.

GET https://www.spot.im/api/sso/v1/register-user

Parameter Description Required Example
access_token An SSO secret token obtained from Spot.IM Yes 03160206m9oGNw
code_a The codeA you got through the API call from the FrontEnd Yes 03160206m9oGNw
primary_key A unique User ID (to be served as the primary key) Yes 12345678
user_name A unique user name that will be allocated for the user. Spot.IM will ensure this is unique even if taken. Yes john_doe
display_name Full name No John Doe
image_url User profile image URL No https://example.com/image1.jpg
email User email No but if you do not pass email, your team will not be able to log in to admin panel [email protected]
email_verified Set to true if the email was verified. Registering non verified emails in Spot.IM as verified violates the terms of use and will invalidate all users. No true

Example

https://www.spot.im/api/sso/v1/register-user?code_a=egosnilivzvbxeoeazhymjzswmlbplagrcyyvywm&access_token=03160206m9oGNw&primary_key=bar%40foo.com&user_name=bar&display_name=Bar%20Refaeli&image_url=https%3A%2F%2Fpbs.twimg.com%2Fprofile_images%2F657706432087904256%2FbE7bSek8.jpg&email=bar%40foo.com&verified=true

Frontend Logout Integration

To ensure state consistency between Spot.IM and the Partner it is required that the Partner informs Spot.IM whenever the user logs out.

The logout action is performed from the Front End by calling window.SPOTIM.logout()

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

Backend - updating existing user details

The update-user endpoint should be used when you’d like to update an existing user.

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

The parameters are the same as the register-user except for the code_a parameter.

We don’t need code_a here since there is no Frontend involved here. The partner Backend should call Spot.IM Backend.

In order to simplify the process Spot.IM expects the full data of the user as used in the register-user

Example

https://www.spot.im/api/sso/v1/update-user?primary_key=3169059&user_name=[]&display_name=[]&email=[]&verified=true

Backend - deleting existing user

To remain GDPR compliant, it is necessary to delete a user's Spot.IM account, upon their request to delete their Publisher account. The delete-user endpoint below should be used when you’d like to delete an existing user.

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

User's primaryKey should be placed in the PATH: PRIMARY_KEY - The unique User ID (to be served as the primary key)

SSO Access Token should be placed as a header in the HTTPS request, named x-spotim-sso-access-token: ACCESS_TOKEN - The same SSO secret token obtained from Spot.IM

The partner Backend should call Spot.IM Backend, when an account is deleted from the partner's site. Comments by the deleted user will be annonimized, meaning, the comments will remain but will be linked to a random guest user.

Backend - getting existing user details

The /v1/user/:primary_key endpoint should be used when you'd like to get the SpotIM 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

The required parameter is the users's primary key used in the register-user endpoint to register/login the user to SpotIM.

This must be done as a backend to backend call as to ensure the security of your access token (partner Backend should call Spot.IM Backend).

Example

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

Sample Reponse

{
  "success": true,
  "user": {
    "primary_key": "PKEY",
    "spotim_user_id": "string",
    "user_name": "string",
    "display_name": "string",
    "image_url": string,
    "email": string,
    "email_verified": boolean,
    "livefyre_user_id": string,
    "settings": {
      "notifications": {
        "email": {
          "liked_your_message": integer,
          "user_mentioned": integer,
          "replied_to_message": integer
        }
      }
    }
  }
}

Integration for "Require Login" moderation policy

Spot.IM allows moderators to activate a moderation policy which requires users to be logged in before writing comments. Usually the user is prompted with a Spot.IM login dialog when this policy is active.

With SSO, Spot.IM login UI never activated, and the login process needs to be initialized by the publisher.

The publisher is notified with an event when the user attempts to send his message.

SSO Flow

Example

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