Enable Single Sign-On (SSO) with Community Hub Using OpenId

Nimble AMS allows third-party vendors to provide a Single Sign-On (SSO) experience with their systems using Community Hub as the Identity Provider. This is accomplished using OpenId and OAuth 2 from Salesforce.

Pre-Requisites

  • Community Hub is active and accessible in the Salesforce organization (org).

Setup

Each vendor using SSO must have their own Connected App from Salesforce. The Connected App has their Consumer Key and Consumer Secret that identifies their system along with their settings. The Consumer Key and Consumer Secret are also known as the client id and client secret.

Create a Connected App 

  1. Log in to Salesforce as an Admin.

  2. Open Setup → Build → Create → Apps.

    1. Scroll to the bottom of the page.

  3. Click New in Connected Apps.
  4. Enter the Connected App settings.

    1. Connected App Name - Enter the name of the Vendor followed by the name of the system in case the vendor has multiple systems. For example, “Vendor CMS” or “Vendor LMS”.

    2. API Name - Let the default API name be used.

    3. Contact Email - The email of the individual or team responsible for maintaining the integration.

    4. Description - While this is optional, enter a brief description of the vendor and system so others know what this relates to.

    5. Enable OAuth Settings - This needs to be checked. After this is checked, additional OAuth settings are shown.

    6. Callback URL - Enter the https URL(s) that Salesforce redirects to when someone successfully authenticates in Community Hub. If one is not known at this time, use “https://service.nimbleams.com/openidtester/login.aspx”. This is NimbleUser’s openid tester page. Once the page or pages are known, update the Callback URL(s).

      1. Note: The OAuth protocol requires that SSL be used.

    7. Add the following OAuth Scopes to the Selected OAuth Scopes

      1. Access your basic information (id, profile, email, address, phone)

      2. Allow access to your unique identifier (openid)

    8. The Web App Settings, Custom Connected App Handler, Mobile App Settings, and Canvas App Settings are unneeded.

  5. Save
  6. Click Continue to acknowledge that it’ll take up to 10 minutes for the SSO to be available with Salesforce.

Post Connect App Creation Steps

Security Settings

  1. Open Setup → Administer → Manage Apps → Connected Apps.

  2. Click the Label of the Connected App to update.

  3. Click Edit

    1. Update Permitted Users to “Admin Approved users are pre-authorized”. This bypasses the prompt to users to "Approve / Authorize the app".

      1. Click ok to the prompt.

    2. Refresh Token Policy - Ensure “Immediately expire refresh token” is checked if it’s not already.

  4. Click Save

Granting Connected App Access to Nimble AMS Integration Profile 

  1. Open Setup → Administer → Manager Users → Profiles

  2. Click Nimble AMS Integration

  3. Click Assigned Connected Apps

  4. Click Edit

  5. Add the Connected App to the “Enabled Connected Apps” list.

  6. Click Save

Granting Connected App access to Community Hub 

  1. Open Setup → Administer → Manager Users → Profiles

  2. Click Community Hub Login User

  3. Click Assigned Connected Apps

  4. Click Edit

  5. Add the Connected App to the “Enabled Connected Apps” list.

  6. Click Save

Share OpenId Settings With Vendor

After the Connected App is created and configured, the vendor has to be informed what the consumer key and consumer secret are so they can be supplied from their system and be used within the Single Sign-On with Community Hub. The vendor also has to be informed of the Community Hub login URL since they differ between each Salesforce organization / environment.

Finding the Consumer Key and Consumer Secret

  1. Log in to Salesforce as an admin.

  2. Open Setup → Build → Create → Apps and scroll to the bottom of the page.

  3. Click the name of the desired Connected App.

  4. Consumer Key - is the id of the connected app that identifies the system. This is also known as the client id.

  5. Consumer Secret - This is the shared token passed to the token endpoint from the Callback URL page(s) so that Salesforce knows this is the actual system and not a malicious user. To see the value, click the “Click to reveal” link and the consumer secret is shown.

Finding Community Hub URL

Each Salesforce organization / environment has its own Community Hub URL so the one used for Staging will be different from the one used for production. Each one has to be shared with the vendors so they know which to use for each environment.

    1. Log in to the Salesforce org as an admin.

    2. Open Setup

    3. Type in “Comm” in the Quick Find.

    4. Click “All Communities”

    5. For the Community Hub community, highlight the URL and copy it so that the Text of the link is copied instead of the underlying URL. The underlying URL must not be used.

Custom Attributes

By default, OpenId returns user information such as name, email, and other demographics when the userinfo endpoint is invoked. On each connected app, an admin can designate other custom fields to return. These fields can come from labels, organization fields, profile fields, public hierarchy custom settings, System, or the user record. Community Hub users are tied to an account record indirectly but are inaccessible from the Custom Attribute feature. See the "Adding Account Custom Attributes" section below on how to use Account fields.

Adding Custom Attributes

  1. Open Setup → Build → Create → Apps and scroll down to the Connected Apps section.

  2. Click the name of the desired connected app.

  3. In the Custom Attributes section, click New.

  4. Enter Settings

    1. Key - This is the name of the field that will be passed back in the UserInfo service.

    2. Value - This is the API name of the field (eg. $User.Phone)

  5. Save

  6. Repeat 1-5 to add other fields as needed.

Adding Account Custom Attributes

Account fields must be brought across to a related User field using the “Field Mapping” custom setting. Formula fields are not allowed for Custom Attributes.

To pass back custom fields from the account using Field Mapping,

  1. Duplicate each Account field as a new User custom field.

  2. Log in through the LMA to the org and add a Field Mapping Custom Setting record between Account and User so that the system will keep the account fields and user fields updated as they change.

    1. Note: Only NimbleUser can do this at this time.

    2. Note that the Destination and Source language is backwards. Mimic the screen capture below.

  3. Add a custom attribute for each field on the desired connected app(s). See Adding Custom Attributes for how to do this. Be careful-- there are two places that show “Custom Attributes” but only one set is valid.

  4. Manually trigger the Custom Attributes to update with:

    1. Database.executeBatch(new NC.SyncAllRecordJob());

  5. Check that Selected OAuth Scopes includes:

    1. Access and manage your data (api)

Logout

At this time, Community Hub only supports logging out with one other system.

When a user logs out of the third-party system, it should redirect to the Community Hub logout URL and then redirect to the third-party system’s logout URL that’s specified in Community Hub.

The Community Hub logout URL is "<Community_Hub_URL>/secur/logout.jsp”. To determine the Community Hub Url, see Finding Community Hub URL above.

For example, if a user logs out of system A, which has an SSO with Community Hub, the user is redirected to the Community Hub logout URL and then redirected to the configured system A logout URL that is configured in Community Hub. If one logs out of Community Hub, the user is logged out of the external system too.

Specifying Community Hub Logout URL

The following are the steps needed to designate where Community Hub redirects to after someone logs out of Community Hub.

  1. Open Setup

  2. Type in “Comm” in the Quick Find.

  3. Click “All Communities”.

  4. Click Manage for Community Hub.

  5. Click Administration on the left.

  6. Click Login & Registration.

  7. Enter the desired logout URL in the URL field under the Logout section.

  8. Save.

Creating Community Hub Account

  1. Open the Community Hub URL

  2. Click “Don’t have an account”.

  3. Enter the contact and login information.

  4. Click Create Account.

Testing With NimbleUser OpenId Tester

NimbleUser has an internal tool called OpenId Tester to help confirm if the base configuration for OpenId has been configured correctly before handing off the configuration by testing by a third party. The feature confirms that the correct user credentials have been provisioned, the correct URLs are being referenced, and the correct keys are being referenced. (Note to NimbleUser staff: The tool is documented in Confluence). OpenId tester is not available for external use, however there are other similar tools available:

  • Chrome Extension: Advanced Rest Client
  • Executable: Post Man
  • For some testing of the Nimble Integration Framework, you can use Workbench > Utilities > Rest Explorer