Integrating Stateless Single Sign-on with Hyvor Talk

Make sure to read the introduction before integrating Single sign-on with Hyvor Talk.

Using WordPress? Our plugin supports SSO by default. Visit this tutorial.

Requirements

  • A Hyvor Account with business subscription.
  • Access to back-end of your website.
  • A developer to write the back-end code.

The Procedure

  1. Creating a SSO ID.
  2. Writing back-end code to create hashes and encode data.
  3. Setting up sso object in the Hyvor Talk installation code.

1. Creating a SSO Id

  • Go to the Account -> SSO section in the console.
  • Add a name, select "Stateless" as the type, and click "Create" to generate new SSO ID.
  • Now, click "Assign Websites" and choose the websites that you need to use this SSO ID.
  • Copy the Private Key. We will use it in the next steps.

2. Writing the back-end code

User Data Object

Key Description Type Status Max Length
id A unique ID saved in your database for each user. This is used to identify each user by Hyvor Talk. int or string required 128
name User's name string required 25
email User's email string required 125
picture URL of the user's profile picture string optional, recommended 1024
url URL of the user's profile string optional 1024

(The name will be trunctated if longer than 25 characters.)

The user data object should be JSON encoded and then base 64 encoded. Then, create a hash using the HMAC-SHA1 and your private key.

  • JSON encode + base64 - Just a simple trick to make the data unreadable without decoding.
  • HMAC-SHA1 - This is how we validate that the user data we received from you is what you sent.

Back-end code in PHP: (Assuming you already have a $user object)

<?php
$HYVOR_TALK_SSO_PRIVATE_KEY = 'MY_PRIVATE_KEY';  
// empty object for guests
$userData = [];
if ($user -> isLoggedIn()) { // check login
    // setup object for logged-in users
    $userData = [
        'id' => $user -> id,
        'name' => $user -> name,
        'email' => $user -> email,
        'picture' => $user -> picture,
        'url' => $user -> url
    ];
}

// json and base64 encoding (used for hash and later)
$encodedUserData = base64_encode(json_encode($userData));
// creating the hash (will use it soon)
$hash = hash_hmac('sha1', $encodedUserData, $HYVOR_TALK_SSO_PRIVATE_KEY);

This repository includes functions written in several other languages to generate the encoded user data and hash.

3. Setting up sso object in the installation code

Now, add the sso object to your installation code.

SSO Object

Key Description Type Status
id (No longer required) The ID of the SSO ID created in the first step. integer
hash The HMAC-SHA1 hash. string required
userData The JSON and base64 encoded user data object. string required
loginURL The login URL of your authentication system string required
signupURL The signup URL of your authentication system string optional

If continuing the PHP code above, you can echo the variables as follows.

var HYVOR_TALK_CONFIG = {
    // ... other configs
    sso: {
        hash: "<?= $hash ?>",
        userData: "<?= $encodedUserData ?>",
        loginURL: "https://example.com/login",
        signupURL: "https://example.com/signup"
    }
};

Never share the private key with anyone or send it to the front-end!

Additional Information

Handling Guest Users

When a user is not logged in (guest users), user data object should be empty.

$userData = [];

For guest users, Hyvor Talk will show a login button which links to the given URL. If the signup URL is given, a signup button will also be shown. The given link will be opened in the parent browser window.

Tip: For the login and signup URLs, use ones that redirects back to the same page after the action. Ex: https://example.com/login?redirect=start_page_url.

Reloading Hyvor Talk

hyvor_talk.reload(obj) function can be used to reload the plugin. (see javascript API). Here obj.sso you can set a new SSO login. For example, if the user logs in from the same page, you can change the obj.sso and reload the plugin. Make sure to generate hashes in the back-end using AJAX.

Related Articles