Vanilla Forums Documentation Registration & SSO OAuth

OAuth 2.0 Addon

SSO with OAuth 2.0: Overview

Higher Logic Vanilla (Vanilla) provides OAuth 2.0 integrations with these third-party services as ready-to-go addons:

Facebook
Twitter
LinkedIn
Google+

Because OAuth 2.0 is an SSO framework — not a narrowly defined protocol (see OAuth 2.0 Spec) — custom services work is typically required in order to set up an OAuth solution for a community.

Vanilla has created a base class that can easily be extended by custom plugins in order to minimize the amount of custom services work that is required to create SSO integrations.

This base class might look like many of our plugins (containing event handlers, etc.), but it is not intended to be executed directly.

To use this base class, follow the steps in OAuth2 plugin, below.

OAuth2 addon

Vanilla has created an OAuth2 addon that can provide a plug-and-play SSO solution for most customers.

OAuth 2.0 accounts are mapped to existing community accounts by email address, or a new account is created if no match is found.

Workflow

This addon has a workflow of three distinct steps:

An authorization request (request for a code)
A token request (the code is exchanged for an authorization token)
A profile request (by passing the authorization token)

Assumptions

Besides requiring that you follow the workflow above, this addon 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 addon out-of-the-box, and that you will require some level of customization.

All requests from Vanilla are sent with the following header.

Content-Type: application/x-www-form-urlencoded

Authorization Server assumptions

The Authorization Server will expect an authorization request sent by GET with the following parameters:
- response_type => code
- client_id
- redirect_uri => https://[url_of_the_forum]/entry/oauth2
- scope
- state
- client_secret
The Authorization Server will respond to a successful log in by sending a code through GET to the redirect_uri
- client_id
The Authorization Server will expect a token request sent by POST with the following parameters:
- code => [the code returned from the authorization request]
- grant_type => authorization_code
- scope
- the user’s name (display name, nickname)
The Authorization Server will send a JSON response with the variable:
- access_token
The Authorization Server will accept a request for the user’s profile sent by GET with:
- access_token
The Authorization Server will send a JSON response with at least the following:
- a unique ID for the user
- the user’s email

📝 NOTE: This workflow does not support "nonce" support (a hash sent in the state and verified to be unchanged) and refresh tokens.

Features

The OAuth2 addon attempts to "parameterize" as many aspects of the functionality as possible. A Settings form in the Dashboard allows you to set:

The client ID
The client secret
The full path to the authorization URI, registration URI, sign out URI, token endpoint, and profile endpoint
The scope
The expected keys in the JSON response in the profile request

Possible pitfalls

A number of things can go wrong when trying to implement SSO with this addon. To mitigate the likelihood of problems, you should:

Double-check that all the parameters outlined above (in the Assumptions section) are met
Make sure that your community can be accessed over https and can contact your Authorization Server in the same way
Make sure that your Authorization Server adds the following redirect URI to its "allowlist"
- https://[url_of_the_forum]/entry/oauth2