🔑Single Sign-On

All it takes is a few lines of code added to your website!

With our Json Web Token (JWT) SSO implementation, you will be able to automatically register or log members into your Spot. If you enable SSO, a user will go through the following flow:

From your App

1. Your user clicks on a link in your app to enter your community.

2. Clicking on this link triggers the creation of a signed token (see below).

3. Your app redirects the user to your Spot and passes the token along.

4. If we can validate the token, we log the user in and identify them using the information passed in the token (like their name and email address).

From your Spot

1. A user who clicks on Login or Join on your Spot (go.meltingspot.io/spot/...) will be redirected to a page on your website (the authorisation URL, see below).

2. On your app, the user will need to login or sign up.

3. Your app will generate a signed token (see how to below).

4. Your app will redirect the user to your Spot and pass the token along.

5. If we can validate the token, we log the user in and identify them using the information passed in the token (like their name and email address).

Implementation

1. Enable JWT SSO in your Spot settings

First, you will need to activate the SSO in your Spot settings :

1. Add an authorisation URL. It is the URL of the page where the user is redirected to be authenticated on your side (2nd bullet point in the "From your Spot" flow). 👀 If you want to run local tests, use 127.0.0.1 in the URL, as localhost URLs are blocked by our system.

2. Copy your private key.

3. Turn SSO on once you are ready.

You will need to create a custom signed link for your app that would automatically pass information to your Spot, such as: the email, first and last name of the member you want to log in.

2. Generate an SSO token

You will need to create a custom signed JWT for your user that would automatically pass information to your Spot.

1. Install JWT library

First, you'll have to install a library that allows you to create the token embedding your user's information.

Node.js

npm install --save jsonwebtoken

Python

pip install PyJWT

PHP

composer require firebase/php-jwt

1. Create the token

Next, you'll have to prepare a signed JWT defining some or all available user information. You'll have to use the private key copied from the Spot settings.

Node.js

const jwt = require('jsonwebtoken');
const privateKey = "{Your Private Key}";
function createToken(user) {
  const userData = {
    sub: user.id, // Your own user ID
    firstName: user.firstName,
    lastName: user.lastName,
    email: user.email,
    title: user.title, // optional
    avatarUrl: user.avatarUrl, // optional
    lang: user.lang, // optional
    timezone: user.timezone, // optional
    groups {
      join: ["groupsId",...];
      leave: ["groupsId",...]; 
    }, //optional
    domains {
      set: { default: "https://some-default-url.com/for/this/member", customContext: "https://some-custom-context-url.com/for/this/member",...}
      unset: ['default', 'customContext']
    }, //optional
  };
  return jwt.sign(userData, privateKey, { algorithm: "HS256" });
}

Python

import jwt

private_key = '{Your Private Key}'

def create_token(user):
  user_data = {
    'sub': user.id, # Your own user ID
    'firstName': user.firstName,
    'lastName': user.lastName,
    'email': user.email,
    'title': user.title, # optional
    'avatarUrl': user.avatarUrl, # optional
    'lang': user.lang, # optional
    'timezone': user.timezone, # optional
  }
  return jwt.encode(user_data, private_key, algorithm='HS256')

PHP

use Firebase\JWT\JWT;

const privateKey = '{Your Private Key}';

function createToken($user) {
  $userData = [
    'sub': $user['id'], // Your own user ID
    'firstName': $user['firstName'],
    'lastName': $user['lastName'],
    'email': $user['email'],
    'title': $user['title'], // optional
    'avatarUrl': $user['avatarUrl'], // optional
    'lang': $user['lang'], // optional
    'timezone': $user['timezone'], // optional
  ];
  return JWT::encode($userData, privateKey, 'HS256');
}

You can use all the following fields in the JWT:

Parameter	Type	Description
sub	string	(required) The ID of the user in your product or platform. This value will be stored as an external ID in MeltingSpot. It should be 255 characters or less.
firstName	string	(required) The first name of the user. It should be 255 characters or less.
lastName	string	(required) The last name of the user. It should be 255 characters or less.
email	string	(required) The email of the user. This email address is considered as a verified address. You should make sure you've verified it on your side. It should be 255 characters or less and follow a valid email address format.
title	string	The job title of the user in plain text format.
avatarUrl	string	A full URL to the user's profile picture. It should include https:// or http://. You should make sure it's a valid URL on your side.
lang	string	The default locale to apply in the application. Currently, MeltingSpot supports: en for English fr for French de for Deutsch If not specified or invalid, it will default to en.
timezone	string	The default timezone to apply in the application. If not specified or invalid, it will default to Europe/Paris.
iat	number	The issue time of the JWT.
exp	number	The expiration time of the JWT. Although this value is not required, it's highly recommended to set it to 60 seconds from now. If not set, the token will be valid forever and can introduce security issues.
groups:join	string	The groups to which you want to add the member. Simply retrieve the id of the groups in question from the group selection menu of the audience table.
groups:leave	string	The groups whose members you wish to remove. Simply retrieve the id of the groups in question from the group selection menu in the audience table.
domains: set	string	If you have embedded the Spot into several domains, specify which domains the member can have access to. They will be redirected to the default domain key when clicking on a notification email.
domains: unset	string	If you have embedded the Spot into several domains and specified member redirection domains, you can remove them via this parameter (URL of a software for which the member no longer has a license, website whose URL has changed...). You'll need to reuse the keys defined in the set object.

3. Redirection to MeltingSpot

Once the user token has been created, you need to redirect the user to a URL by passing the token as a parameter. This URL is supplied to you as a parameter (redirectUrl) when the user lands on your authorization URL. Basically, it looks like this:

https://go.meltingspot.io/spot/<Your Spot ID>/sso/jwt

You need to add the token as a parameter as follows:

https://go.meltingspot.io/spot/<Your Spot ID>/sso/jwt?ms_token=<Your generated SSO Token>

In most cases, the redirect URL we provide (redirectUrl) also contains a referrerUrl parameter that returns the user to the page they were on when they logged in in SSO mode.

You can force the value of this parameter, but to be valid, the value must represent a path relative to https://go.meltingspot.io and your Spot (e.g. ?referrerUrl=/spot/129487c9-6acc-43d9-ab96-182ded763538/lives).

Your Spot ID is the string following spot/ in your Spot's url (eg: go.meltingspot.io/spot/129487c9-6acc-43d9-ab96-182ded763538 -> Spot ID is 129487c9-6acc-43d9-ab96-182ded763538).

Embed / widgets + SSO = ❤️

Once SSO authentication has been set up for your Spot, you can pass on the JWT token authenticating the user in the Spot embed or widget installation scripts. This will enable every user in your space to access the embed or widget with a connected status. When displaying your Spot in embed, your members will no longer have to click on 'Continue with SSO' to sign up or log in 😉

To do this, you need to add the authToken parameter to the embed or widget installation script parameters.

Good to know

• What happens when the user logs in? If the user does not exist, we will create the user using the provided information in the JWT and log him in. If the user exists, it will only log him in, without updating his information.

• What happens to existing users when I activate the SSO on my Spot?

  If you activate the SSO, your existing members can still connect using a password. They will be able to use both authentication methods (SSO or email + password) as long as they use the same email. Both authentication methods will be attached to the same user.

• What if members join my private Spot through SSO? Members who register to your Spot through SSO are automatically accepted, even if your Spot is private. You can always deactivate them later.

• What happens if my user updates his email address on my app? The next time on of your users logs in to your community, we will consider the user to be a new member. If the user wants to connect to their account attached to their former email, the user will have to authenticate through login + password.

• Can I decide on which page of my Spot a member lands after logging in with SSO?

  Yes, when your users access your Spot from your application, you can use the "referrerUrl" parameter to send them to any page in your Spot.

• How are handled members' status (Invited / Pending / Declined / Rejected / Deactivated / Left) when they join / reconnect to a Spot with SSO? -> Check it here!