jsConnect Single Sign On

jsConnect is Vanilla's new single-sign-on library. It enables Vanilla users to authenticate with your site even if your site is on a different domain than your forum.

Installation

In order to get jsConnect working you have to do the following:

1. Configure the authentication url on your site.
2. Install the jsConnect plugin.
3. Secure the jsConnect connection.

Configure the Authentication Url on Your Site

You need to program a page on your site that gives out information on the currently signed in user. We've provided some client libraries to help you with this. If you choose to use a client library, you can ignore the rest of this documentation as it simply describes what the client library will do.

If you need to program your jsConnect page yourself, and the client libraries will not work for you: The easiest way to get your authentication url going is to download a client library and modify the example page that comes with it. If you want a deeper understanding of what's going on or your site is programmed in a language that we don't provide a client library for then keep reading.

The basic format of the page is as follows:

callback({
    "uniqueid": "1234",
    "name": "John Doe",
    "email": "johndoe@noreply.com",
    "photourl": "http://nosite.com/johndoe.png"
});

This might look like a javascript call to you and that's because it is called by javascript to work. Let's go through the parts one by one:

• callback: You don't actually put the word "callback" here. That's because this is actually used with a technology called jsonp. What you have to do is look at the querystring for a parameter called callback. Use the value of that parameter. So if the page requests ?callback=foo then your page should generate foo({...});
• uniqueid: The unique ID of the user in your system. This value should never change for the user and is usually an automatically generated number or guid.
• name: The username of the user that identifies them on the page.
• email: The user's email address.
• photourl: This is a url to the user's photo or avatar. If your system doesn't use photos than you can make this an empty string. You might want to give a link to a small 32x32 pixel logo of your site so that something shows up beside the user.

What if there isn't a user signed in to your site?

If the user isn't signed in to your site then you should give the following response.

callback({"name": "", "photourl": ""});

Install the jsConnect Plugin

The jsConnect plugin is installed just like any plugin in Vanilla. Once you install the plugin you will see a jsConnect menu item in your dashboard. Here is where you add your connections. The add/edit page looks like this:

There are descriptions of each field on the page, but I'll give some additional insight here:

• Client ID & Secret: These values uniquely identify your site and secure the connection. You almost always generate these by clicking Generate Client ID and Secret at the bottom of the page.
• This connection is in test-mode: You can check this box if you are trying to test to see if your sign-in works. This will disable the client ID and secret security check. Once you have the client ID and security set up then make sure you check this box.
• Authenticate Url: This is the url of the page you made in step one that serves the jsonp user information in the format specified above.

Once you have your connection set up you are ready to go.

Secure the jsConnect Connection

Once you have your single sign on setup in test-mode you should now secure the connection on your end. This involves using the client ID and secret to sign the responses sent from your site so that Vanilla knows that it's the right site sending the information. Hopefully you've done this with one of our client libraries. If not then you'll have to do it yourself.

jsConnect Client Libraries

While writing the client code for jsConnect is pretty straightforward, it can be a little bit difficult to secure the connection. Because of this we provide client libraries for four of the more popular languages. All of these libraries are open source and maintained on github:

• PHP jsConnect client library
• Ruby jsConnect client library
• Java jsConnect client library
• .NET jsConnect client library

All of these libraries have one file with all of the library code you'll need and one file that gives an example usage. They also have a readme that tells you which file is which.