Single Sign-On Integration

Important: This documentation ONLY relates to Vanilla 2

Vanilla 2 & Garden are all about integrating with existing applications. We recently released our first single sign-on integration with WordPress, that is available from our addons site. There are a number of different methods for performing single sign-on with an external application, and this plugin represents just one.

Requirements

Cookie Setup

Vanilla will need access to your existing application's session cookies (note: Vanilla doesn't alter your application's session cookies in any way, nor does it do anything with the information they contain). This means that your application's cookies should be on the same domain as Vanilla, and should not be isolated to any subfolders that Vanilla does not have access to. If you are using PHP, the easiest way to ensure this is to create your cookies in the following manner:

setcookie("YourCookieName", $YourCookieValue, $YourCookieExpiryTime, '/', '.yourdomain.com');

By setting the second-last argument to '/', you are ensuring that your cookies are based off the root folder of domain.com, and by setting the final argument to ".domain.com", you are ensuring that the cookie will be accessible from any part of your domain, even subdomains like sub.domain.com. Read this for more documentation on PHP's setcookie function.

When you destroy your cookies (ie. a user signs out of your application), you must also destroy Vanilla's cookies (ending the associated Vanilla session as well). Unless you have customized the vanilla cookie name, it will be "Vanilla", and can be destroyed like this:

setcookie('Vanilla', ' ', time() - 3600, '/', '.yourdomain.com');
unset($_COOKIE['Vanilla']);

Authenticate Url

You'll need to create a "user information" page in your application. This is a simple page that writes information about the currently authenticated user to the screen. The information should be in the following format:

UniqueID=1
Name=Mark
Email=mark@emailaddress.com
TransientKey=02742kjd2820
DateOfBirth=1975-09-16
Gender=Male

Important: If the user is not signed in, your user information page should remain blank.

About the user information values:

• UniqueID (required) is a value from your database (typically an integer) that is a unique representation of the user account.
• Name (required) is the "display name" from your system that will appear next to the user's comments and discussions in Vanilla.
• Email (required) is the user's email address.
• TransientKey (NOT required) is a value used to prevent CSRF attacks. In WordPress, this value is called the "wp_nonce". Not all applications have this value, and so it is not required.
• DateOfBirth (NOT required) is the user's birth date.
• Gender (NOT required) is the user's gender.

Enable the SSO Plugin in Vanilla

Using this plugin you can define the location of your application's sign-in, sign-out, registration url, and also the location of your "user information page" or "authenticate url".

How it works

When a user visits Vanilla for the first time, Vanilla will make a request to your user information page behind the scenes (the user will not see anything happening). If the user is not signed into your application, Vanilla will not do anything. If the user does have an active session, and there is information returned by the user information page, Vanilla will look in it's database to see if the user has a related account. If the user does have a related account, it will sign the user in. If the user does NOT have a related account, Vanilla will create one and sign the user in.

Finishing Touches

When Vanilla 2 is first installed, it creates an administrative account with full admin capabilities. In order to make sure that your related account in your existing application maps to this admin account, you will need to update the "UniqueID" field in Vanilla to relate to the appropriate UniqueID in your application. So, find the unique id of the admin user in your application, and update Vanilla's user authentication table accordingly:

insert into GDN_UserAuthentication (UniqueID, UserID) values ($YourAdminUsersUniqueID, 1);

Powered by Vanilla