Discover. Learn. Grow.

TABLE OF CONTENTS

Introduction

Things to consider before setting up

System Language

User Attributes

Access Restriction

How to Setup?

Details

Introduction

CustomerGauge's Single Sign On (SSO) functionality supports any system/identity provider (IDP) that is compliant with the SAML2.0 protocol. This includes both Standard and Custom/Company Specific systems. 

Some examples of common standard systems are as follows:

• Salesforce 
• Microsoft Entra (a.k.a. Azure Active Directory)
• F5
• GSuite/Google 
• Okta

Things to consider before setting up

• You will need global Admin access in CustomerGauge and sufficient access to your Identity Provider.
  
• If you do not set up Role Id in your IDP, users will be granted access with User-role feature access restriction.
• If you do not set up Data Access Restriction in your IDP, users will be granted access without data access restrictions.
• Once your IDP instance is activated, a SSO Login button will be added to your account's login page. Your users can click this button while you're still setting this up.
• Users created prior to setting up SSO will retain Direct Access, in addition to being able to log in with SSO. Users created as part of logging in with SSO will not have Direct Access.

System Language

The system language of a user can be defined through the "Locale" user attribute in your IdP set-up in CustomerGauge. If no Locale attribute is configured, or your IdP holds an unsupported value, the user will be created with English as their system language.

The following languages are supported:

User Attributes

User Attributes are details about the user - some of which are functional, while others are purely informative. Users Attributes are also one of the most common areas where we see customers struggle setting up. When mapping the user attributes, you're defining how we can find the information in your IdP to store in the attribute in CustomerGauge. The values to add in your SSO configuration can differ from IdP to IdP, so always make sure to check in your IdP what the right configuration would be.

Noteworthy attributes

• Email is a required attribute.
• Role controls which features the user will have access to.
• Locale controls which system language the user will be in.

Examples

In Microsoft Entra (formerly known as Azure Active Directory) the attributes are usually as follows (but keep in mind this can be different in your case):

Access Restriction: Feature Access and Data Access

Just like regular users, SSO users can be restricted to certain features, and restricted to seeing only data they're supposed to see. You can do this either automatically, as part of your SSO setup, or manually in the User Manager. We'll dive into the SSO setup here.

Feature Access

You can manage the user's Role, which controls the set of features available to them by providing the Role Id as part of the User Attributes. The IDP needs to hold the ID number in an attribute to be passed as part of the Single Sign-On process. If no Role Id, or a non-matching Role Id gets provided, the 'User' role will be assigned.

• Admin: Role Id '1' - these are the least restricted users, having access to administration features such as Campaigns, Imports, and User management.
• User: Role id '86' - these are the most common users, having access to reporting features. This will be defaulted to if the Role Id is not provided.
• Workflow Plus: Role id '91' - these are frontline users who close the loop, and have limited reporting access.
• Workflow: Role id '90' - these are frontline users who close the loop, and have limited reporting access.

Data Access

Data Access controls what data a user can see in the system. They will only be able to see data that is matching the filters set up. If no Data Access Restriction is set up, the user will be set to Global and will be able to see all data in the system. You can manage the Data Access restriction by adding the relevant fields, and linking it with the appropriate attribute from the IDP.

Data Access with multiple values

You can set up Data Access Restriction with multiple values in the same field. For example, NL and BE for a user attribute describing Sales Region. The value in your IDP for this user attribute needs to be in a JSON-encoded array:

['NL', 'BE']

How to Setup?

Please follow these steps in order to get everything set up:

1. Navigate to the Settings --> Single Sign On (SSO) and click "+ Add IDP":
   
   
   
   
   
2. In your IDP, you will need to copy the "Entity ID" and "Assertion Consumer Service URL" into the relevant areas for that in your IDP app configuration when setting up your app for CustomerGauge:
   
   
   Note: If you use a system like Okta, the third item "Login URL" may also be required to enter into your IDP (so that it directs to the appropriate login page). If using other systems, please simply share this special login page with your users (after you've finished the remaining steps) so that they can log into CustomerGauge using the IDP(s) you've configured.
   
   
3. Next, you will need to fill out the information of your Identity Provider:
   
   
   Note: In the case of Metadata XML - URL is recommended because if things change, you wouldn't need to provide the new XML to CustomerGauge; we'd have the changes automatically as the XML is provided via URL. If you upload a file and things change, you may need to upload the new XML file to CustomerGauge in order to guarantee your SSO configuration continues to operate smoothly.
   
   However, some systems, such as GSuite, do not provide the option of a metadata XML URL, and only provide a downloadable file. If that's the case, you can select the "File Upload" option from the dropdown instead:
   
   
   Then simply click the "Browse File" button to upload the XML data from your local device, and be sure to re-upload a new one if things change in the future.
   
   
4. Next, you must provide the User Attribute Mapping to ensure any data you want to be associated with a user is passed to CustomerGauge upon initial user creation. Before doing this though, it's important to understand how the user creation element works:
   
   Once you've configured your SSO IDP, when someone tries to log in using their IDP credentials, CustomerGauge will check the email address of the user that the login request is coming from. If this is a new user and the same exact email address does NOT already exist in CustomerGauge, then we will create a user license in CustomerGauge for that user and will include any attributes you specify that have been mapped in the User Attribute Mapping section.
   
   If, however, the email address of the user who initiated the login request already exists (existing user) with a username in CustomerGauge (meaning they've either already logged in via SSO once before, or they've had a username created manually by a CustomerGauge Admin), then CustomerGauge will just authenticate them and associate their SSO login request with that already-existing user. In this case, we will NOT look at the attributes being passed with the user, only the email address. Any changes to user attributes for users that already exist in CustomerGauge must be made in the CustomerGauge User Manager, which all Admins have access to.
   
   OK, now that you understand the user creation element, here are the instructions for how to do the mapping. All you need to do is select the CustomerGauge Attribute name on the left and then enter the Attribute name as it's stored in your IDP on the right (Note: If the shortname like EmailAddress does not work, please try with the complete uri of the attribute as available in your metadata file ex., http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress). As you might expect, based on the details provided above, mapping the "Email" attribute is mandatory. All other fields are optional. For more information on the user attributes we offer, please see this article.
   
   For a handy infographic of which attributes feed into which sections of your User Manager Details Page, see here:
   
   
   
5. Now it's time to set up Data Access Restriction, if you wish to do so. Data Access Restriction allows you to restrict which data users can interact with. They'll only be able to interact with survey data that matches the Data Access Restriction configured. You can add multiple fields to apply Data Access Restriction on - survey records need to match all the fields for a user in order to show up for that user. This data must come from your IDP and must match existing data in CustomerGauge.
   
   For each field, you'd want to add the IDP Field Name or URL (depending on the IDP) into each respective IDP Field Name input field.
   
   
   
6. Enter these remaining SSO Details and then "Save" once you are done!
   
   
   
   
7. When you are ready, you can activate the SSO by either clicking this box and then "Save":
   
   
   Or by going to your "Deactivated IDPs" section and clicking this checkmark:
   
   

Details

Connecting multiple IDPs to 1 CustomerGauge platform

You may be in a situation where some of your users have access to Salesforce, but others don't. But they do have access to GSuite (or Okta, etc.). You can have as many IDPs connected to your CustomerGauge platform as you need! Most of our customers only require 1 or 2 max, but you can add more than that if your situation requires.

Using the same IDP for multiple CustomerGauge Platforms 

You can use the same IDP for multiple CustomerGauge Platforms. Just configure the same settings in the other platform(s) using the steps above

Direct access for SSO Users

Your users may want to have the ability to log into CustomerGauge directly (not via SSO) using a username and password. As you saw in point 4 above, some of your users might have already had direct access prior to accessing CustomerGauge via SSO. However, if you have users who have only ever accessed CustomerGauge via SSO, they won't have direct access to CustomerGauge (yet). If they would like (not mandatory), they can also set up a direct access username and password with CustomerGauge from their "My Profile" page. This could be helpful in situations where the IDP you are using for SSO has an outage or your users get locked out of their IDP and need to access CG urgently.

Deleting SSO Users

Users who have SSO access to CustomerGauge cannot be deleted, but you can deactivate them. Deactivating users both prevents them from accessing CustomerGauge and also does not count towards your overall, contractual user license limit. We don't allow deletion of SSO users because the user would just end up being created again if they attempted to log into CustomerGauge from the IDP, unless you were to have deleted them or revoked their access from the IDP itself as well. Deactivation, therefore, is how you both prevent users from logging into CustomerGauge via SSO as well as maintaining your contractual user limit.

Handling SSO Users in your User Manager

Your User Manager comes with a few quick and easy ways to identify (and manage) SSO users. As mentioned previously, and changes you want or need to make to a user's attributes after they've already been created as a user in CustomerGauge can be handled in the User Manager by editing the user as normal. You also have the ability to filter between the different types of users (all user types, those who are direct access only, SSO access only, or both)