Single Sign-On (SSO)
Enable seamless access to Supahub’s public hub by integrating Single Sign-On (SSO) with your app’s existing authentication credentials.
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:
- Administrative access to your Supahub account.
- Growth plan and above.
- Access to your Private Key from SSO settings.
How it works
Here is a summary of the authentication flow:
- The user wants to authenticate and clicks on the “Login with YourWorkspaceName” button on your public hub’s navbar.
- 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
- Once the user is authenticated, your authentication system generates a JWT token.
- 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
- Supahub receives the token and logs the user into the system using the validated token.
- 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
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.
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.
Install JWT packages
Install the required packages for JWT token generation on your server.
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
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.
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",
});
}