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 need 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 will need 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 roles over OAuth2
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 -- yet. For now, if you want to pass a user's role 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. In order for it to work, it must correspond exactly with name of a Role or Roles 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. For more details on passing Roles over SSO, check out this article.
"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-hand 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:
- In the Vanilla Dashboard, under Settings > Addons > OAuth2, set the "Prompt" dropdown to either "Consent" or "none."
- In your application, the link you provide from your application to the Vanilla application should be:
-
https://[your-vanilla-app]/entry/oauth2-redirect if you only have one OAuth2 connection. Or, https://[your-vanilla-app]/entry/oauth2-redirect?client_id=[the-client-id-of-your-oauth2-connection] if you have more than one OAuth2 connection.
- 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 in Vanilla, the user will be created and logged in. All of this happens "instantaneously" from the user's perspective.
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.
