The jsConnect addon has a special way of supporting SSO for embedded sites. To do this, you will have to use a specially formatted SSO string and pass it to your embed. This document deals only with how to seamless log in users into Vanilla forums embedded in iFrames. For all other SSO using jsConnect see this document.
NOTE: We are making a patch so that this will work with JSConnect V3.
What You'll Need
Before you start, you'll need the following:
- A jsConnect connection on your community. Make a note of your secret because you'll need this to format your SSO string.
- You will need to generate your SSO string on your server. This will be done on the page where you embed Vanilla.
- Your server will also have to know the current user. You'll need information such as the user's ID, username, and email.
- You will need a forum or comment embed code. You can get this in your dashboard under settings/embedding.
Generating Your SSO String
You must generate your SSO string on the server, even though you will be generating a client-side SSO string. Here is an example in PHP:
$user = [
'client_id' => 'Your jsConnect Client ID',
'uniqueid' => '',
'name' => 'Name',
'email' => 'Email',
'photourl' => 'Photo',
'roles' => 'Roles',
];
$string = base64_encode(json_encode($user));
$timestamp = time();
$hash = hash_hmac('sha1', "$string $timestamp", $secret);
$sso_string "{$string} {$hash} {$timestamp} hmacsha1";
You need to take this string and add it to your output page inside a script tag like this:
<script>
vanilla_sso = "<?php echo $sso_string; ?>";
</script>
Below this script tag you would put your embed code which will read the vanilla_sso variable and use it to sign your user in.
Trouble shooting
As of release 2020.014, For jsConnect version 3 only. In your Vanilla dashboard, in the jsConnect addon, click on Test. On the Test page you will find a sample jsConnect sso_string for the user that you are logged in as. You can compare it to the one you have generated or you can temporarily paste it manually into the page that you are using to embed the forum. TEMPORARILY because anyone who visits that page will be logged in as you. Please exercise caution.
Gotchas
Here are some issues you may run into when trying to get embedded SSO working:
- Make sure not to output an SSO string if there isn't a user signed in on your site.
- When using embedded SSO, users will not receive a welcome email. This is to provide as seamless an experience as possible. We assume your site has already welcomed the user and they shouldn't think they are signing up to another site.