Integrate Vanilla Forums with SSO in a PHP Website

By Vipul Kapoor - June 26, 2017

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.

Use the generator to generate a Client Id and Secret Key.
Site Name: Example
Authentication URL: http://www.example.com/includes/vanilla.php
Sign In URL: http://www.example.com/login.php?src=vanilla
Registration URL: http://www.example.com/login.php?src=vanilla
Sign Out URL: http://www.example.com/includes/sign-out.php
Check options of Trusted Connection and Make Default
Use SHA1 as your hash algorith and Uncheck Test Mode
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();

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(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);

<?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: ../');

<?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.

Vipul Kapoor

I'm the Head of Operations and Project Manager at BWD MEDIA. I love front end development and occasionally write about it.

One thought on “Integrate Vanilla Forums with SSO in a PHP Website”

LOKENDRA RATHOUR March 14, 2018 at 8:34 am

Hi Vipul –
I am completly failing to integrate the same to my website
my project is codeignitor
and I am putting this forum button only for the logged in user and want user to login / get registered as soon as s/he clicks on that button .
I have tried all possible way as marked above but luck for me .
thanks in advance for help ..

Reply