JsConnect V3 Quickstart - HL Vanilla Community
<main> <article class="userContent"> <p>In this article, you'll learn how to configure Vanilla's JsConnect addon to perform Single Sign On (SSO) to your Vanilla community from your website. Vanilla's JsConnect is our in-house SSO addon that interfaces with your authentication application by making signed requests/responses sent as GET parameters in JSON Web Token. </p><ul><li>For more information about the workflow, see <a href="https://success.vanillaforums.com/kb/articles/211-implementing-the-jsconnect-version-3-protocol" rel="nofollow noreferrer ugc">Implement the jsConnect V3 Protocol</a>.</li></ul><p>If you <strong>are</strong> <strong>using </strong>JsConnect but are <strong>not using </strong>V3, we recommend that you switch as soon as possible. To do so, you'll need to upgrade the code on your authentication application first. You can build your own authentication application or install one of our libraries, if you use a programming language we support. </p><ul><li>For more information, and for a link to our libraries, see <a href="https://success.vanillaforums.com/kb/articles/34-jsconnect#technical-overview" rel="nofollow noreferrer ugc">this article.</a></li></ul><p><strong>📝 NOTE</strong>: This article explains how to configure the JsConnect addon in the Vanilla Dashboard only; for configuring the authentication application, follow the instructions in the README of the library you choose to install.</p><h2 data-id="anatomy-of-the-jsconnect-addon">Anatomy of the JsConnect addon</h2><div class="embedExternal embedImage display-large float-none"> <div class="embedExternal-content"> <a class="embedImage-link" href="https://us.v-cdn.net/6030677/uploads/Y6PLNASAJBO5/jsconnect-addon.png" rel="nofollow noreferrer noopener ugc" target="_blank"> <img class="embedImage-img" src="https://us.v-cdn.net/6030677/uploads/Y6PLNASAJBO5/jsconnect-addon.png" alt="jsconnect-addon.png" height="1032" width="2004" loading="lazy" data-display-size="large" data-float="none"></img></a> </div> </div> <ol><li><strong>Add Connection </strong>- You can have multiple buttons that connect to different applications, thereby allowing users to log in from different JsConnect authentication applications.</li><li><strong>Auto Connect </strong>-<strong> </strong>This setting allows you to automatically connect a user that you pass over in the SSO response to a user that already exists in your community. What does this mean? Let's say I register directly in the community with my email, <code class="code codeInline" spellcheck="false" tabindex="0">willy@chocolatefactory.com</code>. I have created a display name and have even posted some content. I then notice there's a button to sign in through your site, where I also have a membership. When I sign in through your site and am redirected to the community (with the signed response and my user data), the community finds that <code class="code codeInline" spellcheck="false" tabindex="0">willy@chocolatefactory.com</code> already exists and knows it's me from my earlier registration. If <strong>Auto Connect</strong> is turned <strong>on</strong>, the community will trust that I am the same <code class="code codeInline" spellcheck="false" tabindex="0">willy@chocolatefactory.com</code> , and I will be logged in as such. If <strong>Auto Connect </strong>is turned <strong>off</strong>, it will not assume that <code class="code codeInline" spellcheck="false" tabindex="0">willy@chocolatefactory.com</code> is me, it will prompt me to put in the correct password for that user in order to prove that it <em>is</em>.</li><li><strong>Use Popup Sign In Pages </strong>-<strong> </strong>Toggle this on if you want a small dialog to open on the page with the sign in form. If you're using JsConnect as your default method of signing in, we recommend that you turn this off, as it will just open the dialog and then redirect you. You will definitely want this set to off if you're using Vanilla to embed comments, or if you're embedding the whole community in an iframe.</li><li><strong>Edit, Delete or Test a Connection.</strong> Since you can have multiple connections, you're free to edit them or delete them. Testing the connection will make a request to the Authentication URL you have configured and show you the response.</li></ol><h2 data-id="configuration">Configuration</h2><p>The configuration form of a connection is simple. However, here are some elements that might require an explanation:</p><ol><li><strong>Client ID -</strong> The name of the authentication application on your site. </li><li><strong>Secret -</strong> The string shared between the authentication application on your site and Vanilla, used to sign requests.</li><li><strong>Site Name -</strong> The name of the site or application that the user will sign in from. If you have multiple methods to sign in, this will appear on the button for this connection. If I want employees to log in from one connection, then I would put "Employee Sign In" here.</li><li><strong>Authentication URL -</strong> The endpoint on the authentications application on your site that handles the logic of logging in users. Append this URL with <code class="code codeInline" spellcheck="false" tabindex="0">&Target={target}</code> or <code class="code codeInline" spellcheck="false" tabindex="0">?Target={target}</code> in order to allow our system to return the user to the page where they were when they clicked Sign In. If I click Sign In when I'm on <code class="code codeInline" spellcheck="false" tabindex="0">/discussion/16/any-suggestions</code> our system will literally string-replace <code class="code codeInline" spellcheck="false" tabindex="0">{target}</code> with <code class="code codeInline" spellcheck="false" tabindex="0">%2Fdiscussion%2F16%2Fany-suggestions</code> and pass it along to your authentication server as <code class="code codeInline" spellcheck="false" tabindex="0">&Target=%2Fdiscussion%2F16%2Fany-suggestions</code>. When the user is authenticated and sent back to the community with that <code class="code codeInline" spellcheck="false" tabindex="0">Target</code> parameter still intact, we will redirect them to where they were.</li><li><strong>Sign In and Registration URLs -</strong> These URLs are where you want users directed to when they sign in or register. Append these URLs with <code class="code codeInline" spellcheck="false" tabindex="0">&Target={target}</code> or <code class="code codeInline" spellcheck="false" tabindex="0">?Target={target}</code> in order to allow our system to return the user to the page where they were when they clicked Sign In. If I click on Sign In when I'm on <code class="code codeInline" spellcheck="false" tabindex="0">/discussion/16/any-suggestions</code> , our system will string-replace <code class="code codeInline" spellcheck="false" tabindex="0">{target}</code> with <code class="code codeInline" spellcheck="false" tabindex="0">%2Fdiscussion%2F16%2Fany-suggestions</code> and pass it along to your authentication server as <code class="code codeInline" spellcheck="false" tabindex="0">&Target=%2Fdiscussion%2F16%2Fany-suggestions</code>. When the user is authenticated and sent back to the community with that <code class="code codeInline" spellcheck="false" tabindex="0">Target</code> parameter still intact, we will redirect them to where they were.</li><li><strong>This is a trusted connection and can sync roles & permissions -</strong> All of Vanilla's SSO methods support passing and assigning Roles as part of the connection process. If the authentication server is controlled by you, you can trust that if it passes a Role that we can assign it to the user. If not, toggle this off. By default Vanilla will re-assign the user's Roles every time they log in over SSO, giving your authentication provider full control over the user's Roles. Cloud customers who want to be able to assign roles to users in the Vanilla Dashboard <strong>and</strong> have roles <strong>added</strong> over SSO can ask Vanilla Support to configure their community to work this way. For more details on passing roles over SSO, see <a href="https://success.vanillaforums.com/kb/articles/179-managing-roles-with-sso" rel="nofollow noreferrer ugc">this article</a>.</li><li><strong>Make this connection your default signin method -</strong> If you only want users logging in registering on your authentication server, toggle this <strong>on</strong>. This has multiple benefits.<ol><li>There will not be multiple buttons or a form to sign in.</li><li>When a user clicks on sign in he/she is sent directly to your sign in page.</li><li>If your forum is in Private Mode, instead of landing on the community, users will be redirected to the sign in page on your site if they are not already signed in.</li><li>You can use the convenient <code class="code codeInline" spellcheck="false" tabindex="0">/sso</code> endpoint to connect users seamlessly from your application to the community. This means that on your site you can create links to the community that are like <code class="code codeInline" spellcheck="false" tabindex="0">https://you-forum.yoursite.com/sso </code>and if your user is logged in on your site they will be logged in on the community. They will not have to click Sign In to start posting in the community.</li></ol></li><li><strong>Test Mode -</strong> Ignore this if you're using Version 3.</li><li><strong>Protocol -</strong> This should be set to Version 3. Version 2 is based on making Ajax requests and passing cookies over those requests. Most browsers will now reject those cookies.</li></ol><h2 data-id="troubleshooting">Troubleshooting</h2><p>For testing and troubleshooting, see <a href="https://success.vanillaforums.com/kb/articles/34-jsconnect#testing-the-integration" rel="nofollow noreferrer ugc">this article</a>.</p> </article> </main>