OAuth2 Addons - Vanilla Success
<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>Vanilla currently 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 forum. 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. To take advantage of this class, either use our <strong>OAuth2 Plugin</strong> or <strong>Create Your Own OAuth2 Plugin</strong>.</p><h2 data-id="oauth2-plugin">OAuth2 Plugin</h2><h3 data-id="overview">Overview</h3><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 forum 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 forum, 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>: Not supported in this work flow are <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 exepected 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 Assumptions section above are met</li><li>Your forum 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 “whitelist” 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>For more on how to create your own plugin see our docs on <a href="https://docs.vanillaforums.com/developer/plugins/" rel="nofollow noreferrer ugc">Plugins</a>.</p><p>Feel free to use the OAuth2 plugin as a template. Make sure your plugin extends Gdn_OAuth2. You may want to change your ProviderKey (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>