You can use Salesforce as an authentication provider in conjunction with the OAuth 2.0 protocol.
Before setting this up we strongly encourage you to read the section Understand OAuth 2.0, below. If you have any questions, contact Vanilla Support before proceeding.
Salesforce addons
Higher Logic Vanilla (Vanilla) offers two Salesforce addons which have very distinct purposes. Both addons are on the Vanilla Addons page in the Dashboard (Settings > Addons > Addons) and, at a high level:
- Salesforce - Allows users to create leads and cases from discussions and comments.
- Salesforce OAuth2 SSO - Allows users to sign in to your Vanilla community using their Salesforce credentials.
⚠️ IMPORTANT: This addon is the focus of this article.
Understand OAuth 2.0
OAuth 2.0 is not exclusively a single sign-on protocol. It is a more general protocol that is used for authentication between any two applications. So, when Vanilla and Salesforce documentation talk about "OAuth 2.0" connections, they aren't specifically, or even necessarily, talking about users signing in to a site such as Vanilla.
For example, when a user wants to be able to create cases and leads in Salesforce from Vanilla, they are using the OAuth 2.0 protocol to get an access token from Salesforce and then using that access token to make the necessary API calls.
Salesforce SSO using OAuth 2.0 addon
This article describes the set-up process for enabling your users to sign in to your Vanilla community using their Salesforce credentials. For this, we have a dedicated addon, Salesforce OAuth2 SSO, in the Dashboard (Settings > Addons > Addons):
After the addon is enabled and configured (as described below in Enable and configure the addon), a Sign In with Salesforce option displays on your sign-in page which, when clicked, redirects users to the Salesforce log-in page.
📝 NOTE: There a few important differences in the way that Salesforce does OAuth 2.0; these are noted in the configuration steps below.
✔️ TIP: To create an application in Salesforce for single sign-on, check out the Configuring OAuth for Salesforce video.
Enable and configure the addon
Enable and configure the Salesforce OAuth2 SSO addon as described below.
1. Access the Dashboard and navigate to Settings > Addons > Addons.
2. Scroll down to the Salesforce OAuth2 SSO addon and slide the toggle to the right to enable the addon.
3. Click the settings icon to open to the Oauth2 SSO Settings dialog.
4. In the settings dialog, specify your unique values for:
- Client ID
- Secret
- Authorize Url
- Token Url
- Profile Url
- Check the box for Authorization Code in Header.
- Uncheck the box for Basic Authorization Code in Header.
- Uncheck the box for Request Profile Using the POST Method.
- For the endpoints (Register Url and Sign Out Url), consult this Salesforce OAuth Endpoints document.
📝 NOTE: Be sure to specify the domain of your Salesforce application.
5. Scroll down and confirm, or set, the following required values exactly as shown. Note the use of underscores (_) and other characters.
- Request Scope = id profile email
- Email = email
- Photo = photos.thumbnail
- Display Name = display_name
- Full Name = name
- User ID = user_id
- Roles = roles (refer to Roles field and Mapping Roles, below, for information)
- Prompt - login
- Toggle OFF these two settings:
6. Click Save to preserve your settings and exit the dialog.
Roles field
Roles can be passed in a variety of ways. Check the logs to see whether and/or how they are being passed.
✔️ TIP: Navigate to Dashboard > Settings > Technical > Audit Log.
📝 NOTE: If you don't see Audit Log, it might not be enabled in your community. Contact Vanilla Support and request it be turned on.
Roles will not be mapped in the same way as the other profile fields; refer to Mapping Roles, below.
Mapping Roles
To map the Roles, you have to update the config. To do so:
1. Do a test login to see how Roles are being passed.
2. Look for the record that shows the RawProfile, which is the profile that Salesforce passes (before Vanilla translates it into the Profile JSON object which has been mapped to our application). It can be found by filtering Oauth 2 Debug on Action and opening the record with the title "OAuth2 - OAuth2 API JSON Response".
It resembles:
{ "active": true,
"addr_city": null,
"addr_country": "United States",
"addr_state": null,
"addr_street": null,
"addr_zip": null,
"asserted_user": true,
"display_name": "Patrick Kelly",
"email": "pkelly@higherlogic.com",
"email_verified": true,
"first_name": "Patrick",
"id": "https://test.salesforce.com/id/00D590000008iH3EAI/00559000001DSAtAAO",
"is_app_installed": true,
"is_lightning_login_user": false,
"language": "en_US",
"last_modified_date": "2022-06-29T19:36:26Z",
"last_name": "Kelly",
"locale": "en_US",
"mobile_phone": "+1 5148830520",
"mobile_phone_verified": true,
"nick_name": "User16565198955355017485",
"organization_id": "00D590000008iH3EAI",
"custom_attributes": {
"usersroles": ["Agent"]
},
"photos": {
"picture": "https://higherlogic--pkelly.sandbox.file.force.com/profilephoto/005/F",
"thumbnail": "https://higherlogic--pkelly.sandbox.file.force.com/profilephoto/005/T"
},
"status": {
"body": null,
"created_date": null
},
"timezone": "America/New_York",
"urls": {
"custom_domain": "https://higherlogic--pkelly.sandbox.my.salesforce.com",
"enterprise": "https://higherlogic--pkelly.sandbox.my.salesforce.com/services/Soap/c/{version}/00D590000008iH3",
"feed_elements": "https://higherlogic--pkelly.sandbox.my.salesforce.com/services/data/v{version}/chatter/feed-elements",
"feed_items": "https://higherlogic--pkelly.sandbox.my.salesforce.com/services/data/v{version}/chatter/feed-items",
"feeds": "https://higherlogic--pkelly.sandbox.my.salesforce.com/services/data/v{version}/chatter/feeds",
"groups": "https://higherlogic--pkelly.sandbox.my.salesforce.com/services/data/v{version}/chatter/groups",
"metadata": "https://higherlogic--pkelly.sandbox.my.salesforce.com/services/Soap/m/{version}/00D590000008iH3",
"partner": "https://higherlogic--pkelly.sandbox.my.salesforce.com/services/Soap/u/{version}/00D590000008iH3",
"profile": "https://higherlogic--pkelly.sandbox.my.salesforce.com/00559000001DSAtAAO",
"query": "https://higherlogic--pkelly.sandbox.my.salesforce.com/services/data/v{version}/query/",
"recent": "https://higherlogic--pkelly.sandbox.my.salesforce.com/services/data/v{version}/recent/",
"rest": "https://higherlogic--pkelly.sandbox.my.salesforce.com/services/data/v{version}/",
"search": "https://higherlogic--pkelly.sandbox.my.salesforce.com/services/data/v{version}/search/",
"sobjects": "https://higherlogic--pkelly.sandbox.my.salesforce.com/services/data/v{version}/sobjects/",
"tooling_rest": "https://higherlogic--pkelly.sandbox.my.salesforce.com/services/data/v{version}/tooling/",
"tooling_soap": "https://higherlogic--pkelly.sandbox.my.salesforce.com/services/Soap/T/{version}/00D590000008iH3",
"users": "https://higherlogic--pkelly.sandbox.my.salesforce.com/services/data/v{version}/chatter/users"
},
"user_id": "00559000001DSAtAAO",
"user_type": "STANDARD",
"username": "pkelly@higherlogic.com.pkelly",
"utcOffset": -18000000
}
Vanilla doesn't know what the actual name of the Roles attribute will be. It will be in the custom_attributes and it will be an object. Below is an example:
"custom_attributes": {
"usersroles": ["Agent"]
},
In this case, you would have to set the mapping in the Roles field to custom_attributes.userroles to tell Vanilla how to map the Roles.
