Integrate Vanilla Forums with SSO in a PHP Website

You have a php website and you decided to add a forum section to it and you picked Vanilla Forums for the purpose. As awesome as it is, especially for running on PHP 7 (the only one currently) you need a way to log users in seamlessly across your website and forums. I mean you can not ask your users to make two accounts on the same website and sign in separately for your website and forum? That would be absurd.

Vanilla’s Single Sign On (SSO) remedies this exact problem. It syncs user data across your website and forums so the user doesn’t have to create another account on the same website. To know how it works you can read about it on Vanilla’s Documentation Site. We’ll go straight in to the action! To do that, we’ll use Vanilla’s jsConnect plugin so, let’s get that first.

Download jsConnect plugin

Let’s assume a folder structure like the following to make things easy to understand. Then you can adapt it easily to your situation:
Home Page: www.example.com
Forum Home Page: www.example.com/forums

I also assume that you have the standard installation of Vanilla installed and configured already. If not, do so by downloading the forum software from the official website. Once you have the forum ready, you have to upload the jsconnect plugin to www.example.com/forums/plugins  and extract it. You should a folder like so

www.example.com/forums/plugins/jsconnect

Go to the plugins page of the forum dashboard and you should see the plugin listed there. Enable it so a yellow background appears on it.

Now go to Users > Registration and check the box to select “Connect” as the preferred registration method.

Next go to Users > jsConnect and click Add Connection. Here, we’ll configure our plugin.

1. Use the generator to generate a Client Id and Secret Key.
2. Site Name: Example
3. Authentication URL: http://www.example.com/includes/vanilla.php
4. Sign In URL: http://www.example.com/login.php?src=vanilla
5. Registration URL: http://www.example.com/login.php?src=vanilla
6. Sign Out URL: http://www.example.com/includes/sign-out.php
7. Check options of Trusted Connection and Make Default
8. Use SHA1 as your hash algorith and Uncheck Test Mode
9. Click Save

Registering New User

Imaging a scenario where the user is on your website and clicks the forum link to visit the url www.example.com/forums . He is neither signed into your site, nor the forums so he should be looking at a generic message requesting him to sign in or sign up.

Both these links correspond to the links we entered earlier in Sign In Url and Registration Url. Lets assume that the user clicks on Register button and lands on http://www.example.com/login.php?src=vanilla . I personally have the same page for Sign In and Sign Up but if you have different pages, you should enter different Urls above. Notice I’ve added a parameter to identify the user as coming from forums and not any other place. There’s nothing fancy about the sign up here, sign him up as you do and redirect the user back to the forums

if(isset($_POST['vanilla']) and $_POST['vanilla'] == 1)
    header('location:forums/sso');
else
    header('location:thanks.php');
exit();

Notice we’re sending them to /forums/sso  and not forums/  because that would not log them in automatically and another step would be required. When a user visits this url, vanilla automatically pings your authentication url to ask for authentication of the user. (more on that later)

Login User

In another case, lets say the user has already registered on your website and clicks the Login button. They’ll be taken to the Login page (which in my case is the same as registration page). Again there is nothing special to be done here, just log your user in and send him back to the forums. This is the contents of http://www.example.com/login.php?src=vanilla

if(isset($_SESSION['user'])){
        //user is logged in
	if(isset($_GET['src']) and $_GET['src'] == 'vanilla')
		header('location:forums/sso');
	else
		header('location:index.php');
	exit();

} elseif(isset($_POST['signInSubmit'])) {
        //Login form submitted. Process form
	if(isset($_GET['src']) and $_GET['src'] == 'vanilla')
		header('location:forums/sso');
	else
		header('location:index.php');
	exit();
}

If the user is logged in and I have the src  parameter, I’ll send him to the forum endpoint, else he is probably logging in from the website so I send him to the homepage.

Vanilla’s Endpoint

And finally we have our SSO endpoint which vanilla calls automatically whenever it needs to check for authentication of the user. This is your authentication url: http://www.example.com/includes/vanilla.php  and we’ll create this file now. But before that we need another file which is a client library of jsConnect for php. Download the library from github, we only need one file that is functions.jsconnect.php  and place it in our includes folder.

Here’s how the vanilla.php looks like:

<?php
require_once 'functions.jsconnect.php';
require_once 'config.php';
// 1. Get your client ID and secret here. These must match those in your jsConnect settings.
$clientID = "xxxxxxxxx";
$secret = "xxxxxxxxxxxxxxxxxxxxxxxxxx";

// 2. Grab the current user from your session management system or database here.
if(isset($_SESSION['user']))
	$signedIn = true;
else
	$signedIn = false;

// 3. Fill in the user information in a way that Vanilla can understand.
$user = array();

if ($signedIn) {
   // CHANGE THESE LINES.
        $user['uniqueid'] = $_SESSION['user']['id'];
	$user['name'] = $_SESSION['user']['name'];
	$user['email'] = $_SESSION['user']['email'];
	$user['username'] = strtok($user['name'], ' ').$user['uniqueid'];
	$user['photourl'] = SITE_URL.'/images/users/'.$_SESSION['user']['avatar'];
}

$secure = 'sha1';

$log = fopen('log.txt', 'a');
fwrite($log, date('Y-m-d h:i:s')." - Get variables: ".serialize($_GET)."\r\n");
WriteJsConnect($user, $_GET, $clientID, $secret, $secure);

Fill in your client_id and secret from the jsConnect settings page. Here you check if the user is logged in or not. If they are, you create an array $user  with above mentioned five parameters and feed it into a function WriteJsConnect() . This function is defined in the library file. You don’t have to do anything there.

If the user is not logged in, we send a blank array to the same function which gives an appropriate response to vanilla. Don’t ask your user to login here. There’s absolutely no user interaction from this file.

I’ve also included two lines to log the GET  parameters to a file. Since this file runs completely in background, this is the only way to see what input we’re getting from Vanilla. You can also modify the library file to log output to the same file as well. This is just for debugging purposes.

The function can produce a variety of responses based on the authentication level of the user on your site and react accordingly. You can read these responses here.

And that’s it. The login should be working fine now.

Loggin in a Logged In User

If the user has already logged in on your site and visits the forum, Vanilla will ping your auth url and get a half authenticated response. This will look like this to the user:

Notice you get the user image and the name of the user (Super Admin) but nothing else. There is a link that says “Sign in with Example”. Example being the Site Name from the jsConnect plugin setting page. If you click on it, Vanilla will ping the /sso  endpoint with authentication and it’ll get a full response back. This will log the user in automatically.

You can skip this step if you modify your forum url in the navigation from www.example.com/forums  to www.example.com/forums/sso  but the caveat is, if the user is not logged in, he is taken to the login page. I believe this hampers the user experience a bit so I decided to keep the 2 step login. It’s up to you.

Signing Out

Now that the user is able to login, lets make sure he can logout from both your website and the forums. If the user clicks on the forum signout link, Vanilla will sign him out of the forum and send him to your Sign Out link (http://www.example.com/includes/sign-out.php ) where he gets signed out of your website as well. But if the user clicks on the Sign Out link on your website, they will not get logged out of  the forums. To fix that, just modify your sign out links to point to www.example.com/forums/entry/signout .

With this Url, the user will be signed out of the forums and then sent to your usual signout link to sign him out of your website. It looks like this for me:

<?php
require 'config.php';
mysqli_query($connect, "UPDATE `users` SET `last_logout` = '".NOW."' WHERE `id` = '".$_SESSION['user']['id']."'");
unset($_SESSION['user']);
if(isset($_COOKIE['session'])){
  setcookie('session', null, -3600, '/');
  unset($_COOKIE['session']);
}
session_destroy();
header('location: ../');

And that’s  it. You now have a fully integrated Vanilla Forums on your hands. If you like it, please share it with your friends and colleagues and leave a comment if you find anything confusing.