OAuth2 Addons - HL Vanilla Community
<main> <article class="userContent"> <div class="embedExternal embedImage display-large float-none"> <div class="embedExternal-content"> <a class="embedImage-link" href="https://us.v-cdn.net/6030677/uploads/JSIQF9TCCFTV/microsoftteams-image-288-29.png" rel="nofollow noreferrer noopener ugc" target="_blank"> <img class="embedImage-img" src="https://us.v-cdn.net/6030677/uploads/JSIQF9TCCFTV/microsoftteams-image-288-29.png" alt="MicrosoftTeams-image (8).png" height="108" width="1356" loading="lazy" data-display-size="large" data-float="none"></img></a> </div> </div> <h2 data-id="sso-with-oauth%3A-overview">SSO with OAuth: Overview</h2><p><strong>Higher Logic Vanilla (Vanilla)</strong> provides OAuth2 integrations with these third-party services as ready-to-go addons:</p><ul><li>Facebook</li><li>Twitter</li><li>LinkedIn</li><li>Google+</li></ul><p>Because OAuth 2.0 is an SSO <em>framework</em> and not a narrowly defined protocol (see <a href="https://tools.ietf.org/html/rfc6749" rel="nofollow noreferrer ugc">OAuth 2.0 Spec</a>), custom services work is typically required to set up an OAuth solution for your community. In an attempt to minimize the amount of custom services required to create SSO integrations, Vanilla has created a base class that can easily be extended by custom plugins. This base class might look like many of our plugins (containing event handlers, etc.); it is not intended to be executed directly. </p><ul><li>To take advantage of this class, follow the process in either the <strong>OAuth2 plugin</strong> or <strong>create your own OAuth2 plugin </strong>section below.</li></ul><h2 data-id="oauth2-plugin">OAuth2 plugin</h2><p>Vanilla has created an OAuth2 plugin that, for most use-cases, can provide a plug-and-play SSO solution.</p><p>OAuth2 accounts are mapped to existing community accounts by email address, or a new account is created if no match is found.</p><h3 data-id="workflow">Workflow</h3><p>This plugin has a workflow of three distinct steps:</p><ul><li>An <strong>authorization request</strong> (request for a code)</li><li>A <strong>token request</strong> (the code is exchanged for an authorization token)</li><li>A <strong>profile request</strong> (by passing the authorization token)</li></ul><h3 data-id="assumptions">Assumptions</h3><p>Besides requiring that you follow the workflow above, this plugin has several assumptions about the setup of the Authorization Server. If your Authorization Server does not meet these assumptions, it does not mean that you cannot integrate with a Vanilla community; rather, it means that you will not be able to use this plugin out-of-the-box, and that you will require some level of customization.</p><ul><li>All requests from Vanilla are sent with the header <code class="code codeInline" spellcheck="false" tabindex="0">Content-Type: application/x-www-form-urlencoded</code></li><li>The Authorization Server will expect an authorization request sent by GET with the following parameters:<ul><li><code class="code codeInline" spellcheck="false" tabindex="0">response_type</code> => <code class="code codeInline" spellcheck="false" tabindex="0">code</code></li><li><code class="code codeInline" spellcheck="false" tabindex="0">client_id</code></li><li><code class="code codeInline" spellcheck="false" tabindex="0">redirect_uri</code> => https://<em>[The url of the forum]</em>/entry/oauth2</li><li><code class="code codeInline" spellcheck="false" tabindex="0">scope</code></li><li><code class="code codeInline" spellcheck="false" tabindex="0">state</code></li><li><code class="code codeInline" spellcheck="false" tabindex="0">client_secret</code></li><li><code class="code codeInline" spellcheck="false" tabindex="0">redirect_uri</code> => https://<em>[The url of the forum]</em>/entry/oauth2</li></ul></li><li>The Authorization Server will respond to a successful log in by sending a <code class="code codeInline" spellcheck="false" tabindex="0">code</code> through GET to the <code class="code codeInline" spellcheck="false" tabindex="0">redirect_uri</code><ul><li><code class="code codeInline" spellcheck="false" tabindex="0">client_id</code></li></ul></li><li>The Authorization Server will expect a token request sent by POST with the following parameters:<ul><li><code class="code codeInline" spellcheck="false" tabindex="0">code</code> => <em>[the code returned from the authorization request]</em></li><li><code class="code codeInline" spellcheck="false" tabindex="0">grant_type</code> => <code class="code codeInline" spellcheck="false" tabindex="0">authorization_code</code></li><li><code class="code codeInline" spellcheck="false" tabindex="0">scope</code></li><li>the user’s name (display name, nickname)</li></ul></li><li>The Authorization Server will send a JSON response with the variable <code class="code codeInline" spellcheck="false" tabindex="0">access_token</code></li><li>The Authorization Server will accept a request for the user’s profile sent by GET with <code class="code codeInline" spellcheck="false" tabindex="0">access_token</code></li><li>The Authorization Server will send a JSON response with at least the following:<ul><li>A uniqueID for the user</li><li>the user’s email</li></ul></li></ul><p><strong>📝 NOTE</strong>: This workflow does not support <strong>“nonce” support</strong> (a hash sent in the <code class="code codeInline" spellcheck="false" tabindex="0">state</code> and verified to be unchanged) and <strong>refresh tokens</strong>.</p><h3 data-id="features">Features</h3><p>The OAuth2 plugin attempts to “parameterize” as many aspects of the functionality as possible. A settings form in the Dashboard allows you to set:</p><ul><li>The client ID</li><li>The client secret</li><li>The full path to the authorization uri, registration uri, sign out uri, token endpoint, and profile endpoint</li><li>The scope</li><li>The expected keys in the json response in the profile request</li></ul><h3 data-id="possible-pitfalls">Possible pitfalls</h3><p>A number of things can go wrong when trying to implement SSO with this plugin:</p><ul><li>Double check that all the parameters outlined in the <strong>Assumptions </strong>section above are met</li><li>Your community must be accessed over <code class="code codeInline" spellcheck="false" tabindex="0">https</code>, and must contact your Authorization Server in the same way</li><li>Your Authorization Server will usually need to “allowlist” the redirect uri (i.e., https://<em>[The url of the forum]</em>/entry/oauth2)</li></ul><h2 data-id="create-your-own-oauth2-plugin">Create your own OAuth2 plugin</h2><p>To learn how to create your own plugin, see <a href="https://docs.vanillaforums.com/developer/plugins/" rel="nofollow noreferrer ugc">Plugins</a>.</p><p>You can use the OAuth2 plugin as a template. Make sure your plugin extends Gdn_OAuth2. You may want to change your <strong>ProviderKey </strong>(the key used to store your configuration data in the db) to something unique:</p><p><code class="code codeInline" spellcheck="false" tabindex="0">$this->setProviderKey('myOauthConnection');</code></p><p>This key will appear as part of a URL on the public-facing site when users connect, so you will want to make it relevant, readable, and URL safe.</p><p>Now, you can override any of the methods or constants in Gdn_OAuth2 or create new hooks for added functionality.</p> </article> </main>