SSO (single sign on) systems are complex. Setting up your own SAML or OAuth system takes a lot of time, and generally is not feasible for small-to-medium business owners.
If you have a website that stores your user’s identity and the only thing you need to integrate is a forum, jsConnect is a far simpler solution. This is because we’ve abstracted most of the work to our side of the connection, and provide sample code for making your side.
However, even our easier solution does require a developer on your team. A developer can typically set up the client side of jsConnect in 2-6 hours using our technical documentation. The only exception is WordPress users, for which we’ve developed a ready-to-go SSO plugin.
Ready to learn more about jsConnect? Read on.
jsConnect Concepts Overview
Our SSO solution has a few basic assumptions:
- Your user is signed into a website.
- You control this website and can add files & pages to it.
The integration will be a lot easier and tighter if:
- You have unique, validated usernames for users.
- You have confirmed, unique email addresses for users.
Creating & mapping users
Data that can currently be passed over SSO with jsConnect:
- Unique ID from your system (required)
- Email (required)
- Username (recommended)
- Photo URL
- Roles (Vanilla’s permissions management groups)
When receiving an SSO response, Vanilla will do a lookup by email address against the forum database. If it finds a match and the user connects, a permanent mapping is made against the unique ID you provided. This means future email changes on your side do not effect the login process.
If no email match is found, a new forum account will be created instantly using the provided data. If no username is provided, the user will be prompted to create one.
Data is synced at every new login. For instance, providing a different email address on the user’s fifth login will still log them into the same account, but will update their Vanilla email address.
The Photo URL is accepted only if the user has not uploaded their own avatar in the forum yet, and it is a valid URL. Imported avatars (if you migrated to Vanilla from another platform) count as the user having uploaded their own avatar.
We strongly recommend against creating new users via the API. Our SSO solution lazy-creates new users for maximum robustness and reliability. Once a new user is created, you can optionally sync additional data about the user over API as needed.
Unified user experience
In Vanilla, these optional configuration changes are possible:
- Auto-connect to existing forum user accounts without prompting for a password (i.e. your SSO source is 100% trusted).
- Disable all email sending in Vanilla.
- Disable profile editing.
- Redirect user profile links to another system.
Cloud users can contact support to make these changes.
How it connects
Clicking the “Sign In” button in Vanilla generates an asynchronous request in the user’s browser session back to the main website. This means the user’s cookies are sent as if they had visited the page directly, and that your normal login detection logic will work.
Two Flavors of SSO
JsConnect supports two methods of implementing SSO. You can implement either of the methods or both, as they serve different purposes.
Method 1: Site-Wide SSO
You implement site-wide SSO when Vanilla is as a full site. With this method you need to create a page that provides your login information in JSON Web Token format.
Method 2: Embedded SSO
Vanilla also has the ability to be embedded in an HTML page either as an entire site or just as embedded comments. In this scenario, you need to create a special SSO string that can be passed to the embedded Vanilla and provide login information.
For JsConnect to work, you must put some code on your site that identifies your users in a way that Vanilla can understand. Vanilla then requests this information when the user wants to sign in and synchronizes the user with Vanilla. This is done by sending a signed JSON Web Token to obtain login information.
Vanilla’s web-based SSO has 2 parts:
- Your SSO endpoint (based on one of our example libraries) on your site.
- Vanilla’s JsConnect plugin.
JsConnect pings your endpoint whenever it wants to know if a user is logged in on your site. It does this using the user’s current session, so you can use your normal “is logged in” detection to determine this - nothing fancy here.
Your Endpoint & Client Libraries
Your endpoint needs to say 1 of 3 things when it’s called:
- The current user is a guest (not logged in).
- User is logged in here, but this wasn’t a secure request (no signature + timestamp), so here’s their name & photo only.
- User is logged in AND this was securely requested, so here’s all the user data (including email and a unique ID from your system, which are required).
Our example libraries help you structure the output so that jsConnect can read it correctly. We highly recommend using one of the following client libraries, if applicable.
These libraries are open source and maintained on Github:
Each library has 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. Please note that these libraries don’t support embedded SSO.
If your site is programmed in a language that does not have a client library, then we recommend consulting our JsConnect technical implementation guide.
How JsConnect maps users
After calling your endpoint and getting a “signed in” reply, JsConnect looks up the user. If they have already used SSO, we have permanently mapped their unique ID to our UserID, so we sign them into that account. If they haven’t used SSO before, 1 of 3 things happens:
- If the email for the user has never been used on the forum, a new account is created using the data passed, and the user is signed into it.
- If the email is in use and
AutoConnect is enabled, we will immediately sign the user in (and permanently store the mapping).
- If the email is in use and
AutoConnect is NOT enabled, we will prompt the user for their forum password to confirm their identity. This is the default setting because it is safer to assume you haven’t verified their email address.
Vanilla Cloud customers should ask Support to enable
AutoConnect if they desire it. That is an important component of a seamless experience.
Tightening the integration
To get very tight SSO integration, you will also want to follow these steps. (But always carefully test your basic SSO authentication before tightening your integration).
- Change your registration method to ‘Connect’ to block non-SSO users from registering.
- Set the sign-in, sign-out, and registration URLs under JsConnect’s settings in your Dashboard.
- Check “Make this connection your default signin method.”
- When linking or redirecting signed-in users to your forum, use the
/ssoendpoint on the forum. This triggers JsConnect’s user lookup on the connection with “default sign in method” selected without the user needing to click. Optionally, you can provide a
Target parameter with a relative path to specify where they should ultimately land on the forum. Example:
http://forum.yoursite.com/sso?Target=/categories. This is the final critical step in a fully seamless experience.
- For seamless SSO on an embedded forum, see our embedded SSO solution.
If no JsConnect connection is designated as the “Default”, you cannot use the
/sso endpoint. Instead, use expanded endpoint that specifies the client ID of the connection you wish to trigger:
/entry/jsconnect?client_id=[value_in_settings]. This setup is useful in situations where you are using JsConnect in addition to normal logins or alternate SSO solutions, rather than as the sole connector.
Testing the integration
Use the “Test URL” link under your JsConnect settings to see if your endpoint is returning a good response.
Try using your browser’s Incognito/Private window mode for testing. This allows you to have a separate “test” session while you stay logged in as the administrator in your main session to make changes quickly.
What do we do if SSO breaks and we’re locked out?
You can log back in using the “hidden” URL
/entry/password to sign-in with an existing forum account. This page is never redirected for SSO.
Can’t we just add users over the API?
We strongly recommend against adding users over the API. Using JsConnect and allowing it to add users as they sign-in is the most robust and reliable approach that will cause you the fewest issues.
Can we use multiple SSO connections?
Absolutely. However, only one can be the default, which is what will trigger when
/sso is used.
How do we have seamless sign-in for users who go directly to the forum?
If you’ve followed all the steps above, the only way a user can be not signed into the forum while signed into your main site is if they sign into your site separately and then visiting the forum by typing in the address manually or clicking a browser bookmark. In this scenario, they would need to click a prompt to finish the forum sign-in.
How is sign-out handled?
We bounce them to your sign-in page after they sign-out on the forum. To do the opposite, redirecting users through our sign-out page, again passing a
Targetparameter so they finish where you want them to.
Does this work for native applications, non-web scenarios, or third-party products?
No. JsConnect is purely a web-based SSO workflow for your existing login system. We also have separate products for popular third-party platforms and non-web scenarios.
Can we reverse-SSO to Vanilla via API to see if a user is logged in there?
Not at this time.
Can we use JsConnect without providing an email address?
No. You absolutely must send an email, which is the only method for mapping users. If you are importing forum users without email addresses and need a way to map them over SSO, we recommend using dummy email addresses that follow a formula like
Our system has overlapping names, but Vanilla needs unique ones. How can we handle this?
We strongly recommend assigning them unique usernames in your system, then passing that unique username to JsConnect. Keep in mind that, for features like mentions and autocomplete to work, usernames must be unique and adhere to Vanilla’s username restrictions. Passing a duplicate
Name field for a new user over JsConnect will cause the connection to fail.
Can we set roles over JsConnect?
Yes. See our quickstart documentation for more information.
The settings & endpoint response look correct now, but it’s still not working or redirecting properly.
Try clearing your cookies and browser cache and restarting your browser. Use Incognito/Private mode whenever possible. Also, beware of Firefox caching redirects; when in doubt, double-check a redirect using another browser.
Repeatedly attempting SSO with many sessions and accounts with changing settings can cause unexpected results. This isn’t a problem users would ever run into day-to-day.
Make it seamless
When setting up a JsConnect connection in full-site mode, you have the option to specify it as “default”. Doing this attaches it to the special
/sso endpoint in Vanilla. When a user clicks “Forum” in your website’s navigation, instead of linking to the forum homepage, instead link them to the
/sso page. This will auto-fire the asynchronous call back to your website rather than waiting for the user to click “sign in”, then drops them on the homepage as normal.
For more information, read our technical overview and our quickstart guide.
If your site is using WordPress you can use our plugin that allows you to use SSO with your WordPress site and allows you to set up an embedded forum and embedded comments on your site. Get the plugin.