TABLE OF CONTENTS
- Introduction
- Things to consider before setting up
- Mapping User Attributes
- Access: Feature Access and Data Access
- How to Setup?
- Details
- Troubleshooting SSO Issues
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:
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.
Mapping 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.
Every time a user logs in with SSO, the latest information from the mapped attributes from your IdP get used to reflect on the user in CustomerGauge.
Connecting to Existing CustomerGauge Users
CustomerGauge identifies users by their Email attribute in CustomerGauge. If you want to link users from your Identity Provider (IdP) to existing CustomerGauge users, ensure that unique identifier field for the SSO application in your IdP is set up with the same field that has the same values as the Email attribute in CustomerGauge. This linking happens in the background, and does not need specific mapping in your CG SSO setup.
Microsoft Entra: How to change Unique User Identifier
When using Microsoft Entra, it could be that the standard Unique User Identifier is not in line with the email addresses of users in CustomerGauge. If this happens in your case, you can change the Unique User Identifier for the Enterprise Application set up for SSO with CustomerGauge. Go to the Claims section in the Enterprise Application in Microsoft Entra and edit the Unique User Identifier to the correctly matching attribute. This then connects users between Microsoft Entra and CustomerGauge based on that attribute, rather than the Principal User Name.
Setting up Unique User Identifier as a different attribute than user.principalname allows to match Users based on that different attribute, in case the Principal User Name does not match your pre-existing CustomerGauge users' email addresses.
Edit the Unique User Identifier claim and change the Source attribute to the correct attribute that holds the same email address values as the users in your CustomerGauge system.
Claim Name and Namespace should be URL-Friendly
Some IdPs, such as Microsoft Entra, allow you to configure the Namespace and Claim Name of user attributes. These configurations need to be URL-safe. This means no spaces, and no non-URL safe characters should be used in these configurations in your IdP.
Email address
The 'Email address' attribute is used to identify users in your CustomerGauge system, and is mandatory to map in order to set up SSO. Email addresses in CustomerGauge are unique within the same CustomerGauge system.
Special note when setting up Email claim
We highly recommend for the Application in your IdP to be set up with the identifier attribute as email (e.g. “user.mail” in Microsoft Entra), as well as mapping that same attribute to the CustomerGauge Email Address attribute to ensure data consistency.
Mandatory: Yes
Example IdP attribute name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
Example value inside IdP: [email protected]
Telephone number
The 'Telephone number' attribute is an information field that may help get in contact with other users in your system. It has no functional behaviour in CustomerGauge.
Mandatory: No
Example IdP attribute name: user.phone
Example value inside IdP: +31612345678
Default value in CustomerGauge: (empty value)
First Name
The 'First Name' attribute is an information field that may help to identify a user, or how to call them when trying to contact them. First Name does show up in various areas of the CustomerGauge system.
Mandatory: No, but recommended
Example IdP attribute name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
Example value inside IdP: John
Default value in CustomerGauge: (empty value)
Last Name
The 'Last Name' attribute is an information field that may help to identify a user, or how to call them when trying to contact them. Last Name does show up in various areas of the CustomerGauge system.
Mandatory: No, but recommended
Example IdP attribute name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
Example value inside IdP: Doe
Default value in CustomerGauge: (empty value)
Timezone
The 'Timezone' attribute is a field that controls which Timezone the user will see the system reflected in.
Mandatory: No
Example IdP attribute name: user.zoneinfo
Example value inside IdP: Europe/Amsterdam
Default value in CustomerGauge: The configured Timezone of the System
System Language
The 'Timezone' attribute is a field that controls which System Language the user will see the system reflected in.
Special note about 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:
| Language | Locale value |
| English | en_GB |
| Dutch | nl_NL |
| German | de_DE |
| French | fr_FR |
| Italian | it_IT |
| Spanish | es_ES |
| Portuguese | pt_PT |
| Japanese | ja_JP |
| Thai | th_TH |
Mandatory: No
Example IdP attribute name: user.locale
Example value inside IdP: en_GB
Default value in CustomerGauge: en_GB (English)
Access: 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.
Role Id: 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.
Not mapping Role Id
If no Role Id, or a non-matching Role Id gets provided, the 'User' role will be assigned.
Valid 'Role Id' values
| Role Id (value in IdP) | User Type | Description |
| 1 | Admin | These are the least restricted users, having access to administration features such as Campaigns, Imports, and User management. |
| 86 | User | These are the most common users, having access to reporting features. This will be defaulted to if the Role Id is not provided. |
| 91 | Workflow Plus | These are frontline users who close the loop, and have limited reporting access. |
| 90 | Workflow | These are frontline users who close the loop, and have limited reporting access. |
Mandatory: No
Example IdP attribute name: user.cg_role_id
Example value inside IdP: 1
Default value in CustomerGauge: User (role id 86)
Division Id: Division Data Access Restrictions
Division Data Access controls what 'Division'-field data a user can see in the system. They will only be able to see survey records that is matching the Division Id set up in the IdP.
Valid 'Division Id' values
The value in the IdP must match a the Id of a Division in CustomerGauge. Create a support ticket to identify your Division Ids.
Not mapping Division Id
If no Division Id is mapped, the user will be set to Global and will be able to see all data in the system, regardless of the Division value of Survey Records. Segment Access Restrictions may still apply.
Mandatory: No
Example IdP attribute name: user.cg_division_id
Example value inside IdP: 42
Default value in CustomerGauge: Global
Segment Access Restrictions
Segment Data Access controls what data a user can see in the system. They will only be able to see survey records that is matching the filters set up. You can map up to 5 attributes to map to control the Segment access restrictions.
Not mapping Segment Access Restrictions
If no Segment Data Access Restriction is set up, the user will be set to Global and will be able to see all data in the system, regardless of the Division value of Survey Records. Division Access Restrictions may still apply.
How to set up
You can manage the Segment Access Restriction by adding the relevant fields, and linking it with the appropriate attribute from the IDP. Contrary to other attributes, you map each field in the segment access restriction independently.
Valid Segment access values
The value in the IdP must match a value of that Segment in CustomerGauge, such as "NL" for a user attribute describing Sales Region. This data must come from your IdP and must match existing data in CustomerGauge.
Segment Access Restrictions with multiple values
You can set up Segment 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']
Mandatory: No
Example IdP attribute name: user.custom_sales_region
Example value inside IdP: NL
Default value in CustomerGauge: (empty value)
How to Setup?
Please follow these steps in order to get everything set up:
- Navigate to Users → Single Sign On tab.
- 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 another system, 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 you've configured. - Next, you will need to fill out the information of your Identity Provider:
Select your Identity Provider, and set the prefix (this gets used to ensure users are unique within CustomerGauge).
Note: In the case of Metadata XML - URL is recommended because if things change on the IdP side, you wouldn't need to provide the new XML file to CustomerGauge. If you upload a file and things change in your IdP, 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 G-Suite, 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. - Next, you must map User Attributes to ensure relevant data is passed from your IdP to CustomerGauge.
Depending on your IdP system, the IdP attributes might be slightly different. In some cases this can be something like "user.email", whereas in other cases, such as with Microsoft Entra, this is in a URI format, like "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress". We recommend checking your IdP documentation to ensure the right setup. For Microsoft Entra, we pre-fill some attributes with their common configurations, but feel free to change this if it does not inaccurately reflect your system. - Now it's time to set up Access restrictions, if you wish to do so. Access restrictions allow you to restrict which features and data users can interact with. They'll only be able to interact with survey data that matches the Data Access Restriction configured, and can only access the features available to the Role they have. This is described in more detail in the Access section earlier in this article.
For each field, you'd want to add the IdP Attribute Name or URL (depending on the IdP) into each respective IdP Field Name input field.
- Enter the Button text to make it clear for your users what they can log in with
- When you are ready, you can activate the SSO by either clicking this box and then "Save":
Details
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)
Troubleshooting SSO Issues
Sometimes things don't work the way you hope when setting up Single Sign-On. This article is here to help guide you through the most common issues, and we'll continue to add more scenarios as we discover areas customers have.
Unable to create user
Your system can be set up to avoid creating users on the fly during the SSO process. This may have been set up to ensure the right data access is associated with the users in your system. When you get the error "Unable to create user", you are likely attempting to log in without having a pre-existing user in CustomerGauge. Contact one of your system administrators to ensure you have a user to log in with.
SSO login unavailable
If you receive an Invalid Configuration error when clicking the SSO Login button on the CustomerGauge Login page, this is likely to do with an outdated metadata file. When in CustomerGauge, access the Single Sign-On settings, and review the Metadata file. We recommend using a direct link to the metadata file, opposed to uploading a metadata file, so that you always have the latest version.
Additionally, please review whether the user attributes (primarily Email) is mapped correctly, and populated in your IdP.