SSO Overview - HL Vanilla Community
<main> <article class="userContent"> <p><strong>Single Sign-on</strong> (<strong>SSO</strong>) is a feature that allows log-in credentials to be shared across multiple systems to reduce repeated log-in operations.</p><p>For example, users can sign in to a <strong>Higher Logic Vanilla</strong> (<strong>Vanilla</strong>) forum and, from there, access a separate system (such as Twitter) without having to log in. The username and password that were provided to Vanilla act as the log-in credentials for Twitter because the user has already been authenticated.</p><p>📝 <strong>NOTE</strong>: All communications between SSO-enabled systems are secure; so is the identity of the user moving between them.</p><h2 data-id="vanilla's-sso-solutions">Vanilla's SSO solutions</h2><p>Vanilla has several SSO options. Use the links below to access our knowledge base articles.</p><ul><li><strong>Security Assertion Markup Language</strong> (<strong>SAML</strong>): <a href="https://success.vanillaforums.com/kb/articles/32-saml-sso" rel="nofollow noreferrer ugc">SAML SSO</a> (cloud-only)</li><li><strong>Open Authorization</strong> (<strong>OAuth</strong>): <a href="https://success.vanillaforums.com/kb/articles/33-oauth2" rel="nofollow noreferrer ugc">OAuth 2.0</a></li><li><strong>JSON Web Tokens</strong> (<strong>JWT</strong>): <a href="https://success.vanillaforums.com/kb/articles/98-jwt-json-web-token-sso" rel="nofollow noreferrer ugc">JWT (JSON Web Token) SSO</a></li><li><a href="https://success.vanillaforums.com/kb/articles/34-jsconnect" rel="nofollow noreferrer ugc">jsConnect</a> (our in-house solution)</li></ul><p>We also offer:</p><ul><li>Social SSO (Twitter, Facebook, and more)</li><li>Third-party service integration (e.g., Auth0; cloud-only)</li><li>Custom SSO integrations (cloud-only)</li></ul><p>All SSO options follow general rules in Vanilla, many of which are outlined below.</p><h2 data-id="general-sso-principles">General SSO principles</h2><p>Regardless of your type of SSO, the following principles and recommendations apply in order to ensure that your SSO works well with Vanilla.</p><ul><li>You are the provider so you must make sure that the information you pass through SSO is already validated. For example, email addresses <strong>should be already confirmed</strong> on your side before a user is allowed to connect through SSO.</li><li>It is recommended you <strong>do not create</strong> users over the API. The fault-tolerant way to map users to your forum is to have them be asynchronously created as they log in.</li></ul><h3 data-id="account-connection">Account connection</h3><p>When a user logs in through SSO for the first time, a connection is made using the <strong>SSO UniqueID</strong> and <strong>Vanilla UserID</strong>. The connection between the two IDs is permanent <em>for that connection</em>. If the user changes their email address after the first connection it won’t cause any problem.</p><p>When that connection is being made, if:</p><p><strong>All the required information is correctly passed through SSO and a matching user is found in Vanilla...</strong></p><ul><li>A new user is created on the forum.</li></ul><p><strong>Some required information is missing... OR</strong></p><p><strong>Some information matches an existing user on the forum...</strong></p><ul><li>The user will be redirected to a page and <em>must do one of the following</em>:<ul><li>Provide the missing information.</li><li>Manually connect to an existing forum account by specifying the password of that account. (This ensures that the user owns the forum’s account.)</li><li>Create an account with a username/email address that does not exist in forum.</li></ul></li></ul><p>📝 <strong>NOTE</strong>: A prompt will display if the user omits any required information<em>.</em></p><h3 data-id="autoconnect">AutoConnect</h3><p>AutoConnect is a feature that uses email addresses to automatically connect an account in the <a href="https://docs.vanillaforums.com/help/sso/#account-connection" rel="nofollow noreferrer ugc">Account connection</a> process. When this feature is enabled and the email address that is passed through SSO matches the email address of a user account on the forum, the connection between the SSO UniqueID and Vanilla UserID is immediate, the user does not have to confirm ownership over an existing account.</p><ul><li>For security reasons, it must be opted into. Email addresses must be validated on your side when using this feature.</li><li>Vanilla connects existing accounts only by matching email address. No exceptions.</li></ul><h3 data-id="redirection">Redirection</h3><p>📝 <strong>NOTE</strong>: Most SSO solutions honor this behavior.</p><p>When tightening your SSO configurations to automatically redirect users after the sign-in process, you can use <code class="code codeInline" spellcheck="false" tabindex="0">{target}</code> in the redirect URL. Vanilla will replace <code class="code codeInline" spellcheck="false" tabindex="0">{target}</code> with the page that the user is currently on when generating the URL.</p><p><strong>EXAMPLE</strong> (using jsConnect):</p><p><a href="https://sso.example.com/jsconnect/signin?redirect={target}" rel="nofollow noreferrer ugc"><code class="code codeInline" spellcheck="false" tabindex="0">https://sso.example.com/jsconnect/signin?redirect=</code></a><a href="https://sso.example.com/jsconnect/signin?redirect={target}" rel="nofollow noreferrer ugc"><strong>{target}</strong></a><a href="https://sso.example.com/jsconnect/signin?redirect={target}" rel="nofollow noreferrer ugc"> </a></p><p>might be updated to:</p><p><a href="https://sso.example.com/jsconnect/signin?redirect=/discussions" rel="nofollow noreferrer ugc"><code class="code codeInline" spellcheck="false" tabindex="0">https://sso.example.com/jsconnect/signin?redirect=</code></a><a href="https://sso.example.com/jsconnect/signin?redirect=/discussions" rel="nofollow noreferrer ugc"><strong>/discussions</strong></a></p><h2 data-id="user-log-outs">User log outs</h2><h3 data-id="log-out-initiated-from-vanilla">Log out initiated from Vanilla</h3><p>We recommend using the default logout approach, which is accomplished by:</p><ol><li>Setting a default connection (having your SSO connection as the only method for connecting users to the community) and</li><li>Including your site's log-out URL in its configuration. </li></ol><p>When users click <strong>Sign Out</strong> on Vanilla, they are logged out of the community and redirected to your site's log-out page. </p><h3 data-id="log-out-initiated-from-your-site">Log out initiated from your site</h3><p>You can set up the log out such that when users log out of your site, they are also automatically logged out of your community.</p><p>There are two ways to have this happen: <strong>redirecting</strong> and <strong>deleting cookies</strong>. Both of these methods require:</p><ul><li>having a <strong>shared domain</strong> (or subdomain) and</li><li>modifying your <strong>Cookie Domain</strong>. </li></ul><p>To understand <strong>shared domain</strong>, assume that your site is <strong>thisismysite.com</strong> and that your community is <strong>forum-now</strong>, your shared domain is <strong>forum-now.thisismysite.com</strong>.</p><p>Because your site and community share the domain, you can set the <strong>Cookie Domain </strong>on the community<strong> </strong>as <strong>*.thisismysite.com</strong>.</p><p>📝 <strong>NOTE</strong>: Modifying your Cookie Domain requires the assistance of the Vanilla Support Team.</p><p>Now when the user is on <strong>thisismysite.com</strong>, you can read and/or delete cookies that were set on <strong>forum-now.thisismysite.com</strong>.</p><p><em>Redirecting</em> and <em>deleting cookies</em> are the two ways of logging users out of your site and automatically out of your community.</p><h4 data-id="redirecting">Redirecting</h4><p>When users sign out of your site, they are redirected to the community log-out page with the <strong>TransientKey</strong> (which is stored in their cookies) and the <strong>Target</strong> (the URL-encoded destination of where you would like users to end up after being logged out).</p><p>Below is an example of a URL with these <strong>parameters</strong> and their <em>values</em>.</p><p>https://forum-now.thisismysite.com/entry/signout?<strong>TransientKey</strong>=<em>59WaY3nFTSHLiDWN%3A33%3A1585763045%3Abfb7f6e3cd8dda34095a441dcba52f1f</em>&<strong>Target</strong>=<em>https%3A%2F%2Fthisismysite.com%2Fthank-you-come-again</em>.</p><p>📝 <strong>NOTE</strong>: Specify the Target URL in the <strong>Trusted Domains</strong> section of the <strong>Security</strong> page in <strong>Dashboard > Settings > Technical</strong>.</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/XEOXJH700ZOJ/settings-security-trusted-domains.png" rel="nofollow noreferrer noopener ugc" target="_blank"> <img class="embedImage-img" src="https://us.v-cdn.net/6030677/uploads/XEOXJH700ZOJ/settings-security-trusted-domains.png" alt="Settings-Security-Trusted Domains.png" height="524" width="1083" loading="lazy" data-display-size="large" data-float="none"></img></a> </div> </div> <h4 data-id="deleting-cookies">Deleting cookies</h4><p>When users sign out of your site, as part of your session-ending routine, you can delete all the Vanilla-generated cookies.</p><ul><li>See <a href="https://success.vanillaforums.com/kb/articles/86-cookies-used-in-vanilla" rel="nofollow noreferrer ugc">Cookies Used in Vanilla</a> to learn about <em>Vanilla's cookies</em>, <em>how they are named</em>, and <em>what they do</em>.</li></ul> </article> </main>