Embedding with seamless JsConnect
Our technical overview explains how to set up JsConnect SSO for site-wide SSO. However, if you have Vanilla embedded in a page, you’ll notice that the SSO doesn’t automatically sign you in even if users are signed in to the containing page. In order to make the sign in seamless you need to add some SSO information to your embed code.
🛑 IMPORTANT: Attempting embedded SSO across two domains will not work in the Mobile Safari browser (and therefore, on all Apple devices).
To solve this, your Vanilla community must be hosted on a subdomain of your main site. For example, if your site is url.com, you could put your community on forum.url.com, and then embed it from there. This sidesteps Mobile Safari’s issue, and potentially increases your search engine value as well.
You can change your community to a subdomain of your site in the Dashboard by following the instructions on the Settings > Appearance > Custom Domain page.
Now, on to revising your embed code with some additional SSO information.
Vanilla embed code
Consider the embed code for Vanilla comments:
<script type="text/javascript">
/*** Required Settings: Edit BEFORE pasting into your web page ***/
var vanilla_forum_url = 'http://forum.example.com/'; // The full http url & path to your vanilla forum
var vanilla_identifier = 'your-content-identifier'; // Your unique identifier for the content being commented on
**var vanilla_sso = 'SSO STRING'; // Your SSO string.**
/*** DON'T EDIT BELOW THIS LINE ***/
(function() {
var vanilla = document.createElement('script');
vanilla.type = 'text/javascript';
var timestamp = new Date().getTime();
vanilla.src = vanilla_forum_url + '/js/embed.js';
(document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(vanilla);
})();
</script>
If you declare vanilla_sso and give it the proper value, then Vanilla will be able to sign in your user. To generate your SSO string:
- Start with the signed in user. This has the same fields as the user from the seamless setup.
- Add your client_id to the user so Vanilla will know how to identify you.
- JSON encode the user.
- Base64 encode the user in UTF-8. This is your signature string.
- Sign the signature string with your signature and the current timestamp using HMAC SHA1. Confirm the signature string is hex encoded.
signature = hmacsha1(signature_string + " " + timestamp, secret);
- Build your final sso string:
vanilla_sso = signature_string + " " + signature + " " + timestamp + " hmacsha1"
That’s it! The value of vanilla_sso from above is what you put in your embed code. Since this needs to be dynamically generated by your site, you cannot use SSO on a static page.
Considerations
- The above example is for blog comments. For a full community embed, use the code provided under “Forum Embed” in the Dashboard.
- Even though your signature string is base64-encoded, make sure the actual signature is hex encoded. The correct string will be 40 characters, consisting of the numbers 0-9 and a-f.
- The timestamp is a UNIX timestamp. That means it will be an integer representing the number of seconds since 1 January 1970. Most languages have a way of getting this timestamp.
- On your endpoint, make sure you're sending the correct document headers when serving JavaScript (
Content-Type: application/javascript; charset=utf-8 ) or do not include X-Content-Type-Options: nosniff . This will cause browsers to refuse to render the JavaScript and break the SSO workflow. The most recent versions of our client libraries serve the correct document headers (for more explanation see JsConnect Response Headers).