SSO Authenticator

About SSO Authenticators

The authenticator feature in Qualtrics is typically used to verify that respondents are found on a contact list that you have uploaded into Qualtrics. With the Single Sign-On (SSO) authenticator, you can go beyond this and authenticate against a third-party system (e.g., verify that they have a legitimate user ID at your university or have a Facebook account).

The authenticator feature supports 6 basic types of SSO authentication:

• Token: The third-party generates a secure token that allows the respondent (if validated) to automatically login.
• CAS (Central Authentication Service): Respondents authenticate against a CAS server.
• LDAP (Lightweight Directory Access Protocol): LDAP is used to authenticate users.
• Shibboleth: Respondents authenticate via SAML.
• Google OAuth 2.0: Respondents authenticate with their Google username.
• Facebook: Respondents authenticate with their Facebook username.

Below is a brief description of how to set up each method given a basic knowledge of how to use contact list authenticators. For further details about SSO, view our Single Sign-On Technical Documentation.

Token

Token authenticators allow you to authenticate using the secure token generated via a third party. Token authenticators can also be used to pass encrypted embedded data into the survey where it then be decrypted and stored as embedded data.

To set up a Token Authenticator

1. While editing your survey, open the Survey flow.
   
2. Click Add a New Element Here or Add Below.
3. Select Authenticator.
   
4. Change Authentication Type to SSO.
   
5. Change SSO Type to Token.
6. Specify the Encryption Method, Mac Method, and Leeway (we suggest 300 as the leeway.) You can also generate a secure key, or enter in your own key.
7. Click Apply.

To capture identifying information (Optional)

1. Enable Capture respondent identifying info. 
2. Click Add Embedded Data.
3. Enter your embedded data field name into the “Embedded Data to Set” text entry box on the left of the equals sign.
   
4. Insert the parameter name from the encrypted token into the “Field From SSO” text entry box.
5. If needed click the plus sign (+) to add a field and the minus sign (-) to remove a field.
6. Click Apply.

You will now see the embedded data values in the response results after someone takes the survey.

ASSOCIATE RESPONDENT WITH CONTACT LIST (OPTIONAL)

By default, Token SSO authenticators allow participants to take the survey multiple times. You can prevent this behavior and allow participants to only take the survey once by enabling Associate Respondent With Panel. This option forces participants to be a member of the selected contact list in order to take the survey.

The table below indicates which identifying field from the contact list (specified with the Identified by Fields dropdown) pairs with which Token authenticator attribute.

For example, if the Identifying Field was Last Name and the respondent was passing “Doe” for the lastname attribute, the contact list would need to have “Doe” in the Last Name field.

CAS

CAS authenticators allow you to authenticate users against a CAS server. They can also be used to capture and store a participant’s CAS username as embedded data.

To set up a CAS Authenticator

1. While editing your survey, open the Survey flow.
   
2. Click Add a New Element Here or Add Below.
3. Select Authenticator
   
4. Change Authentication Type to SSO.
   
5. Change SSO Type to CAS.
6. Specify the Hostname, Port, and URI.
7. Click Apply.

To capture identifying information (Optional)

1. Enable Capture respondent identifying info.
   
2. Click Add Embedded Data.
3. Enter your embedded data field name into the “Embedded Data to Set” text entry box on the left of the equals sign.
   
4. Insert the username parameter into the “Field From SSO” text entry box.
5. If needed, click the plus sign (+) to add fields and the minus sign (-) to remove fields. Note that Qualtrics only accepts the username attribute from CAS, so any field specified to capture attributes will return the username.
6. Click Apply.

You will now see the embedded data value in the response results after someone takes the survey.

ASSOCIATE RESPONDENT WITH CONTACT LIST (OPTIONAL)

By default, CAS SSO authenticators allow participants to take the survey multiple times. You can prevent this behavior and allow participants to only take the survey once by enabling Associate Respondent With Panel. This option forces participants to be a member of the selected contact list in order to take the survey.

Since only the username can be consumed via CAS authenticators, the contact list field that is selected as the identifying field (using the Identified by Field dropdown) must house the CAS username to properly authenticate users.

For example, if the identifying field was First Name and the respondent was passing “johnd” for the their CAS username, the contact list would need to have “johnd” in the First Name field.

LDAP

LDAP authenticators allow you to authenticate users directly against your LDAP servers. They can also be used to capture and store LDAP attributes as embedded data.

To set up an LDAP Authenticator

1. While editing your survey, open the Survey flow.
   
2. Click Add a New Element Here or Add Below.
3. Select Authenticator.
   
4. Change Authentication Type to SSO.
   
5. Change SSO Type to LDAP.
6. Specify the Hostname, Port, Base DN, Bind DN, Bind Password, and Filter.
   Qtip: The Filter field should be left in the format ([filter]=%1), e.g., (sAMAccountName=%1) or (uid=%1).
7. Click Apply.

To capture identifying information (Optional)

1. Enable Capture respondent identifying info.
   
2. Click Add Embedded Data.
3. Use the plus sign (+) to add 4 fields.
   
4. Enter your embedded data field names into the “Embedded Data to Set” text entry boxes on the left of the equals sign.
5. Insert the following parameters into the “Field From SSO” text entry boxes: FirstName, LastName, Email, and ExternalDataReference.
6. Insert the attribute names into the respective fields.
   
7. Click Apply.

You will now see the embedded data value in the response results after someone takes the survey.

ASSOCIATE RESPONDENT WITH CONTACT LIST

By default, LDAP SSO authenticators allow participants to take the survey multiple times. You can prevent this behavior and allow participants to only take the survey once by enabling Associate Respondent With Panel. This option forces participants to be a member of the selected contact list in order to take the survey.

The table below indicates which identifying field (determined in the Identified by Field dropdown) from the contact list pairs with which LDAP authenticator attribute, as specified in the First Name Field, Last Name Field, Email Field, and External Data Reference in the authenticator settings.

For example, let’s say that the identifying field was Email and the following attributes were specified in the LDAP authenticator settings:

If the respondent was passing “johnd@email.com” for the mail attribute, the contact list would need to have “johnd@email.com” in the Email field.

Shibboleth

Shibboleth allows users to authenticate via SAML. SAML is a 2 way connection, which is why this option is only available to those who already have Shibboleth set up on their brand. To find out if your brand has a Shibboleth SSO setup, contact your Brand Administrator.

To set up a Shibboleth Authenticator

1. While editing your survey, open the Survey flow.
   
2. Click Add a New Element Here or Add Below.
3. Select Authenticator.
   
4. Change Authentication Type to SSO.
   
5. Change SSO Type to Shibboleth.
6. Select the connection you’d like to use. We recommend the option that appears as default.
   Qtip: Brand Administrators can control which SSO connections are available across the organization. See Managing SSO Connections for Survey Authentication for relevant details and warnings.
7. Click Apply.

To capture identifying information (Optional)

1. Enable Capture respondent identifying info.
   
2. Click Add Embedded Data.
3. Use the plus sign (+) to add fields and the minus sign (-) to remove fields.
4. Enter your embedded data field name into the “Embedded Data to Set” text entry box on the left of the equals sign.
   
5. Insert the formal or friendly names of the attributes that are being passed via SAML into the “Field From SSO” text entry box (you can click the plus sign to add additional fields).
6. Click Apply.

You will now see the embedded data value in the response results after someone takes the survey.

ASSOCIATE RESPONDENT WITH CONTACT LIST

By default, Shibboleth SSO authenticators allow participants to take the survey multiple times. You can prevent this behavior and allow participants to only take the survey once by enabling Associate Respondent With Panel. This option forces participants to be a member of the selected contact list in order to take the survey.

The table below indicates which identifying field from the contact list pairs with which SAML attribute (specified by Identified by Field dropdown), as specified in the User Name Field, First Name Field, Last Name Field, and Email Field in the Qualtrics instance’s SSO settings.

For example, if the identifying was External Data Reference and the respondent was passing “johnd” for the uid attribute, the contact list would need to have “johnd” in the External Data Reference field.

Google OAuth 2.0

Google OAuth 2.0 authenticators allow respondents to authenticate with their Google credentials. They can also be used to capture and store Google account information as embedded data.

To set up a Google OAuth 2.0 Authenticator

1. While editing your survey, open the Survey flow.
   
2. Click Add a New Element Here or Add Below.
3. Select Authenticator.
   
4. Change Authentication Type to SSO.
   
5. Change SSO Type to Google OAuth 2.0.
   Qtip: By default, Google OAuth 2.0 authenticators will authenticate anyone with a Google account. To restrict who can access your survey, add in approved account email domains to the Restrict Authentication to Domain(s) field. No wildcard is necessary here; you’ll just need to type in your domain without the @ symbol (e.g., “gmail.com” or “qualtrics.com”). To allow multiple domains, enter your domains as a comma-separated list (e.g., “gmail.com, qualtrics.com”). A Brand Administrator can also restrict who can access the authenticator by configuring SSO settings for the organization.
6. Click Apply.

To capture identifying information (Optional)

1. Enable Capture respondent identifying info and click Add Embedded Data.
   
2. Use the plus sign (+) to add fields and the minus sign (-) to remove fields. 
3. Enter your embedded data field name into the “Embedded Data to Set” text entry box on the left of the equals sign.
4. Insert the parameter field from Google OAuth 2.0 into the “Field From SSO” text entry box. You can select fields from the following list:

   attribute

   value

   FirstName

   John

   LastName

   Doe

   Email

   johndoe@email.com

5. Click Apply.

You will now see the embedded data value in the response results after someone takes the survey.

ASSOCIATE RESPONDENT WITH CONTACT LIST

By default, Google OAuth 2.0 authenticators allow participants to take the survey multiple times. You can prevent this behavior and allow participants to only take the survey once by enabling Associate Respondent With Panel. This option forces participants to be a member of the selected contact list in order to take the survey.

The table below indicates which identifying field (specified under Identified by Field dropdown) from the contact list pairs with which Google OAuth 2.0 attribute.

For example, if the identifying field was First Name and the respondent was passing “John” for the Firstname attribute, the contact list would need to have “John” in the First Name field.

Facebook

Facebook authenticators allow respondents to authenticate with their Facebook credentials. They can also be used to capture and store Facebook account information as embedded data.

To set up a Facebook Authenticator

1. While editing your survey, open the Survey flow.
   
2. Click Add a New Element Here or Add Below.
3. Select Authenticator.
   
4. Change Authentication Type to SSO.
   
5. Set the SSO Type to Facebook.
6. Click Apply.

To capture identifying information (Optional)

1. Enable Capture respondent identifying info.
2. Click Add Embedded Data.
3. Use the plus sign (+) to add fields and the minus sign (-) to remove fields.
4. Enter your embedded data field name into the “Embedded Data to Set…” text entry box on the left of the equals sign.
   
5. Insert the parameter field from Facebook into the “Field From SSO” text entry box. You can select fields from the following list:

   attribute

   value

   name

   John Doe

   first_name

   John

   last_name

   Doe

   link

   http://www.facebook.com/johndoe

   gender

   male

   email

   johndoe@email.com

    

6. Click Apply.

You will now see the embedded data value in the response results after someone takes the survey.

ASSOCIATE RESPONDENT WITH CONTACT LIST

By default, Facebook authenticators allow participants to take the survey multiple times. You can prevent this behavior and allow participants to only take the survey once by enabling Associate Respondent With Panel. This option forces participants to be a member of the selected contact list in order to take the survey.

The table below indicates which identifying field (specified by the Identified by Field dropdown) from the contact list pairs with which Facebook parameter.

For example, if the identifying field was Email and the respondent was passing “johnd@email.com” for the email attribute, the contact list would need to have “johnd@email.com” in the Email field.

Maximum Authentication Attempts

Under Options, you’ll see a setting called Maximum Authentication Attempts. When using an SSO authenticator, the respondent is brought to an SSO landing page to log in, instead of the Qualtrics survey. The Qualtrics survey is unaware of any login failures in that SSO page. That means we generally don’t recommend setting maximum authentication attempts for an SSO authenticator, because it will have no effect.

The only time maximum authentication attempts would benefit a survey with an SSO authenticator is if “Associate Respondent With Panel” is enabled. Then the failure would occur because the user didn’t match the contacts in the connected list.

Errors When Logging into an Authenticator

When a survey taker is trying to log into the SSO authenticator, they may see the following errors. We’ll explain what they mean and how to resolve them.

• AUTHENTICATOR_SSO_CONFIG_DISABLED: A Brand Administrator needs to enable Use for survey authenticator for the SSO connection.
• AUTHENTICATOR_SSO_CONFIG_NOT_FOUND: The SSO connection was not found in the SSO Provider Service. This might be due to data syncing issues, or may occur because the connection was deleted. A Brand Administrator may also need to enable Use for survey authenticator for the SSO connection.

Types of Projects this Feature Is Available In

The survey flow can be customized in many different types of projects. However, not all survey flow features are available in all types of projects.

Authenticators can be used in the following projects:

• Survey projects
• XM Solutions
• Conjoints
• MaxDiff