Integrating Stateless SSO

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

Requirements

• A Hyvor Account with a business subscription (or 14-days trial enabled).
• Access to the back-end of your website.
• A developer to write the back-end code.

Here we assume you have already installed Hyvor Talk on your website. After that, go to the Single Sign-on section of the website, turn on SSO, and choose SSO Type Stateless. Then, copy the private key. We will use it in the next steps.

This guide explains how to configure SSO when you have access to your back-end. If you are using a website builder or CMS, and have no access to a back-end, we may have guides for you on our blog. If not, please contact us via the live chat.

Writing the back-end code

When the comments embed load, you have to send currently logged in user's data with a hash. Let's see how to send this data and hash.

User Data Object

{
    id: 1,
    name: "Example User",
    email: "[email protected]",
    picture: "https://example.com/picture.png",
    url: "https://user.com"
}

(The name will be truncated 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, and easy to handle programatically.
• 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)

Check this repository for helper functions written in other languages.

<?php declare(strict_types=1);
$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);

Setting up sso object in the installation code

Now, add the sso object to your installation code.

SSO Object

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!

Handling Unauthenticated users

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

$userData = [];

For those users, Hyvor Talk will show a login button that links to the given URL. The given link will be opened in the parent browser window.

Tip: Use a login URL that redirects back to the same page after the action. Ex: https://example.com/login?redirect=start_page_url.

Login Modals

You may show a modal instead of redirecting the user to a login/signup page. First, set sso.loginURL and/or sso.signupURL to true. Then, use onEvent callback to open the modal.

var HYVOR_TALK_CONFIG = {
    // ... other configs
    sso: {
        hash: "<?= $hash ?>",
        userData: "<?= $encodedUserData ?>",
        loginURL: true,
        signupURL: true
    },
    onEvent: (type) {
        if (type === 'sso-login') {
            openLoginModal();
        } else if (type === 'sso-signup') {
            openSignupModal();
        }
    }
}

You may also need to reload Hyvor Talk when the user logs in. Use the hyvor_talk.reload(obj) function for that (see javascript API). Here you can set a new SSO login using obj.sso. Make sure to generate hashes in the back-end using AJAX before reloading.

Troubleshooting

After setting up SSO, you may run into errors. Usually, the errors are shown in a red box.

Here are some possible errors.

If the issues persist, you can contact us via the live chat if you need help.