Higher Logic Vanilla (Vanilla) provides tailored OAuth 2.0 integrations with these third-party identity providers as ready-to-go addons:
- Facebook
- Twitter
- LinkedIn
- Google+
📝 NOTE: To learn how to use these SSO methods, check out this article.
We also provide a generic OAuth2 addon that works with basic implementations, including support for the third-party services like Auth0 and Okta.
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 community.
Vanilla supports the authorization code grant workflow and the implicit grant flow. To learn about the differences between these two methods for OAuth 2.0, read this article.
Use the OAuth2 addon in Vanilla
As with all our SSO solutions, OAuth2 accounts are mapped to existing community accounts by email address. Vanilla supports Just-In-Time (JIT) provisioning, which means a new account is automatically created if no match is found. You may combine it with any other SSO connections.
A settings form in the Dashboard allows you to define custom parameter names for:
- Client id
- Client secret
Full path to the:
- authorization URI,
- registration URI,
- sign out URI,
- token endpoint, and
- profile endpoint
- Expected keys in the JSON response to the profile request
- Scope
Map user profile values
The Profile endpoint, or user-info endpoint, is expected to return a JSON-encoded array of the user's data (view this article for the expectations). The Profile URL field is required in the OAuth2 addon: Vanilla does not support getting user data from an IDToken.
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 have to map the key names in the OAuth2 addon Settings form. For example, if your authentication provider sends the user's profile like this:
{ "address": "dave@email.com", "pic": "https://cdn.aws.com/ourcdn/davesprofilepic.gif", "name": "Dave", "fullname": "Dave Johnson", "id": 1828838378}
…you have to configure the dashboard accordingly:
The OAuth2 plugin even supports multi-dimensional responses. If your authentication provider's user profile response looks like this:
{ "address": "dave@email.com", "pictures": { "preferred": "https://cdn.aws.com/ourcdn/davesprofilepic.gif" }, "name": "Dave", "fullname": "Dave Johnson", "id": 1828838378}
…you can map it by using dot-notation:
Pass Names over OAuth2
Different communities have different needs in terms of Display Names. Below are a few strategies and how to configure your OAuth2 addon to achieve them.
Display Name controlled by the Identity Provider
- The user has created a Display Name on your "parent" site, the Identity Provider.
In this case, that Display Name should be part of the user's profile and should be returned in the ID Token or the User Profile JSON response, and mapped correctly in the Display Name field of the OAuth2 addon.
Display Name controlled by the Forum
- The user creates a Display Name the first time they connect to the community over SSO.
In this case, you simply do not send a name in the ID Token or the User Profile JSON response when a user logs in. If you cannot alter what profile information is sent from your Identity Provider, you can put a value in the Display Name field of the OAuth2 addon in your Dashboard that does not map to anything. This way, from our system's perspective, no name was sent and the user will be stopped during the first log in and prompted to create a Display Name.
Display Name passed but editable
- The Display Name was passed from the Identity Provider; the user can over-write it on the forum.
In this case, the Identity Provider passes a Display Name in the ID Token or User Profile JSON response. The Display Name is properly mapped and saved in the user's Profile on the community. In order to allow users to then edit their Display Name and not have it over-written every time the user logs in, ask your CSM or Support Agent to set Garden.Registration.ConnectSynchronize to false. Understand that this will mean that once a user has connected to the community for the first time, their user profile will never again be updated with profile information (e.g., Name, Role, Avatar) from the Identity Provider.
Pass Roles over OAuth2
There are two ways to pass users' Roles.
- In Dashboard > Settings > Connections, select OAuth2.
- Add (or edit) a Connection.
- On the General SSO Settings tab, specify the key in the Roles field (as shown) and click Save.
You can also pass users' roles in the profile response.
To pass a user's role (or roles) and have it applied as a role in the community, it must be passed as "Roles" (case-insensitive, plural "Roles"). The value can be a comma-separated list of Roles.
📝 NOTE: Any values specified for "Roles" must exactly match the Role that is configured for your community.
For example:
{ "address": "dave@email.com", "pic": "https://cdn.aws.com/ourcdn/davesprofilepic.gif", "name": "Dave", "fullname": "Dave Johnson", "id": 1828838378, "Roles": "Moderator, Cheerleader"}
Will assign these two Roles to this user:
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 assign Roles to users in the Vanilla Dashboard, and have roles added over SSO, can ask support to configure their community to work in this way.
"Allow this connection to issue API access tokens."
To allow Vanilla to access a user's profile data from your authentication provider, you have to send 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:
After generating an access token on your Token endpoint (e.g., /oauth/token ) and passing it to Vanilla, use it to POST to our api/v2/tokens/oauth with your unique ClientID to receive an access token that you can now use to perform any actions that the user can.
A call to:
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"}'
Will return:
{ "accessToken": "va.kVH976QqVV9WgI_59HDSj2ffKUBuuLxT.SRsKXw.Ut_vRgN", "dateExpires": "2020-07-11T20:04:25+00:00"}
📝 NOTE: Take note of when this token expires and have a strategy to renew it. For more information, refer to the API v2 / tokens section in your Dashboard.
"Make this connection your default signin method."
Check the "Make this connection your default signin method." checkbox in the Settings form to make this the only way to log into your community or create new users. This means:
- When you click the default "Sign In" button it will redirect you to your authentication provider to log in.
- The "Username and Password" or "Registration" forms on the community will no longer be accessible to users.
- Users will not be able to edit their profiles on the community.
- You will be able to redirect users to a configured end-point after they log out.
If you have created a user natively in the community before setting OAuth2 as the default method for connecting and need to log in via the "Username and Password" form, you can 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 in the community, you will be asked to enter the password you created when you created the user. If this becomes problematic, talk to your CSM.
Logging out
Only if you have checked the "Make this connection your default signin method." option can you configure a URL where you would like to redirect a user when he/she logs out of your community. This URL can be an end-point on your authentication provider that will then log them out of the "parent" system.
📝 NOTE: If you choose to not log them out of the authentication provider and the user navigates back to the community and clicks "Sign In," he/she will be automatically logged into the community without having to enter a username and password.
If you wish to redirect the user back to the community after logging him/her out, append the Sign Out URL with (literally) ?Target={target} and our system will URL-encode the URL of the community and pass it in the Sign Out request on your system as Target.
Troubleshooting your OAuth2 setup
If you're not sure what data you're sending or how it's formatted, ask your CSM to turn on logging. Then, you can click the Event Log link in the left menu to see the logs. Filter on "Event Name" sso_logging, and then 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.
Set up your OAuth2 provider
With most SSO providers, you will have four additional requirements:
- Your community must be accessed by users over
https. - Your community must contact your Authorization Server using
https. - Your Authorization Server must allowlist the redirect URI (e.g.,
https://[community-domain].com/entry/oauth2). - Your Authorization Server MUST receive and return the state token in tact that is passed to it from the community in the authorization request. This is an OAuth2 requirement and a security feature.
Seamless connection from your web app to Vanilla
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 log in again, do the following:
Auto-connect
If you have existing users in your Vanilla community prior to configuring your OAuth2.0 connection (either because the users were migrated or they were created using the Vanilla Registration form), Vanilla will attempt to automatically match those users with users logging in via SSO.
The OAuth2.0 connection endpoint will stop during the connection process and prompt the user to enter their password when the email in the OAuth2.0 Profile Response or User Token matches an existing email when connecting for the first time. To avoid this step, you must do both of the following:
- Pass the value
`”email_verified”: true` in the OAuth2.0 user info. - In the config, set
`Garden.Registration.AutoConnect` to `true`.
To change the configuration:
- If you are a cloud customer, contact Vanilla Support and ask to have Auto-connect turned on.
- If you are self-hosted, go into
/conf/config-defaults.php and add $Configuration['Garden']['Registration']['AutoConnect'] = true;
🛑 WARNING: 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 community, which would allow them to log in as that community user.
Automate OAuth2 connections with JavaScript
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 significantly increased traffic against your identity provider). We do not provide this as a service.
The following instructions will determine if the user is currently signed in to their authentication provider and, if the user is indeed signed in, automatically initiate an SSO login to Vanilla using that authentication provider.
Create a connection in JavaScript
First, make a standard HTTPS GET request to the authentication provider’s authorize endpoint. If you’re using Auth0, this is usually something like https://[eauth-domain].com/authorize. Use the following parameters:
response_type: codeclient_id:ABCDEFG (found in the provider’s application settings)redirect_uri: https://[community-domain]/entry/oauth2 (required to initiate SSO on Vanilla’s side)scope: openid profile email (can be configured in the OAuth2 settings page in Vanilla)
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 in to Vanilla at the end of the request chain. The URL will look something like this: https://[auth-domain].com/authorize?response_type=code&client_idABCDEFG&redirect_uri=https%3A%2F%2Fc[community-domain].com%2Fentry%2Foauth2&scope=openid+profile+email
Test the connection
- Sign in at
https://[auth-domain].com (your actual SSO sign in page) - Visit
https://[community-domain].com. Make sure you are not logged in. Clear your cookies, if necessary. - Visit the “authorize” link described above.
- You should automatically arrive back at
https://[community-domain].com, but you should now be signed into Vanilla.
In Vanilla, this can be implemented as JavaScript in your page via the Customize Theme feature or a Pocket. Contact Vanilla Support if you need clarification on these steps.
Additional resources
Click the link below to access a video expanding on what you learned in this article.
