Integrating Single Sign-on with Hyvor Talk

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

Requirements

  • A Hyvor Account with premium or unlimited 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 and click "Create new SSO ID". (Name is only a reference for yourself).
  • Then, you will see the newly created SSO ID and the Private Key.

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

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 The ID of the SSO ID created in the first step. integer required
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: {
        id: YOUR_SSO_ID,
        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 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.

Moderating SSO-enabled websites

As mentioned in the introduction, all the moderators should have a Hyvor account to moderate comments.

When the user is logged in from both SSO and Hyvor

Usually moderators logs in with both accounts (maybe other users too). In this case, the user can choose what account to use to comment. The default is the SSO profile. However, moderators should use their Hyvor account when commenting and replying. The MOD tags are only shown for Hyvor accounts.

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