Howdy, Stranger!

It looks like you're new here. If you want to get involved, click one of these buttons!

Try Vanilla Forums Cloud product

Ready to contribute?

Amazing! Sign our contributors' agreement and then join us on GitHub.

Update for critical security issue in PHPMailer included in release Vanilla 2.3.1

Implementing SSO using jsConnect 1.4.1 with Vanilla - Part I

If you're implementing Vanilla on your own website, then you probably want to take advantage of Vanilla's single-sign-on functionality and deploy in an embedded format. This configuration allows Vanilla to integrate seamlessly with your site, but as noted elsewhere, there are a few bugs in the latest version of jsConnect (1.4.1) and deploying this plugin is not exactly intuitive. Furthermore, once you get the jsConnect plugin running, you'll likely find a number of Vanilla features, like direct user registration through Vanilla, that you'd like to turn off or otherwise control in a way other than the standard Vanilla presentation. This tutorial provides a detailed account of how I deployed jsConnect 1.4.1 using embedded Vanilla on

As I walk through the tutorial, make note of the fact that I installed Vanilla in a subfolder called 'forum'. I will refer to specific code line numbers, but in some cases I added short code snippets and so the line numbers I cite might not be exact but the code in question should be within just a few lines of the number cited. I will assume you have a moderate level of PHP and MySql experience. Feel free to ask questions but I reserve the right to ignore those in need of too much hand holding. You'll see that I added comments beginning with //sblaine in each instance where I edited the native Vanilla files. I recommend you do the same so you can easily find these edits later when you upgrade to a newer version of Vanilla.

1. Deploying jsConnect 1.4.1

1.1 Cleaning up jsConnect 1.4.1 bugs

Once you install the plugin, you'll need to modify 2 files as follows:

File: forum\plugins\jsconnect\functions.jsconnect.php
Line 1: //if (!defined('APPLICATION')) exit(); //sblaine commented out this line

File: forum\plugins\jsconnect\class.jsconnect.plugin.php
Line 1: //if (!defined('APPLICATION')) exit(); //sblaine commented out this line
Line 483: //$Form->ValidateRule('AuthenticationKey', 'regex:^[a-z0-9_-]+$i', T('The client id must contain only letters, numbers and dashes.')); //sblaine commented out this line to avoid Regex error
Line 490: $Values = ArrayTranslate($Values, array('Name', 'AuthenticationKey', 'URL', 'AssociationSecret', 'AuthenticateUrl', 'SignInUrl', 'RegisterUrl', 'SignOutUrl')); // , 'IsDefault' //sblaine removed 'IsDefault' value to avoid database write error

The regex error (Line 483) seems to be a problem with the formatting of the regex expression, so you could correct the regex formatting, but I chose to simply skip the validation altogether. Just make sure your client ID contains only numbers, letters and dashes. I allowed Vanilla to suggest a client ID and it contained only numbers.

1.2 Create your jsonp authentication file

I started with the PHP client library provided on Github ( and modified the 'index.php' file accordingly to suit my needs. Note that when a user logs into my site, I save 3 cookies for the userID, username and email address of the user. I also allow my users the option of uploading a profile image. These 4 pieces of information are supplied to Vanilla through the '$user' array.

Note that the very last line in the file is needed if you are deploying Vanilla in an embedded format. I recommend you test in full page mode first, then add this line and test again once you've deployed the embed plugin.

File: sso-auth.php

<?php require_once 'forum/plugins/jsconnect/functions.jsconnect.php'; require_once('includes/database_tc1.php'); require_once('includes/functions.php'); require_once('includes/initialize_settings.php'); // 1. Get your client ID and secret here. These must match those in your jsConnect settings. $clientID = $setting['vanilla_client_id']; $secret = $setting['vanilla_secret']; // 2. Grab the current user from your session management system or database here. $signedIn = isset($_COOKIE['signed_in_id']); // prepare image file for display $url_prefix = $setting['site_full_url']; $test_imgfile_path = $setting['profile_img_dir'].$_COOKIE['signed_in_id'].$setting['profile_img_ext']; if(file_exists($test_imgfile_path)) { $imgfile_path = $url_prefix.$test_imgfile_path; } else { $imgfile_path = $url_prefix.$setting['profile_img_dir'].'blank-user.png'; } // 3. Fill in the user information in a way that Vanilla can understand. $user = array(); if ($signedIn) { // CHANGE THESE FOUR LINES. $user['uniqueid'] = $_COOKIE['signed_in_id']; $user['name'] = $_COOKIE['signed_in_user']; $user['email'] = $_COOKIE['signed_in_email']; $user['photourl'] = $imgfile_path; } // 4. Generate the jsConnect string. // This should be true unless you are testing. // You can also use a hash name like md5, sha1 etc which must be the name as the connection settings in Vanilla. $secure = 'sha1'; WriteJsConnect($user, $_GET, $clientID, $secret, $secure); // for full page forum JsSSOString($user, $clientID, $secret); // add this line if using an embedded forum (remove if not embedded) ?>

1.3 Setup jsConnect connection within your Vanilla Dashboard

This is fairly straightforward, so I'll just give you a screenshot of the end result for my site. Note that I've elected to use the 'sha1' hash algorithm and this is consistent with the '$secure' parameter in my authentication file above (3 lines up from bottom). Note too that the checkbox for 'Make this connection your default sign in method' will not work due to the 'IsDefault' bug we corrected in section 1.1 (Line 490).

1.4 Test connection and deploy if desired

Once you've saved your jsConnect settings in your dashboard, use the 'Test URL' link to evaluate the results. If all is working well and you'd like to embed your forum, modify your authentication file to add in the jsSSOString call (the last line of code in section 1.2) and test again. If these tests are failing, verify that your security settings are consistent between your authentication file and the jsConnect dashboard hash setting (I use sha1 everywhere).

Now you're ready to test SSO on your site. Enable the plugin, if desired, log out of your Vanilla dashboard and navigate to your forum (note that I assume you've already set up a page on your site with the forum embedded). If you are not logged into your website, you should see a button inviting sign-in through your website. If you are logged in, you should see your username, photo (if supplied) and a link to sign-in through your website. Try signing into your site and then into Vanilla. If all works properly, you'll probably notice some things that look odd and some options will appear that you might not want to offer to your users. I'll address those in Part II.

I hope you find this tutorial useful. I'd like to thank the Vanilla Forums development staff for a great product. Please, keep up the good work.


Steven Blaine, Ph.D.



Sign In or Register to comment.