Upgrade jsConnect to v3 - Vanilla Success
<main> <article class="userContent"> <p>This article walks you through how to upgrade an existing <strong>jsConnect v2</strong> installation to <strong>v3</strong>.</p><h2 data-id="why-you-need-to-upgrade">Why you need To upgrade</h2><p>The jsConnect v2 library uses a protocol called JSONP to authenticate the user to your site. JSONP requires certain cookie permissions that browsers are starting to disable by default with the introduction of the samesite cookie restrictions. Vanilla's decision to update jsConnect is in response to evolving standards set by popular web browsers.</p><p>Because of this, we changed the way jsConnect works with v3 to use a redirect flow that is very similar to a two-legged OAuth or SAML authentication flow. This flow uses fairly standard cookie policies, and is compatible with all browsers.</p><p>For this reason, we strongly recommend that you upgrade your jsConnect SSO to v3 as soon as possible.</p><p><strong>📝 NOTE</strong>: We strongly recommend that you change the <strong>secret</strong> on your connection when upgrading. Occasionally changing your secret is a best practice anyway, so this is a good opportunity to do so.</p><h4 data-id="relevant-articles">Relevant Articles</h4><ul><li><a href="https://www.chromium.org/updates/same-site" rel="nofollow noreferrer ugc">Google Chrome</a> resumed SameSite cookie enforcement with the release of <strong>Chrome 84</strong> on July 14, 2020. </li><li>Microsoft Edge is a Chromium-based browser, and is following a <a href="https://docs.microsoft.com/en-us/microsoft-edge/web-platform/site-impacting-changes" rel="nofollow noreferrer ugc">similar schedule</a> as Google Chrome. </li><li>The <a href="https://developer.apple.com/documentation/safari-release-notes/safari-13_1-release_notes" rel="nofollow noreferrer ugc">Safari 13.1</a> release is when Apple began, by default, blocking cookies for all cross-site resources. </li><li>Firefox's <a href="https://support.mozilla.org/en-US/kb/enhanced-tracking-protection-firefox-desktop" rel="nofollow noreferrer ugc">Enhanced Tracking Protection</a> began blocking these types of cookies by default in September 2019. </li></ul><h2 data-id="upgrade-process">Upgrade process</h2><p>Upgrading jsConnect is a three-step process:</p><ol><li>Upgrade your jsConnect client library on your site to a version that supports the jsConnect v3 protocol.</li><li>Configure jsConnect in Vanilla to use the v3 protocol.</li><li>Test your connection.</li></ol><p>Let's walk through each step in detail.</p><h3 data-id="upgrade-your-jsconnect-client-library">Upgrade Your jsConnect Client Library</h3><p>In order to upgrade your client library, you're going to need to locate the authentication page within your application. Because this page is on your site, you'll need to do some research to figure out where it is and where the source code is.</p><p>Generally, you'll need to replace your old client library with a new one, but you may have to do some programming depending on which language your client library is in.</p><p>There are instructions with each client library on Vanilla. You should go to the repository of your client library and look through the README for specific instructions of what to do.</p><ul><li><a href="https://github.com/vanilla/jsConnectPHP" rel="nofollow noreferrer ugc">PHP client library</a></li><li><a href="https://github.com/vanilla/jsConnectJava" rel="nofollow noreferrer ugc">Java client library</a></li><li><a href="https://github.com/vanilla/jsConnectRuby" rel="nofollow noreferrer ugc">Ruby client library</a></li><li><a href="https://github.com/vanilla/jsConnectdotNet" rel="nofollow noreferrer ugc">.NET client library</a></li></ul><p>If your site is programmed in a language other than what's listed above, use our <a href="https://success.vanillaforums.com/kb/articles/211-implementing-the-jsconnect-version-3-protocol" rel="nofollow noreferrer ugc">implementation guide</a> as a reference to implement the new protocol.</p><p>If you're using the Vanilla Wordpress plugin on Wordpress to do SSO, you'll have to install the most recent version of our <a href="https://wordpress.org/plugins/vanilla-forums/" rel="nofollow noreferrer ugc">plugin from Wordpress</a>.</p><h3 data-id="configure-jsconnect-in-vanilla">Configure jsConnect In Vanilla</h3><p>Configuring jsConnect is fairly straightforward. To do so, go into your Dashboard's jsConnect settings and configure your connection to use the v3 protocol.</p><div class="embedExternal embedImage display-large float-none"> <div class="embedExternal-content"> <a class="embedImage-link" href="https://us.v-cdn.net/6030677/uploads/228/GYVAAI347L02.png" rel="nofollow noreferrer noopener ugc" target="_blank"> <img class="embedImage-img" src="https://us.v-cdn.net/6030677/uploads/228/GYVAAI347L02.png" alt="T1.png" height="962" width="2042" loading="lazy" data-display-size="large" data-float="none"></img></a> </div> </div> <p>The above screenshot shows my jsConnect settings. You can see that there's now a warning message and an alert icon by the connection that tells you there's something that need to be fixed. Edit the connection to address the issues.</p><div class="embedExternal embedImage display-large float-none"> <div class="embedExternal-content"> <a class="embedImage-link" href="https://us.v-cdn.net/6030677/uploads/177/ZZ4WYOHVLXYZ.png" rel="nofollow noreferrer noopener ugc" target="_blank"> <img class="embedImage-img" src="https://us.v-cdn.net/6030677/uploads/177/ZZ4WYOHVLXYZ.png" alt="T1.png" height="784" width="2091" loading="lazy" data-display-size="large" data-float="none"></img></a> </div> </div> <p>If you scroll down toward the bottom of the dialog, you will see a dropdown to select the v3 protocol. Select the new protocol, click <strong>Save</strong>, and your connection should be ready to go.</p><h3 data-id="test-your-connection">Test your connection</h3><p>Once you've updated your client library and configured your connection, you should test it. To do so, click the <strong>Test URL</strong> link by the connection. This performs the authentication to your site and gives you some information useful in debugging the test.</p><div class="embedExternal embedImage display-large float-none"> <div class="embedExternal-content"> <a class="embedImage-link" href="https://us.v-cdn.net/6030677/uploads/356/SGH7N4WSM5KF.png" rel="nofollow noreferrer noopener ugc" target="_blank"> <img class="embedImage-img" src="https://us.v-cdn.net/6030677/uploads/356/SGH7N4WSM5KF.png" alt="T1.png" height="326" width="2040" loading="lazy" data-display-size="large" data-float="none"></img></a> </div> </div> <p>The above screenshot shows a successful test, but with a user who isn't signed in to your site, there is a link provided you can click to complete the sign in process.</p><div class="embedExternal embedImage display-large float-none"> <div class="embedExternal-content"> <a class="embedImage-link" href="https://us.v-cdn.net/6030677/uploads/628/FBNY0BM1X3TH.png" rel="nofollow noreferrer noopener ugc" target="_blank"> <img class="embedImage-img" src="https://us.v-cdn.net/6030677/uploads/628/FBNY0BM1X3TH.png" alt="T1.png" height="1207" width="2048" loading="lazy" data-display-size="large" data-float="none"></img></a> </div> </div> <p>After signing in, you get more information on the connection. You should look over the fields to see if there are any problems. Generally, if you see all of your information under <strong>Known User Fields</strong> then you should be okay because Vanilla knows how to map those fields. Any unknown fields may not be applied to users signing in, unless you have a specific customization that can handle them.</p><p><strong>✔️ TIP</strong>: For more troubleshooting tips and tricks, check out <a href="https://success.vanillaforums.com/kb/articles/211-implementing-the-jsconnect-version-3-protocol#troubleshooting-and-tips" rel="nofollow noreferrer ugc">this article.</a></p> </article> </main>