🔑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:

Your user clicks on a link in your app to enter your community.
Clicking on this link triggers the creation of a signed token (see below).
Your app redirects the user to your Spot and passes the token along.
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).

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).
On your app, the user will need to login or sign up.
Your app will generate a signed token (see how to below).
Your app will redirect the user to your Spot and pass the token along.
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 :

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).
Copy your private key.
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.

Install JWT library

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

npm install --save jsonwebtoken

pip install PyJWT

composer require firebase/php-jwt

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.

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
  };
  return jwt.sign(userData, privateKey, { algorithm: "HS256" });
}

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')

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:

sub (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 (required): The first name of the user. It should be 255 characters or less.
lastName (required): The last name of the user. It should be 255 characters or less.
email (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: The job title of the user in plain text format.
avatarUrl: 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: 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: The default timezone to apply in the application. If not specified or invalid, it will default to Europe/Paris.
iat: The issue time of the JWT.
exp: 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.

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).

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!

PrécédentWebhooks SuivantEmbed

Dernière mise à jour il y a 7 mois