Vanilla Single Sign-On Integration
Important: This documentation ONLY relates to Vanilla 2
Description
Vanilla 2 & Garden are all about integrating with existing applications. We're committed to opening up doors for you and your users so that interacting on your forum is as easy and enjoyable as possible. To that end, we have several different ways for you to leverage your existing userbase (be it on a blog like wordpress, another forum, or even a custom in-house application that you've developed yourself). The following document is intended to provide you with a good high level overview of each of our SSO offerings, with links to more in depth documentation.
Before you start...
Throughout this document I'll be referring some fictional sites hosted at the fictional domain 'example.com' to illustrate my points. Your fictional forum will be accessible at http://forum.example.com (hereafter "Your Forum") and your remote application (to which you want to connect via SSO) would be accessible at http://www.example.com (hereafter "Your Website").
Lets say you've got a WordPress blog (or indeed any software with user management capabilities) installed at http://www.example.com. You've had this blog for a couple of years and the blog keeps track of quite a few regular users. You've decided to deploy a Vanilla forum at http://forum.example.com to encourage your users to interact more and to give them additional reasons to come back to your site. You're visiting this page because you want to know how to make it as easy as possible for your existing users to enjoy your new forum software without hassles.
For the purposes of this document, lets say that the user accessing these sites can be identified by their username "Bob", and their email address "bob@example.com".
jsConnect
jsConnect is Vanilla's latest single sign-on solution. It works using javascript and can function cross-domain and with any cookie configuration. You can find the jsConnect documentation here.
ProxyConnect - Basic SSO
ProxyConnect is our most basic method of SSO integration and has certain limitations. On the other hand, it is also by far the simplest to set up and maintain. If you're already familiar with ProxyConnect, perhaps you're looking for the Technical Installation Documentation?
How it's supposed to work
In this section, we'll pretend to follow 'Bob' as he uses ProxyConnect to log into both Your Site and Your Forum using just one set of credentials.
When Bob logs into the software at Your Site he should be assigned a HTTP cookie (formatted however your app likes) that identifies him on future page requests. Each time Bob requests a page on Your Site, his web browser helpfully (and automatically) sends this cookie along with the request. Your Site recognizes this cookie and knows to keep him signed in as "Bob".
When Bob visits Your Forum, ProxyConnect will have access to his entire list of cookies, including the one(s) from Your Site. ProxyConnect reads that list (name + value pairs) and stores it temporarily. Remember, this is all happening lightning fast in the background, before the first page even loads for Bob. Here's where it gets clever and a little bit tricky. ProxyConnect (using information you provide to it during setup) makes a request to Your Site. During that request, it sends the aforementioned list of cookies just like Bob's browser would have done. This lets ProxyConnect pretend to be Bob for this one request. Your Site should then behave as if the Bob himself had visited it. ProxyConnect uses this privileged status to request Bob's UserID, Email Address and Username from Your Site. Once ProxyConnect has this information it checks whether a user with Email Address "bob@example.com", from Your Site, has been here before. If they have, we'll have a record of that and we'll be able to log him in without any prompts.
His experience is seamless: log in on Your Site, visit Your Forum, automatically logged in. If, however, he has never been to Your Forum while already logged into Your Site, we'll need to lay some groundwork so that we can log him in. ProxyConnect looks at his username and email address and tries to create an account on Your Forum with those same details. If this works (email address and username are not already in use), Bob gets the same experience as we described above: log in on Your Site, visit Your Forum, automatically logged in. ProxyConnect has createed their account silently and automatically, and remembers that it is "connected" to the credentials that we gathered from Your Site. Next time Bob comes to Your Forum, we'll sign him back into this same account. If Bob's email address is already in use on Your Forum though, we have to do things a little differently. Before we get into that, consider the reasons for this situation to have occurred. Either Bob already has a pre-existing account on Your Forum which he managed to create before you decided to use a SSO product (maybe you've had this forum for a while too, and only recently decided to enable SSO), or Bob is using an email address that someone else has used. That shouldn't happen often, of course, but it is possible. Either way, ProxyConnect has to ask Bob for help now. Bob will see a screen that looks a lot like this:
Bob has a choice to make now.
1) He can create a brand new account by entering a username and email address pair that is not yet in use on Your Forum, or 2) He can provide the password for the existing account that blocked him in the first place. This is the equivalent of Bob telling ProxyConnect: "Hey, that account actually belongs to me, I'll prove it by entering the password."
In either case, ProxyConnect is able to associate Bob's credentials on Your Site with an account on Your Forum. As a result, Bob can be logged into Your Forum now, and in the future he will be logged in automatically just like in the other cases above.
How do we do it?
The real "magic" of ProxyConnect lies in what we refer to as the Authenticate URL. When you set up ProxyConnect for the first time on Your Forum, you'll be asked to provide an Authenticate URL. This URL points to some custom code on Your Site that, when accessed by ProxyConnect, must provide output that describes the currently logged in user. Remember, when ProxyConnect requests a page from Your Site, it does so in a way that allows Your Site to behave as if Bob himself were viewing the page. The Authenticate URL should output the following pieces of information, formatted exactly as shown:
UniqueID=1279 Name=Bob Email=bob@example.com TransientKey=02742kjd2820
UniqueID - This is Bob's internal database ID on Your Site. Most user management systems have some unique identifier that represents their users and it is usually a number.
Name - This should be Bob's username on Your Site. Depending on Your Site's software, this might be Bob's real name, his "handle", or something else. ProxyConnect will try to use this value as a Username when creating Bob's account on Your Forum.
Email - This is relatively self explanatory. Bob's email address. The other 3 fields are currently optional. TransientKey bears some explanation, however.
TransientKey - Some software packages such as WordPress have an added layer of security in the form of a special "key" that must be provided when users submit forms or attempt to log out. This value is passed back and forth between the user's browser on each page request (a process that is transparent to the user himself) and the software checks that the user's browser provides the right value each time. This precaution ensures that when the user tries to do something like log out, that they really intended to do so and were not tricked into following a link but someone malicious. ProxyConnect can adopt Your Site's TransientKey when your users log in. This makes the Bob's experience seamless and prevents him from reading and dealing with annoying nag messages like "Are you sure you want to log out?".
Important: If the request does not match up with a "signed in" user, your Authenticate URL page should remain completely blank.
Limitations of this method
ProxyConnect is extremely simple and easy to get going. The downside, however, is that it is currently limited to connecting sites on the same domain. In this document, your sites are both hosted on the fictitious domain "example.com", so everything works fine. If Your Site was hosted on a different domain than Your Forum, however, ProxyConnect would be unable to access Bob's cookies from Your Site when he arrived at Your Forum. This is a limitation (rather, a security mechanism) imposed by the HTTP specification itself, not ProxyConnect. If your sites are both hosted on the same domain, the only caveat is that both Your Site and Your Forum must create cookies using the same "Cookie Domain" value, and a liberal "Cookie Path". In order to explain this in more detail, consider the raw syntax used by the HTTP specification to set a cookie:
Set-Cookie: CookieName=CookieValue; expires=Fri, 31-Dec-2020 23:59:59 GMT; path=/; domain=.example.com
Cookie Domain - The ideal value for this is ".example.com", as reflected in the example above. When a web browser sees a Cookie Domain such as the above, it reads it as: "this cookie is valid for any domain name ending in '.example.com'". www.example.com, forums.example.com, admin.example.com... these all match. Cookie Path - The ideal value for this is "/". The Cookie Path allows cookies to be assigned and retrieved only for specific sub-pages of a domain. For example, if your administrative interface was access via the "/admin/" subfolder of your www.example.com site, a cookie that gave you access to this area might use a Cookie Path of "/admin". For ProxyConnect, however, you'll need to set your login cookie's Cookie Path to "/".
And that's how ProxyConnect works! If you'd like to read more technical, hands-on information about how to get ProxyConnect up and running on your forum, or to download ProxyConnect, check out the ProxyConnect Documentation Page.
| Edited February 2012 by Todd |