Vanilla Forums: Community Forums Evolved
Addons Community Documentation Blog Download HostingStart Using Vanilla today

Vanilla Documentation


ProxyConnect (Basic Single Sign-On) Install Guide

Vanilla 2 & Garden are all about integrating with existing applications. We recently released our first single sign-on integration with WordPress, made 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.

Ready to get going with ProxyConnect?

Download ProxyConnect Now

Installing

Installation is a 3 step process. Step 1 is to install the ProxyConnect addon in Vanilla. Step 2 is to configure/install the complimentary plugin or code within your remote application. Step 3 is to configure the ProxyConnect addon in Vanilla using the values provided by the complimentary plugin in your remote application.

Installing ProxyConnect in Vanilla

Simply copy the ProxyConnect/ folder into your vanilla/plugins/ directory on your web server. This will be enough to cause the ProxyConnect plugin to appear in the list of available plugins on your Dashboard.

Installing the WordPress Plugin

We currently have a custom plugin for WordPress. To get up and running, copy the WordPress plugin from the external/ folder into the wp-content/plugins/ folder in WordPress. Then enable it from the WordPress dashboard. From then on, just follow the instructions on the WordPress addon's settings page itself.

Not using WordPress?

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. Vanilla uses an HTTP GET request with the page. The information should be in the following format:

UniqueID=1279
Name=Tim
Email=tim@emailaddress.com
TransientKey=02742kjd2820
DateOfBirth=1970-01-01
Gender=Male

Important: If the user is not signed in, your user information page should remain completely 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.

About the response format:

  • The response is sent as plain text using the HTTP transport. It is not sent as an HTML page. The response should not include HTML tags such as <html>, <body>, etc.
  • A newline character, \n, is used as a record separator. Do not use the HTML line break tag, <br />.
  • The response should start at the beginning of the HTTP protocol's body section.

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). The user has an active session with your application: Information should be returned by the user information page. Vanilla will look in its 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. The user is not signed into your application:Vanilla will display its home page for guest users to the user since the user is not signed-in to Vanilla at this point. The page includes [Sign In] and [Register] buttons.

Signing-in from Vanilla

Two options are available for the sign-in process. The first requires fewer changes to your application:

  • The user presses the [Sign In] button on Vanilla.
  • Vanilla redirects the user's browser to your application's sign-in url configured in the ProxyConnect settings.
  • Your application displays its sign-in page.
  • The user fills in your application's sign-in form and submits it to your application.
  • Your application signs-in the user. Your application displays its usual home page to the user.
  • The user reloads the Vanilla Forum page and will now be signed-in to Vanilla

The preferred optionis for your application to redirect the user back to Vanilla. This technique provides a much smoother user interface flow to the user:

  • Same as above. Then...
  • Your application signs-in the user. Your application redirects the user to the Vanilla Forum page
  • (In the background), Vanilla queries your information page.
  • Vanilla receives a positive response from your application.
  • Vanilla automatically signs-in the user and displays the user's Vanilla home page to the user.

How does your application know to redirect the user back to Vanilla after signing in the user?Either of two methods can be used:

  • You can add a query parameter to your sign-in url. Eg, enter http://myapp.com/login?vanilla=1 as the sign-in url in the ProxyConnect settings.
  • You can add a new login page to your application. Your application will then know that a request for the new login page indicates that the user came via Vanilla and should be re-directed back to Vanilla after signing in. The page should have the look and feel of your application. Remember that the user's model should be that they sign-in to Vanilla via your application.

Integration Examples

Code samples describing how to integrate Vanilla Proxy Connect with different types of applications.

Known Issues

Vanilla 2.0.14 has a known issue which affects Proxy Connect. You can patch your version of Vanilla. Patch instructions. Issue report.

Finishing Touches

Once you've completed the steps above, sign out of Vanilla and then click the Sign In button again. If everything is set up correctly, you should land up on your remote application's login page. Log in with your admin account there. Upon successful login, you should be sent back to Vanilla and be prompted with a 'Sync Screen' (first time), or your Vanilla home page (subsequent signins). Using the "Link my Account" section, log into Vanilla with your original Vanilla Admin Account (created when you first made your forum). After logging in, your Vanilla admin account will be linked to your remote site admin account.

Ready to get going with ProxyConnect? Download ProxyConnect Now

Here is a video (sorry, no audio on it yet) of the entire process in action:

Edited June 2011 by Tim