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"
}
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 |
Absolute URL of the user's profile picture | string |
optional | 1024 |
url |
Absolute URL of the user's profile or website | string |
optional | 1024 |
(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
Key | Description | Type | Status |
---|---|---|---|
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, true |
required |
signupURL |
The signup URL of your authentication system | string, true |
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!
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.
Error Message | Fix |
---|---|
SSO hash, loginURL, or userData is empty | Recheck the sso object in the installation code. |
SSO hashes do not match | You have generated an invalid hash from the server-side code. Recheck it. |
If the issues persist, you can contact us via the live chat if you need help.