Higher Logic Vanilla (Vanilla) provides tailored OAuth 2.0 integrations with the following third-party identity providers as ready-to-go addons:
- Facebook
- Twitter
- LinkedIn
- Google+
📝 NOTE: To learn how to use these SSO methods, check out Social Connect Options.
We also provide a generic OAuth2 addon that works with basic implementations, including support for the third-party services such as Auth0 and Okta.
✅ TIP: If you do not currently have an OAuth 2.0 identity provider, we recommend using a third-party provider instead 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, see the okta developer 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 as shown below:
{
"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 Display Names over OAuth 2.0
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 community
- 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 Display 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 community.
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 on subsequent log ins, ask your CSM or Support Agent to set Garden.Registration.ConnectSynchronize to false.
⚠️ IMPORTANT: Understand that as a result of this: once a user connects 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 OAuth 2.0
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 as it is configured in 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 user Dave Johnson:
By default, Vanilla will re-assign the user's Roles every time the user logs in over SSO, giving your authentication provider full control over the user's Roles.
📝 NOTE: Cloud customers who want to assign Roles to users in the Vanilla Dashboard and have roles added over SSO, can contact Vanilla Support and request that their community be configured to work in this way.
- For more details on passing Roles over SSO, see:
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 use your access token to also generate a Vanilla access token for the user so that you can then make API calls on behalf of this user against Vanilla. To do so:
- 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 then 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 box for Make this connection your default signin method. in the Settings form to make this the only way:
- to log in to your community and
- to create new users.
As a result:
- When you click the default "Sign In" button, you will be redirected to your authentication provider to perform the log in.
- The "Username and Password" and "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.
Notes
If you have natively created a user in the community before setting OAuth 2.0 as the default method for connecting and you 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 a user with the same email address in the community, you will be prompted to provide the password that was created when the user was created. If this becomes problematic, talk to your CSM.
Logging out
Only if you have checked the Make this connection your default signin method. box can you configure a URL where you would like to redirect a user who 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 the user out of the authentication provider and the user navigates back to the community and clicks "Sign In," the user will be automatically logged in to the community without having to enter a username and password.
If you wish to redirect the user back to the community after being logged 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.
- To learn more about user log outs, see:
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 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 OAuth 2.0 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 intact that is passed to it from the community in the authorization request. This is an OAuth 2.0 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.
