Growth or above plan is required.

The Single Sign-On (SSO) feature allows your users to authenticate once and gain access to your feedback hub seamlessly. With SSO integration, you can enable your users to log in to Supahub using their existing credentials from your authentication system. This developer documentation will guide you through the steps to integrate SSO with Supahub.

Prerequisites

Before you begin, make sure you have:

  1. Administrative access to your Supahub account.
  2. Growth plan and above.
  3. Access to your Private Key from SSO settings.

How it works

Here is a summary of the authentication flow:

  1. The user wants to authenticate and clicks on the “Login with YourWorkspaceName” button on your public hub’s navbar.
  2. They are redirected to your website’s custom login page, with the redirectTo parameter appended to the URL: https://yourdomain.com/sso/supahub?redirectTo=https://workspace-name.supahub.com/changelog
  3. Once the user is authenticated, your authentication system generates a JWT token.
  4. The user is then redirected back to Supahub along with the generated token and the original redirectTo parameter passed along: https://workspace-name.supahub.com/api/auth/sso?jwt=payload&redirectTo=https://workspace-name.supahub.com/changelog
  5. Supahub receives the token and logs the user into the system using the validated token.
  6. Finally, Supahub automatically redirects the user back to the page on your public hub where they initially clicked on the “Login with YourWorkspaceName” button.

Steps to Integrate SSO with Supahub

1

Set up a dedicated SSO page

Create a page on your website that will handle the authentication process. For example, you can use the URL: https://yourdomain.com/sso/supahub

Go to your Supahub Dashboard and navigate to the “Settings” section. Look for the SSO settings and enter the URL of the SSO page you created in the ”SSO Redirect URL” field.

Once saved the “Login with YourWorkspaceName” button on your public hub’s navbar will be shown automatically.

2

Authenticate Users

When a user visits your SSO page, use your app’s authentication system to authenticate them. This could involve verifying their credentials or any other authentication mechanism you have in place.

3

Install JWT packages

Install the required packages for JWT token generation on your server.

4

Generate the JWT token

Copy and use the “Private Key” from SSO settings to generate a JWT token on your server.

Private Key should be kept secure and not to be shared. Add it in your .env file.

To enhance security measures, Single Sign-On (SSO) tokens are restricted from authenticating users with administrative privileges within any Supahub workspace. Instead, these users will need to log in using the dedicated portal at workspace.supahub.com

5

Redirect the user back to Supahub

Redirect the user to the Supahub JWT endpoint with the jwt and redirectTo URL. https://workspace-name.supahub.com/api/auth/sso?jwt=payload&redirectTo=https://workspace-name.supahub.com/changelog

Note: If you have custom domain implemented, the redirect URL will be: https://feedback.yourdomain.com/api/auth/sso?jwt=payload&redirectTo=https://feedback.yourdomain.com/changelog

Add User & Company Data

You can also pass the user and company data inside JWT token generation.

Node.js
var jwt = require("jsonwebtoken");
const SSO_KEY = "YOUR_PRIVATE_SSO_KEY";

function generateJWTToken(user) {
  var userData = {
    email: user.email,
    name: user.name,

    id: "786", // Required: Unique id that you are using to identify your user

    avatar: "https://example.com/images/user-profile.jpg", // Optional

    customFields: {
      title: "Product Manager",
      location: "Paris",
    }, // Optional: Add any type of field, in the format ({key1: "value1", key2: "value2"})

    // Company Data
    companies: [
      {
        id: "786", // Required
        name: "Acme Inc.", // Required
        logo: "https://example.com/images/company-logo.jpg", // Optional
        monthlySpend: 300, // Optional, but recommended
        createdAt: "2023-05-19T15:35:49.915Z", // Optional
      },
    ],
  };

  return jwt.sign(userData, SSO_KEY, {
    algorithm: "HS256",
  });
}