Single Sign-On (SSO) for Authenticating SurveyGizmo Users

SAML SSO is available as an add-on.
If you are interested in SSO, please contact us for additional information.

Are you already using an Identity Provider (IdP) to manage logins and access to the various systems your users need to access? If so, you can now include SurveyGizmo as a Service Provider (SP) as part of this single sign-on (SSO).

We support any IdP that uses the SAML 2.0 protocol. At this time, we have tested SSO from Active Directory Federated Services (AD FS) and Azure (AD FS).

SSO Options in SurveyGizmo

Within SurveyGizmo you can use SSO to...

1. authenticate users into the SurveyGizmo application to build and administer surveys. This tutorial will cover this option. 

and/or

2. authenticate respondents into surveys. This option is covered in our SSO Authentication for Survey Respondents Tutorial.

In both cases SSO acts as an added security layer. When using SSO for authenticating survey respondents there is also the added benefit of prepopulation; any data present for each user in the IdP can be automatically passed into the survey, which can then be used within the survey itself or in reporting.

Why SAML SSO?

When security is of paramount importance, organizations will set up an Identity Provider (IdP) to manage all logins for all users. This allows IT professionals at the organization to control the number of logins out there in the wild. Identity providers also allow IT professionals to set up password reset rules to increase security.

If you are not already using an IdP you probably won't start just for SurveyGizmo.

How Does It Work?

Single sign-on allows organizations to set up a trust relationship with a service provider (SurveyGizmo in this case) that allows the IdP to send encrypted login credentials to the service provider thus preventing the user from having to log in more than once, hence single sign-on.

What You Will Need Before You Get Started

If you're not an IT professional at your organization, go get one; you'll need his or her assistance to set this up.

First, you'll need the below ingredients from your IdP; your IT professional can help you with this.

Entity ID - This is the globally-unique URL/string of your IdP entity. It's like a mailing address that we, the service provider, use to contact your IdP. Not sure where to find this? Learn more.

Login URL - This is the URL for logging in to your IdP. The Login URL is often very similar to the Entity ID URL. This is where we will send the SAML request.

SSL Certificate - We'll use your SSL certificate to encrypt the data being sent back and forth via SAML. You will need to upload your SSL Certificate from your IdP. Not sure where to find this? Learn more in our glossary of SSO terms.

SurveyGizmo-Side Setup

You must be an administrative user in SurveyGizmo in order to access these settings.

1. Go to Account > Integrations > 3rd Party Integrations and click the Configure next to the SSO Users option. 

2. Give your SSO Integration an Internal Name. This is particularly important if you plan to use SSO both for authenticating users and for authenticating survey respondents as this name will display when setting up SSO authentication within surveys. 

3. Choose the Authentication type > Allow Users to log in to the SurveyGizmo Application

4. Under SAML Settings choose whether you wish to Pull SAML settings from Identity Provider Metadata or Enter SAML settings manually.  

a. In order to use the option to Pull SAML settings from Identity Provider Metadata your metadata will need to be hosted somewhere so that you can provide a URL for our system to access and parse it. 

i. Enter the URL to your hosted metadata xml file in the Identity Provider Metadata URL field

b. If you prefer to enter your SAML settings manually, populate the Entity ID, Login URL, Logout URL, and SSL Certificate from your IdP. These fields are required. 

Manual Setup Tips:
  • If you do not wish to provide an actual LogoutURL you can enter your Login URL in the Logout URL field.
  • This is your certificate file (.crt) for your IdP which can be downloaded from your SSL Issuer. 
    • Files must include the the begin and end tags. The result should look like this:
      -----BEGIN CERTIFICATE-----
      (Your Primary SSL certificate: your_domain_name.crt)
      -----END CERTIFICATE-----
    • Files must be Base64 encoded.
    • Use this SSL Checker to validate your file.
    • If the file you have also has the ‘intermediate’ or ‘root’ certificate chains in them, that’s fine, as long as it has the main certificate for the domain included.

5. When you are finished with the SAML Settings click Save and Get Metadata. The following Service Provider Metadata XML will be provided to you for you to use in the IdP Setup.

Integration Not Successful?

If the option to pull from metadata does not work we recommend trying the manual setup option. If you've tried both and neither were successful check out our troubleshooting tips for common causes of failure. 

6. (Optional) Automatic User Disabling - If you wish to disable users due to inactivity select this option and specify the number of weeks you wish to have pass before doing so. Please be aware of the below limitations for this option:

  • This setting will not apply to account administrators
  • The deactivation process will run once per day.

7. (Optional) Restrict Login to SSO Only - If you wish to only allow users to access SurveyGizmo via your IdP, check this box. If you wish to allow users to login via either way, IdP or SurveyGizmo, leave this unchecked.

The Restrict Login to SSO Only Setting  will affect both who can access SurveyGizmo and how they will access SurveyGizmo.

  • If the Restrict Login to SSO box is unchecked all users will be able to log in via both the IdP and SurveyGizmo, with the exception of users created via SSO.
  • If the Restrict Login to SSO box is checked, any users that attempt to login directly via SurveyGizmo will not be able to and will see the following message:

    This account is restricted to Single Sign-On only. Please contact your account admin for assistance.


  • Administrative users that were created in SurveyGizmo will always be able to log in via both the IdP and SurveyGizmo regardless of the status of the Restrict Login to SSO option. 
  • Users created via SSO will only be able to login via the IdP.

8. Next, there are two options that control how user seats in SurveyGizmo are handled:

Users must be set up in SurveyGizmo - This means that administrative SurveyGizmo users will need to log in to SurveyGizmo via the SurveyGizmo log in page and add users as described in our Add Users Tutorial. Once a user is set up then the SSO via the IdP will work.

OR

Automatically create new users if they don't exist in SurveyGizmo - This option will create SurveyGizmo users when users click the link/button to log in to SurveyGizmo if a user with those credentials doesn't already exist in SurveyGizmo.

If you choose to automatically create new users, you'll need to specify a Default Role, Team, and License for these newly created users. 

You will need to have enough licenses available in order to create the user. If there are no available licenses of the type you selected in the Default License field, the user will be created but disabled. 

Check out our Teams and User Permissions Tutorial to learn more about Teams and Roles! Check out our User License Tutorial to learn about licenses. 

As an alternative to selecting a default role and team, you can select the option to set up all SSO created users as Standalone Users. Standalone users will only be able to see the surveys that they create, regardless of team or role. Standalone users will have full access (meaning they will be Editors) to their own surveys (provided that their user license supports survey editing).

Finally, if you are automatically creating new users, it is a good idea to add an email address in the New User Notification Email field for the SurveyGizmo to send notification of user creation errors.

9. When you are finished with all of your User Settings the Login Link at the bottom of the page can be used to create a button within your IdP to log users into SurveyGizmo. This link will not work until you complete the IdP Setup below.

IdP-Side Setup

Regardless of your specific IdP vendor,  the setup on the IdP side requires:

  • A claim rule with user's email address in SurveyGizmo passed as the as the Name ID.
  • (Optional) additional data from attributes can be sent to populate User Data Fields. Learn more about populating User Data Fields.

 See a step-by-step example of the IdP-side setup with Active Directory (AD FS)

These setup instructions will walk you through the basic settings for SSO setup in Active Directory (AD FS).  

Launch the AD FS Management Console. Then, go to Trust Relationships > Relying Party Trusts > Add Relying Party Trust. This will open the Add Relying Party Trust Wizard. Click Start.

Chose the Import data about the relying party published online option and copy and paste your SurveyGizmo SP Meta data URL in the Federation metadata address field. Click Next.

Leave the default option selected for multi-factor authentication and click Next.

On the next screen leave the option to Permit all users to access this relying party selected and click Next.

Review your settings and click Next.

On the next screen leave the option to Open the Edit Claim Rules dialog selected and click Close.

This will take you to the Edit Claim Rules dialog where you will need to a rule. Get started by clicking Add Rule.

In the Claim rule template dropdown menu, select Send LDAP Attributes as Claims and click Next.

We're going to pass through the users email address in SurveyGizmo as the Name ID claim type so name the rule as such.

Select Active Directory in the Attribute Store dropdown menu. 

Select E-Mail-Addresses (or the field in the IDP that matches the users' email in SurveyGizmo) from the LDAP Attribute dropdown menu and Name ID  in the Outgoing Claim Type Dropdown and click Finish and Apply.

Adding Email to Name ID Claim

Once you finish your IdP setup go back to SurveyGizmo and copy your Login Link. When you go to this link via a browser you will be taken to your IdP login page. Once you log in, you'll be taken to SurveyGizmo.

If this didn't work check out our troubleshooting tips below.

If this does work, now you're ready to set up a button or link for your users to access SurveyGizmo!

Important Note Regarding Maintenance of Your SSO Integration

As we need to periodically update the cert used to create an SSL connection for SSO, we recommend putting a check in place so that your SSO integration is seamless. Once your integration is successfully set up, a simple script that checks for differences between the metadata in your integration setup and our SP metadata URL and accordingly handles updates to your integration ensures that there is no interruption in service.

FAQ

 How do I integrate with a sandbox environment?

You can set up as many SSO integrations as you wish under Account > Integrations > 3rd Party Integrations. To test SSO using a sandbox environment simply set up a separate integration here. 

 What do I need to know to log existing SurveyGizmo users into that user via SSO?

The Name ID that you pass into SurveyGizmo to identify the user must be the same as their Email field in SurveyGizmo. In the IdP setup above we added a rule to set Name ID = UPN (the users IdP email address).

 Will users still be able to log in with their login and password?

This depends on how you set this up. If you wish to allow your users to continue to login via the SurveyGizmo with their username and password make sure to leave the option to Restrict Login to SSO Only unchecked.

 Will my IdP login credentials work to log me into the SurveyGizmo login page?

This depends on a couple of factors: (1) your Restrict Login to SSO setting and (2) how the user was created.

  • If the Restrict Login to SSO box is unchecked all users will be able to login via both your IdP and SurveyGizmo, with the exception of users created via SSO.
  • If the Restrict Login to SSO box is checked, any users that attempt to login directly via SurveyGizmo will not be able to and will see the following message:
    This account is restricted to Single Sign-On only. Please contact your account admin for assistance.
  • Administrative users that were created in SurveyGizmo will always be able to login via both your IdP and SurveyGizmo regardless of the status of the Restrict Login to SSO option. 
  • Users created via SSO will only be able to login via the IdP.

 What happens if users try to log into the SurveyGizmo login page with IdP credentials?

This depends on a couple of factors: (1) your Restrict Login to SSO setting and (2) how the user was created.

  • If the Restrict Login to SSO box is unchecked all users will be able to login via both your IdP and SurveyGizmo, with the exception of users created via SSO.
  • If the Restrict Login to SSO box is checked, any users that attempt to login directly via SurveyGizmo will not be able to and will see the following message:
    This account is restricted to Single Sign-On only. Please contact your account admin for assistance.
  • Administrative users that were created in SurveyGizmo will always be able to login via both your IdP and SurveyGizmo regardless of the status of the Restrict Login to SSO option. 
  • Users created via SSO will only be able to login via the IdP. If they try to login via the SurveyGizmo login page they will receive a message letting them know that login is restricted to SSO only.

 What happens if the IdP is unavailable? Typically you'll receive a browser message that the page cannot load.

We cannot throw an error in this case. Typically you'll receive a browser message that the page cannot load.

 What happens when a SurveyGizmo session expires?

SurveyGizmo sessions expire after 2 hours of inactivity. If this happens the Continue Working link that displays in SurveyGizmo will not work. Users will need to use the login link/button to log back into SurveyGizmo.

 Can I populate User Data Fields with SSO attributes?

You can! Data from attributes will populate User Data Fields by default as long as the following requirements are met:

  • User Data Fields must already be set up. Learn more about setting up User Data Fields
  • Your SSO Attributes and User Data Field names must match exactly (case sensitive).

 Can SurveyGizmo supply a SAML Service Provider metadata file?

Yes. Here is an example of our metadata XML. Please note that the metadata will vary for each customer; when you set up SSO and enter your settings, the metadata file for your setup specifically will be generated.

Take your login URL and append a query string with r parameter like so:

 Can SurveyGizmo's SAML consume the SAML IdP metadata file?

Yes.

 What attributes does SurveyGizmo require within the SAML assertion?

NameID must be in the subject of the assertion.

 Does SurveyGizmo have a platform for testing identity federation?

No.

 Does your SP support SAML Single Logoff?

No.

 Does your SP support a logoff redirect following termination of the user session?>

No.

 Does your SP sign the authentication (authn) requests that it sends to the SAML IDP?

Yes.

 Does your SP require a signature and/or encryption of the assertions issued by the SAML IDP?

Yes.

 Explain the user authorization mechanism employed by your SAAS application.

Username and password form or SSO.

 Can your SAAS application accept authorization (role membership) data from the SAML assertion?

No, we assign it.

Troubleshooting

 I entered by entity ID, Login and Logout URLs and uploaded my certificate and my integration was not set up. What am I doing wrong?

Often this is due to a invalid certificate. Make sure that you are uploading a valid .crt file. Files must be Base64 encoded and must include the the begin and end tags. The result should look like this:

-----BEGIN CERTIFICATE-----
(Your Primary SSL certificate: your_domain_name.crt)
-----END CERTIFICATE-----

Use this SSL Checker to validate your file.

 If your Entity ID or Login URL are incorrect you will receive an error.

The content of this error varies so if you receive an error during set up check that both of these fields are populated correctly.

Glossary of SSO Terms

 Active Directory Federated Services (AD FS)

Microsoft's IdP software.

 Entity ID

This is the globally unique URL/string of your IdP entity. It's like a mailing address that we, the service provider, use to contact your IdP.

Your Entity ID can be found in your AD FS Management Console by right-clicking the AD FS Folder and selecting Edit Federation Service Properties. 

The URL in the Federation Service identifier field.

 Identity Provider (IdP)

The source of truth for usernames and passwords.

 Login URL

This is the URL for logging in to your IdP. The Login URL is often very similar to the Entity ID URL. This is where we will send the SAML request.

 Name ID

Unique string to identify users. When sending Name ID to SurveyGizmo we recommend it be their email address.

 Service Provider (SP)

The web-based application/s that are accessed via the IdP.

 Security Assertion Markup Language (SAML)

an XML standard that allows secure web domains to exchange user authentication and authorization data. Using SAML, an online service provider can contact a separate online identity provider to authenticate users who are trying to access secure content.

 Single Sign-On (SSO)

Provides partner companies with full control over the authorization and authentication of hosted user accounts that can access web-based applications.

 SSL Certificate

This is your certificate file (.crt) for your IdP which can be downloaded from your SSL Issuer. We require base64 encoded files that include the begin and end tags. The result should look like this:

-----BEGIN CERTIFICATE-----
(Your Primary SSL certificate: your_domain_name.crt)
-----END CERTIFICATE-----

Use this SSL Checker to validate your file. 

Note:  If the file you have also has the ‘intermediate’ or ‘root’ certificate chains in them, that’s fine, as long as it has the main certificate for the domain included.

 User Principal Name (UPN)

The Name of the system user in email address format.

Basic Standard Market Research HR Professional Full Access Reporting
Free Individual Team & Enterprise
Feature Included In