OAuth 2.0 - Vanilla Success
<main> <article class="userContent"> <h2 data-id="options-for-using-oauth-2.0">Options for using OAuth 2.0</h2><p>Vanilla currently provides tailored OAuth 2.0 integrations with these third-party identity providers as ready-to-go addons:</p><ul><li>Facebook</li><li>Twitter</li><li>LinkedIn</li><li>Google+</li></ul><p>To learn more about how to use these SSO methods,<a href="https://success.vanillaforums.com/kb/articles/36-social-connect-options" rel="nofollow noreferrer ugc"> please go to this article.</a></p><p>We also provide a generic OAuth2 addon that works with basic implementations, including support for the third-party service Auth0.</p><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 occassionally required to set up an OAuth solution tailored to your forum. Our generic OAuth2 addon is highly extensible to be able to render these services quickly and efficiently.</p><p>If you do not currently have an OAuth 2.0 identity provider, we strongly recommend using a third-party provider in place of creating a new one before launching your forum.</p><p>Vanilla supports the <strong>authorization code grant </strong>workflow. You will not be able to use the <em>implicit grant flow</em> without creating a custom plugin. To know more about the difference between these two methods for OAuth 2.0 <a href="https://developer.okta.com/blog/2018/05/24/what-is-the-oauth2-implicit-grant-type" rel="nofollow noreferrer ugc">please read this article.</a></p><h2 data-id="using-the-oauth2-addon-in-vanilla">Using the OAuth2 Addon in Vanilla</h2><p>As with all our SSO solutions, OAuth2 accounts are mapped to existing forum accounts by email address, or a new account is created if no match is found. You may combine it with any other SSO connections.</p><p>A settings form in the dashboard allows you to define custom parameter names for:</p><ul><li>Client id</li><li>Client secret</li><li>Full path to the: <ul><li>authorization URI, </li><li>registration URI, </li><li>sign out URI, </li><li>token endpoint, and </li><li>profile endpoint</li></ul></li><li>Scope</li><li>Expected keys in the JSON response to the profile request</li></ul><h3 data-id="mapping-user-profile-values">Mapping User Profile Values</h3><p>The Profile endpoint, or user-info endpoint is expected to return a JSON encoded array of the user's data. <a href="https://success.vanillaforums.com/kb/articles/248-oauth2-addons#assumptions" rel="nofollow noreferrer ugc">See this document for the expectations.</a> The Profile URL field is required in the OAuth2 Addon. We do not support getting user data from an IDToken.</p><p>The OAuth2 workflow sends the user's profile data as a set of key/value pairs in a JSON object. If those key names do not correspond to Vanilla's you will need to map the key names in the OAuth2 Addon Settings form. For exemple, if your authentication provider sends the user's profile like this:</p><pre class="code codeBlock" spellcheck="false" tabindex="0">{ "address": "dave@email.com", "pic": "https://cdn.aws.com/ourcdn/davesprofilepic.gif", "name": "Dave", "fullname": "Dave Johnson", "id": 1828838378 } </pre><p>You will need to configure the dashboard accordingly:</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/351/WILTDOMH3GCD.png" rel="nofollow noreferrer noopener ugc" target="_blank"> <img class="embedImage-img" src="https://us.v-cdn.net/6030677/uploads/351/WILTDOMH3GCD.png" alt="Screen Shot 2019-05-22 at 3.06.27 PM.png" height="708" width="1520" loading="lazy" data-display-size="large" data-float="none"></img></a> </div> </div> <p>The OAuth2 plugin even supports multi-dimensional responses. If your authentication provider's user profile response looks like this:</p><pre class="code codeBlock" spellcheck="false" tabindex="0">{ "address": "dave@email.com", "pictures": { "preferred": "https://cdn.aws.com/ourcdn/davesprofilepic.gif" }, "name": "Dave", "fullname": "Dave Johnson", "id": 1828838378 } </pre><p>you can map it by using dot-notation:</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/732/1YCSKF8RFYNB.png" rel="nofollow noreferrer noopener ugc" target="_blank"> <img class="embedImage-img" src="https://us.v-cdn.net/6030677/uploads/732/1YCSKF8RFYNB.png" alt="Screen Shot 2019-05-22 at 3.13.25 PM.png" height="680" width="1446" loading="lazy" data-display-size="large" data-float="none"></img></a> </div> </div> <h3 data-id="passing-roles-over-oauth2">Passing Roles over OAuth2</h3><p>You can pass a user's role in the profile response. Unlike the values shown above, there is no user interface for mapping the key name for roles in the dashboard -- <em>yet</em>. For now, if you want to pass a user's role and have it applied as a role on the forum it <strong><em>must </em></strong>be passed as "Roles" (case-insensitive, plural "Roles"). The value can be a comma separated list of roles. In order for it to work it <strong><em>must</em></strong> correspond exactly with name of a role or roles configured on your forum.</p><pre class="code codeBlock" spellcheck="false" tabindex="0">{ "address": "dave@email.com", "pic": "https://cdn.aws.com/ourcdn/davesprofilepic.gif", "name": "Dave", "fullname": "Dave Johnson", "id": 1828838378, "Roles": "Moderator, Chearleader" } </pre><p>will assign these two roles to this user.</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/260/SFXJIJGWSVYN.png" rel="nofollow noreferrer noopener ugc" target="_blank"> <img class="embedImage-img" src="https://us.v-cdn.net/6030677/uploads/260/SFXJIJGWSVYN.png" alt="Screen Shot 2019-05-22 at 3.29.30 PM.png" height="256" width="1850" loading="lazy" data-display-size="large" data-float="none"></img></a> </div> </div> <p>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 support to configure their forum to work in this way. For more details on passing roles over SSO <a href="https://success.vanillaforums.com/kb/articles/179-managing-roles-with-sso" rel="nofollow noreferrer ugc">please see this article</a>.</p><h3 data-id="%22allow-this-connection-to-issue-api-access-tokens.%22">"Allow this connection to issue API access tokens."</h3><div class="embedExternal embedImage display-large float-none"> <div class="embedExternal-content"> <a class="embedImage-link" href="https://us.v-cdn.net/6030677/uploads/FAVBHMOMQON6/screen-shot-2020-07-10-at-4-45-16-pm.png" rel="nofollow noreferrer noopener ugc" target="_blank"> <img class="embedImage-img" src="https://us.v-cdn.net/6030677/uploads/FAVBHMOMQON6/screen-shot-2020-07-10-at-4-45-16-pm.png" alt="Screen Shot 2020-07-10 at 4.45.16 PM.png" height="146" width="1942" loading="lazy" data-display-size="large" data-float="none"></img></a> </div> </div> <p>In order to allow Vanilla to access a user's profile data from your authentication provider you have a sent a short-lived access token to Vanilla. You can also use your access token to generate a Vanilla access token for the user so that you can make API calls on behalf of this user against Vanilla. Just toggle on "Allow this connection to issue API access tokens." Here is how it works:</p><p>After generating an access token on your Token endpoint (e.g.<code class="code codeInline" spellcheck="false" tabindex="0"> /oauth/token</code> ) and passing it to Vanilla, use it to <code class="code codeInline" spellcheck="false" tabindex="0">POST</code> to our <code class="code codeInline" spellcheck="false" tabindex="0">api/v2/tokens/oauth</code> with your unique ClientID to receive an access token that you can now use to perform any actions that the user can. </p><p>A call to:</p><pre class="code codeBlock" spellcheck="false" tabindex="0">curl --location --request POST 'https://dev.vanilla.localhost/api/v2/tokens/oauth' \ --header 'Content-Type: text/plain' \ --data-raw '{ "clientID" : "402d75e6-82a7-4d84-a0b5-e5298e97cacc" "oauthAccessToken" : "Ii6JWFSeGgxIkXk3UIU3HWCGejW6nUZn" }' </pre><p>Will return: </p><pre class="code codeBlock" spellcheck="false" tabindex="0">{ "accessToken": "va.kVH976QqVV9WgI_59HDSj2ffKUBuuLxT.SRsKXw.Ut_vRgN", "dateExpires": "2020-07-11T20:04:25+00:00" } </pre><p>Take note of when this token expires and have a strategy to renew it. For more information, so the API v2 / tokens section in your dashboard.</p><h3 data-id="%22make-this-connection-your-default-signin-method.%22">"Make this connection your default signin method."</h3><p>Checking the "Make this connection your default signin method." checkbox in the Settings form will make this the only way to log into your forum or create new users. This will mean that:</p><ul><li>When you click on the default "Sign In" button it will redirect you to your authentication provider to log in. </li><li>The "Username and Password" or "Registration" forms on the forum will no longer be accessible to users. </li><li>Users will <strong>not</strong> be able to edit their profiles on the forum.</li><li>You <strong>will</strong> be able to redirect users to a configured end-point after they log out.</li></ul><p><strong>If you have created a user natively on the forum before setting OAuth2 as the default method for connecting</strong> and need to log in using the "Username and Password" form to log in you can always access it by typing `/entry/password` in the address bar of your browser. Also, when you try to connect over SSO, and the system detects that you have user with the same email address on the forum, you will be asked to enter the password you created when you created the user on the forum. If this becomes problematic, talk to your Customer Success Manager.</p><h3 data-id="logging-out">Logging out</h3><p>You can configure a URL where you would like to redirect a user when he/she logs out of your forum, only if you have checked "Make this connection your default signin method." in the dashboard. This URL can be an end-point on your authentication provider that will then log them out of the "parent" system. If you choose to not log them out of the authentication provider and the user navigates back to the forum and clicks on "Sign In" he/she will be automatically logged into the forum without having to enter a username and password.</p><p>If you wish to redirect the user back to the forum after logging him/her out, append the Sign Out URL with (literally) <code class="code codeInline" spellcheck="false" tabindex="0">?Target={target}</code> and our system will URL encode the URL of the forum and pass it in the Sign Out request on your system as <code class="code codeInline" spellcheck="false" tabindex="0">Target</code>. </p><p>For more log out use cases<a href="https://success.vanillaforums.com/kb/articles/31-sso-overview#logging-users-out" rel="nofollow noreferrer ugc"> please read this article</a>.</p><h3 data-id="troubleshooting-your-oauth2-setup">Troubleshooting your OAuth2 Setup</h3><p>You might not be sure what data you are sending or how it is formatted. Ask your Customer Success Manager to turn on logging. Then you can click on the Event Log link in the left-hand menu to see the logs. Filter on "Event Name" <strong>sso_logging</strong>, scroll down to the bottom of the page to view the filtered logs in either JSON or XML format. Search for "RawProfile" to see what key/value pairs you are sending and compare them to "Profile", what they are being translated to. There will also be helpful error messages here as well.</p><h2 data-id="setting-up-your-oauth2-provider">Setting up your OAuth2 Provider</h2><p>With most SSO providers, you will have four additional requirements:</p><ul><li>Your forum must be accessed over <code class="code codeInline" spellcheck="false" tabindex="0">https</code> by users.</li><li>Your forum must contact your Authorization Server using <code class="code codeInline" spellcheck="false" tabindex="0">https</code>.</li><li>Your Authorization Server will need to allowlist the redirect URI (e.g. <a href="https://[forum-domain].com/entry/oauth2" rel="nofollow noreferrer ugc"><code class="code codeInline" spellcheck="false" tabindex="0">https://[forum-domain].com/entry/oauth2</code></a>)</li><li>Your Authorization Server MUST receive and return the state token in tact that is passed to it from the forum in the authorization request. This is an OAuth2 requirement and a security feature. </li></ul><h2 data-id="seamless-connection-from-your-web-app-to-vanilla">Seamless Connection from Your Web App to Vanilla</h2><p>If you have users logged into your web application and you want to provide a link from your application to your Vanilla application without prompting them to login again, do the following:</p><ul><li>In the Vanilla Dashboard, under Settings>Addons>OAuth2, set the "Prompt" dropdown to either "Consent" or "none".</li><li>In your application, the link you provide from your application to the Vanilla application should be:<ul><li> "https://[your-vanilla-app]/entry/oauth2-redirect" if you only have one OAuth2 connection. Or, </li><li>"<a href="https://[your-vanilla-app]/entry/oauth2-redirect"" rel="nofollow noreferrer ugc">https://[your-vanilla-app]/entry/oauth2-redirect?client_id=[the-client-id-of-your-oauth2-connection]"</a> if you have more than one OAuth2 connection. </li></ul></li><li>This will automatically redirect users back to your web application passing the "prompt" parameter. Your web application will detect that the user is already logged in. Your web application will only stop the user if they have not already given consent to share data with your Vanilla app (a step that will only happen the first time the user connects). The user will then be redirected to, and logged into, Vanilla. If the user does not exist on Vanilla the user will be created and will be logged in. All of this happens "instantaneously" from the user's perspective.</li></ul><h2 data-id="auto-connect">Auto-connect</h2><p>If you want a user to be able to log in through SSO and connect them with their existing user account on Vanilla, you can. Not all of our settings are accessible through user interface. The auto-connect setting can be set by:</p><ul><li>If you are a <strong>cloud customer</strong>, contact your CSM or support and ask to have Auto-connect turned on.</li><li>If you are <strong>self-hosted</strong>, go into<code class="code codeInline" spellcheck="false" tabindex="0"> /conf/config-defaults.php</code> and add <code class="code codeInline" spellcheck="false" tabindex="0">$Configuration['Garden']['Registration']['AutoConnect'] = true;</code></li></ul><p><strong>A word of caution</strong>: if your users can change their email addresses on your authentication application without being verified do not use auto-connect. This could allow them to choose an email address that already exists on the forum allowing them to log in as that forum user.</p><h2 data-id="automating-oauth2-connections-with-javascript">Automating OAuth2 connections with Javascript</h2><p>This section details how a developer on your team could use Javascript to automatically forward a user through the OAuth2 SSO process, creating a more seamless experience. It is not required for any service, nor is it generally recommended (it will generate <em>significantly</em> increased traffic against your identity provider). We do not provide this as a service.</p><p>The following instructions will determine if the user is currently signed into their authentication provider and, if the user is indeed signed in, automatically initiate a SSO login into Vanilla using that authentication provider.</p><h3 data-id="create-a-connection-in-javascript">Create a connection in Javascript</h3><p>First, make a standard HTTPS GET request to the authentication provider’s authorize endpoint. If you’re using Auth0, this is usually something like <a href="https://[eauth-domain].com/authorize" rel="nofollow noreferrer ugc"><code class="code codeInline" spellcheck="false" tabindex="0">https://[eauth-domain].com/authorize</code></a>. Use the following parameters:</p><ul><li><code class="code codeInline" spellcheck="false" tabindex="0">response_type: code</code></li><li><code class="code codeInline" spellcheck="false" tabindex="0">client_id:ABCDEFG</code> (found in the provider’s application settings)</li><li><code class="code codeInline" spellcheck="false" tabindex="0">redirect_uri: <a href="https://[forum-domain]/entry/oauth2" rel="nofollow noreferrer ugc">https://[forum-domain]/entry/oauth2</a></code> (required to initiate SSO on Vanilla’s side)</li><li><code class="code codeInline" spellcheck="false" tabindex="0">scope: openid profile email</code> (can be configured in the OAuth2 settings page in Vanilla)</li></ul><p>The result is a URL which, when visited by a user signed in on the authentication provider, will route the user back to Vanilla to begin SSO authentication. If the user already has an account, they can automatically connect or can automatically create a new account. They will be signed into Vanilla at the end of the request chain. The URL will look something like this: <a href="https://[auth-domain].com/authorize?response_type=code&client_id=1234567890ABCDEFG&redirect_uri=https%3A%2F%2Fc[forum-domain].com%2Fentry%2Foauth2&scope=openid+profile+email" rel="nofollow noreferrer ugc"><code class="code codeInline" spellcheck="false" tabindex="0">https://[auth-domain].com/authorize?response_type=code&client_idABCDEFG&redirect_uri=https%3A%2F%2Fc[forum-domain].com%2Fentry%2Foauth2&scope=openid+profile+email</code></a></p><h3 data-id="test-the-connection">Test the connection</h3><ol><li>Sign in at <a href="https://[auth-domain].com" rel="nofollow noreferrer ugc"><code class="code codeInline" spellcheck="false" tabindex="0">https://[auth-domain].com</code></a> (your actual SSO sign in page)</li><li>Visit <a href="https://[forum-domain].com" rel="nofollow noreferrer ugc"><code class="code codeInline" spellcheck="false" tabindex="0">https://[forum-domain].com</code></a>. Make sure you are not logged in. Clear your cookies, if necessary.</li><li>Visit the “authorize” link described above.</li><li>You should automatically arrive back at <a href="https://[forum-domain].com" rel="nofollow noreferrer ugc"><code class="code codeInline" spellcheck="false" tabindex="0">https://[forum-domain].com</code></a>, but you should now be signed into Vanilla.</li></ol><p>In Vanilla, this can be implemented as Javascript in your page via the Customize Theme feature or a Pocket. Contact support if you need clarification on these steps.</p> </article> </main>