Single sign-on (SSO) systems are complex. Setting up your own SAML or OAuth system requires an investment of time and effort, and generally is not feasible for small-to-medium business owners.
If you have a website that stores your users’ identities and the only thing you need to integrate is a community, 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 you to use on your side.
However, even this simpler solution requires 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.
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 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, Higher Logic Vanilla (Vanilla) will do a lookup by email address against the community 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 affect the login process.
- If no email match is found, a new community account will be created instantly using the provided data. If no username is provided, the user will be prompted to create one. This is known as Just-In-Time Provisioning (JIT).
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 community 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 community 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 implementation methods
JsConnect supports two methods of implementing SSO. You can implement either of the methods or both, as they serve different purposes.
- Site-wide SSO - You implement site-wide SSO when Vanilla is a full site. With this method you need to create a page that provides your login information in JSON Web Token format.
- Embedded SSO – You can also embed Vanilla 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.
Technical overview
For JsConnect to work, you must insert 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 them with Vanilla. This is done by sending a signed JSON Web Token to obtain login information.
Vanilla’s web-based SSO has two 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.
Your endpoint & client libraries
Your endpoint needs to “say” one of three 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.
📝 NOTE: These libraries DO NOT 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, one of three things happens:
- If the email for the user has never been used on the community, 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 community password to confirm their identity. This is the default setting because it’s safer to assume you haven’t verified their email address.
Vanilla Cloud customers should ask Support to enable AutoConnect if they want it. That is an important component of a seamless experience.
Tightening the integration
To achieve a tight SSO integration, you will also want to follow these steps.
📝 NOTE: 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 community, use the /sso endpoint on the community. 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 community. Example:
http://forum.yoursite.com/sso?Target=/categories. This is the final critical step to a fully seamless experience. - For seamless SSO on an embedded community, see our embedded SSO solution.
If no JsConnect connection is designated as the “Default,” you cannot use the /sso endpoint. Instead, use an 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're 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.
Common questions
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 community 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 the fewest issues.
Can we use multiple SSO connections?
Yes. 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 community?
If you’ve followed all the steps above, the only way a user can NOT be signed into the community while signed into your main site is if they sign into your site separately and then visit the community by typing in the address manually or clicking a browser bookmark. In this scenario, they would need to click a prompt to finish the community sign-in.
How is sign-out handled?
We bounce them to your sign-in page after they sign-out on the community. To do the opposite—redirecting users through our sign-out page—again passing a Target parameter 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?
No.
Can we use JsConnect without providing an email address?
No. You must send an email, which is the only method for mapping users. If you’re importing community users without email addresses and need a way to map them over SSO, we recommend using dummy email addresses that follow a formula like {uniqueID}@yoursite.com.
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 encounter 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 community 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,” and then navigates them to the homepage as normal.
For more information, read our technical overview and quickstart guide.
WordPress plugin
If your site is using WordPress, you can leverage our plugin to use SSO with your WordPress site and to set up an embedded community and embedded comments on your site. Get the plugin.