How to enable SSO for your application

Background

SSO provides a better experience for your customers if they want to leave feedback, add a comment, or vote on something. It removes the need for them to create an account on Suggested.

With SSO your user is automatically signed into Suggested when they have a valid session on your web application.

To enable Single Sign-On

Goto settings click on 'Single Sign-On' and click on the button labelled "Generate Single Sign-on token".

This will create your secret token and app id which you will need to integrate SSO.

The SSO Process

The process of implementing SSO works like this:

1. Store a copy of the secret token on your server. Do not share this with anyone.
2. Generate a userHash for the current user on your server. This is a HMAC of the user's unique ID and email address
3. Log the user into Suggested using our JS SDK.
4. When the user visits your portal, the JS SDK will transparently create a new user session for them on our system.
5. The next time the user goes to your feedback portal, they'll be automatically logged in.

Generating the userHash HMAC

You'll need to generate a HMAC on your server using the secret token. The token is generated using your user's ID and email address. Typically the user ID is the primary key that you use for your users in your database.

Below are examples of how to do it in different languages:

In Python 3+

import hmac
import hashlib

user_id = 100 # your user's unique id 
email_address = "nick.f@shield.gov" # email address of your user

user_hash = hmac.new(
  'YourSecretKey', # secret key (keep safe!)
  '{}{}'.format(user_id, email_address), # concat user id and email address
  digestmod=hashlib.sha256 # hash function
).hexdigest()

In Ruby:

OpenSSL::HMAC.hexdigest(
  'sha256', # hash function
  'YourSecretKey', # secret key (keep safe!)
  current_user.id + current_user.email_address # user's id and email address concated
)

Login the user using the Suggested javascript SDK

At this point, you've generated the userHash server side, now you'll need to send it to your frontend app so that you can login the user.

First step is to include the Suggested SDK into your app:

<script src="https://platform.suggested.co/sdk/js/v1/sdk.js" />

Then call the auth method on the SDK with your user's details to create a user session on Suggested.

window.Suggested("auth", {
  userHash: 'YourGeneratedUserHash',
  userId: 100,
  emailAddress: 'nick.f@shield.gov',
  name: 'Nick fury',
  appId: 'YourAppID'
}, function(response) {
  // redirect here, or do something else
})

The userHash, userId, emailAddress, name and appId are all required fields.

Once called, your user will have a valid user session in your portal. The user can be redirected to the portal at this point, or they can visit the portal in their own time.

Help

If you run into any issues setting up SSO for your account, get in contact with us at support@suggested.co and we'll be happy to help!