Configuring Organization SSO Settings

About Configuring Organization SSO Settings

As a Brand Administrator, you have the ability to create and manage your SAML Single Sign-On (SSO) connections. You’ll be able to add new connections, update certificates on existing connections, modify settings such as Just In Time provisioning, and more. To get started:

1. Go to the Admin page.
2. Go to Organization Settings​.
3. Select SSO.

Adding a Connection

This section will go over how to connect your Qualtrics license to SAML SSO. To get started, go to the SSO tab of your Organization Settings, and select Add a connection.

General Information

• Name: Name the connection. This is a required field.
  Qtip: This name appears on your Organization Setting’s SSO tab so you can distinguish different connections you’ve added. This will not appear on your login page.
• Technical Contact: Add the email address of a technical contact which will likely be someone from IT team. This is the person Qualtrics can contact if there are technical questions or updates related to this SSO connection. This field is optional but strongly recommended.

Protocol Information

Under Protocol Information, select SAML.

After selecting SAML, you’ll be required to enter your Identity Provider settings, and will be able to download our Service Provider metadata by clicking Download service provider metadata. This is only available after you’ve saved your connection settings for the first time.

When configuring the Service Provider (SP) metadata in your IdP portal, feel free to look at our guide to common Identity Providers.

Uploading Identity Provider Settings

If you have your IdP metadata information available in XML format, click Upload IdP metadata and paste it into the window that opens. This will fill the fields in the following steps (Entity ID, Single sign-on service bindings, Certificates) with the information you provide.

Entity ID

The Entity ID is the unique identifier for your Identity Provider, and can be found in your IdP metadata. This field will auto-fill from your metadata upload or you can add it manually.

Single Sign-On Service Bindings

Single sign-on service bindings are endpoints used to connect to the Identity Provider, and can be found in your IdP metadata.

To add a new binding manually,

1. Select a Binding type. Qualtrics currently supports HTTP POST and HTTP Redirect.
   Qtip: If HTTP POST is enabled, the SAML request will be signed.
2. Under Binding location, enter the URL.
3. Click Add binding.
4. Once you add a binding, it’ll be listed along the top. If you’ve added multiple bindings, you can only select one to enable.

You can delete bindings by using the trashcan icon to the right of a binding.

Certificates

The certificate is the key used to authenticate the SAML connection. Qualtrics requires a signing certificate for SP Initiated logins, which can be found in your IdP metadata. If you plan on using IdP Initiated logins only, a signing certificate is not required.

To add a new certificate,

1. Set the Certificate type to Signing.
2. Under Certificate, paste the key.
3. Click Add certificate.

You can add multiple signing certificates.

You can delete certificates by using the trashcan icon to the right of a certificate.

Additional Options

The following settings are all optional. Read carefully what each one does before enabling or disabling these.

• Sign Request: If you have a binding that is an AuthN Request and need us to sign it, enable this setting. To guarantee that the request came from Qualtrics and not someone who might’ve intercepted the message, we’ll sign the request sent to the identity provider.
• Force Authentication: When enabled, Qualtrics will have your IdP force users to authenticate even if there is an active session. Only works if your IdP supports this kind of setting.
• Enable assertion replay prevention: When enabled, Qualtrics won’t reuse an assertion we’ve already seen, which is one way to prevent SAML replay attacks. We recommend that you enable this option.

User Attribute Fields

In this section, you’ll enter in the names of the attributes you plan on sending in the SAML exchange. The only required field is email address, but we strongly recommend including a first name, last name, and username field in order to complete the user profile in Qualtrics. The User Type, Division, and Group fields are optional fields that can be used for role mapping.

All attribute names are case sensitive and must be spelled exactly as they appear in the Attribute Statement section of your SAML response. Qualtrics cannot authenticate off of the “NameID” field in your SAML response.

• Email field: The name of the field containing users’ emails. This field is required.
• Username field: The field that carries the usernames, if you want these to be distinct from email addresses. This field is optional and will default to the email field if nothing is provided.
  Qtip: Best practice is to use a unique, unchanging field for username. This can be an email address or a unique identifier such as an employee ID.
• First name field: Users’ first names. Defaults to the email if nothing is provided.
• Last name field: Users’ last names. Defaults to the email if nothing is provided.
• User type field: You may want users to be assigned to a certain user type as soon as they log into Qualtrics for the first time. See Assigning User Permissions for more information.
  Qtip: If nothing is defined, all users will default to your brand’s default user type.
• Division field: You may want users to be assigned to a certain division as soon as they log into Qualtrics for the first time. See Assigning User Permissions for more information.
• Group field: You may want users to be assigned to a certain group as soon as they log into Qualtrics for the first time. If this field is left blank, users will not be assigned to groups. See Assigning User Permissions for more information.

After entering in these attribute names, you can configure the rest of the mapping in the next section, Mapping Options.

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

Mapping Options

If you’ve chosen to set user types, groups, or divisions, then you will need to map the attribute values with the existing fields in Qualtrics. You’ll specify what values correspond to what user types, groups, or divisions in Qualtrics.

Under “Identity provider’s value,” enter the value as it appears in your SAML response. Under “Qualtrics value,” select the corresponding type, group, or division. Then click Add mapping. You will need to complete these steps for every value your identity provider has defined.

To restrict access to the platform to only the mapped user types, you can select ‘Validate User Type’. This means that each time a user tries to log into Qualtrics via SSO, the system evaluates the values passed over for the attribute to ensure that at least one value is accounted for in the User Type mapping conditions.

If you choose not to map user types, divisions, or groups, all users will be assigned the default self-enrollment user type selected in your Admin tab under User Types.

User Provisioning Options

• Just in time provisioning: If a user doesn’t exist in Qualtrics and successfully logs in via SSO with an approved email domain, create a new user.
• Notify admins of user creation: Notify specific administrators when a user is created in their Qualtrics brand. You can specify who gets this notification under Self Enrollment Email Notification.
• Valid email domains: Enter the email domains that can be used to enroll in a Qualtrics account under your license. This will default to an asterisk ( * ), denoting that any domains can be used to enroll. Separate multiple domains with commas.
  Qtip: This list only impacts SSO enrollment. It does not affect other valid email domains saved in the brand’s settings.

User Migration Options

Once you’ve tested and enabled your new SSO connection, you may need to update the usernames of any existing users on your license. When users login through SSO, Qualtrics will check to see if they have an existing account using the attribute you’ve specified as the Username field. In order to ensure that the SSO login matches to the appropriate existing user account, the user’s username as listed in the Admin tab needs to be in the following format.

Value_of_Username_field_attribute#organizationID

You can update the usernames to this format using any of the five following methods:

Method 1: Adding #OrganizationID To Existing Usernames

If you only need to add the #organizationID to the end of the existing users’ usernames, you can enable the Change existing username on login option. When the user logs in via SSO for the first time, the #organizationID will be automatically appended to the end of their username.

Method 2: Just-In-Time Provisioning

If you have Just-In-Time provisioning enabled under User Provisioning Options, you can select Merge with existing user on login option. If the following are true, the user will be prompted with the following screen:

• There is not already an account within the brand that has a username matching the SSO username value for the user.
• The user logs in for the first time after SSO has been enabled for the brand.

1. The user should select Yes, I have a preexisting account here if they already have a Qualtrics account within the brand. The user should then enter in their Qualtrics account credentials and click Verify account. This will update their existing Qualtrics account username to match the user’s SSO username value passed on login. The user will not see this screen moving forward:
   
2. The user should select No, I don’t have a preexisting account here if they don’t already have a Qualtrics account within the brand. The user should then click Sign In when prompted. This will create a Qualtrics account with the user’s SSO username value passed on login. The user will not see this screen moving forward.

Method 3: Small Number of Users

If you have a small amount of existing users, you can update the usernames manually in your Admin page.

Method 4: Large Number of Users

If you have a large amount of existing users and you have API enabled for your license, you can use our public API to update usernames.

Method 5: Employee Experience License

If you are using the Employee Experience platform, you can update usernames via the file upload feature.

Dashboard Attributes

If your license includes CX Dashboards or any of our Employee Experience products, you may pass additional attributes than those defined in the “User Attributes” section. For CX Dashboards, these additional attributes can be used to automatically assign roles to users upon SSO authentication. For our Employee Experience products, you’ll only be able to capture one additional attribute called Unique ID. This field is required for all participants and can be assigned through SSO authentication or through the file upload feature.

In order to add additional attributes, enable Capture additional attributes for dashboards.

Once this option is enabled, you’ll enter in the attribute names you’d like to capture exactly as they appear in the “Attribute Statement” section of your SAML response.

Applying and Reverting Changes

To save your changes, click Apply.

If you want to revert the changes made on the screen to the last saved version instead of applying them, click Revert.

Enabling and Disabling SSO Connections

When you first add a connection, it will default to a status of disabled. Enabling a SSO connection indicates that the SSO login is now live on your license for your entire user base.

You will also see a connection labeled Qualtrics Login for [Your Organization ID]. Disabling this connection will require all users to login through SSO and remove the option for users to login with their Qualtrics username and password. You can enable this connection and an additional SSO connection at the same time.

Your organizational URL (https://OrganizationID.qualtrics.com) will now redirect to the SP initiated SSO login. The user experience will be one of the two following scenarios:

User experience if you only allow SSO logins

If you only allow SSO logins, the user will go to their organizational URL and automatically be redirected through your SSO authentication flow.

User experience if you allow both SSO and Qualtrics credentials

If you are allowing users to login either with SSO or login with their Qualtrics credentials, you will have the option to redirect the user to a landing page with the two available options. The user will select Login with Qualtrics to be redirected to the Qualtrics login page. The user will select Login with SSO to be redirected to your SSO login page.

In order to activate this landing page:

1. Find the connection named Qualtrics Login for [Your Organization ID].
2. Select Edit.
3. Select the option labeled Enable connection on organization URL.
   

If you do not select this option, your organizational URL will redirect to your SSO authentication flow. Users who choose to login without SSO will use one of the following links:

• For FedRAMP users: https://gov1.qualtrics.com
• For all other users: https://qualtrics.com/login

Managing Existing Connections

In the SSO section of the Organization Settings tab, you will see a summary of all the connections set up in your license. You will be able to add new connections, delete or disable connections, edit existing connections, and test connections during setup.

Enable or Disable a Connection

Under Status, you can toggle the connection between disabled and enabled. Please see Enabling and Disabling SSO Connections for relevant details and warnings.

Delete a Connection

Clicking Delete will ​permanently​ delete the connection.

When the button is clicked, a modal will open up with a warning message. You will need to click Delete on this modal to confirm the action.

Edit a Connection

Selecting the Edit button you will be able to modify any of the settings in the connection.

Download service provider metadata

After you’ve saved an SSO connection for the first time, you will see a new option when you go to edit your SSO connection, under the service provider settings.

Clicking Download service provider metadata will open a new tab with all the service provider (SP) metadata.

Rotating Certificates

Certificates expire every so often, so you’ll want to contact your IT team to make sure that the certificates used for Qualtrics logins are updated. You can work with your IT team to add a new certificate before the old certificate expires, and test the connection to ensure that the update goes through successfully.

1. Navigate to Organization Settings in Admin.
   
2. Go to SSO.
3. Click Edit next to the SSO connection you are rotating the certificate for.
4. Scroll down to the Certificates section.
   
5. Select Signing as the certificate type.
6. Paste your new certificate into the Certificate box.
7. Click Add certificate.
8. Click Apply to save your changes.
   
9. Test the connection to make sure the certificate was rotated correctly.
   
10. Click Edit.
11. Scroll down to the Certificates section.
    
12. Click the trash can icon next to your old certificate to delete it.
    Qtip: If your test failed earlier, then delete your newly added certificate instead and double check it is correct before repeating the steps above to re-add it.
13. When finished, click Apply.
    

Test a Connection

After you set up an SSO connection, you can test it out to make sure it’s working the way you intended. Click Test on a connection to start.

A new tab will open in your browser and you will be redirected to your IdP to authenticate. After a successful login, you will be redirected to a page displaying the attributes and values we successfully captured from your IdP in the SAML exchange.

If the login failed, you will receive an error message.  Take a look at the Troubleshooting section for some basic steps to take.

Troubleshooting

If you see an error message while testing a connection, please click on the code or check out the list below to find out more about that error and possible causes.

If the issue is unable to be resolved, please log into your Support Portal for assistance. Our SSO team will require the error code and the SAML response from your login.

Error Codes

• SSO_UNKNOWN_ERROR: An unknown error occurred. Please try logging in again, or contact support and provide the generated error code.
• SSO_SPS_CONNECTION_ERROR: An error occurred. Please try clearing your cookies and cache and logging in again.
• SSO_MISSING_USERNAME: A value for the username or email attribute was not found in the SSO response from your server. Since this attribute is required, please make sure the Attribute Statement section of your SAML response contains an attribute matching the Username field in your SSO Connection settings.
• SSO_SAML_MISSING_SSO_BINDING: A single sign on binding URL was not found in your SAML settings. Since this value is required for SP-initiated logins, please check your SSO connection settings and try again.
• SSO_SAML_INVALID_DECRYPTION_CERT: There was an error while decrypting the SAML response. Please check whether the encryption certificate in your Identity Provider matches the encryption certificate in the Service Provider metadata file generated for your SSO connection.
• SSO_SAML_INVALID_AUDIENCE_RESTRICTION: There was an error in the audience restriction in the SAML response. Please verify whether the correct value is set in your identity provider. This is expected to match the Assertion Consumer Service Location provided in the Service Provider metadata file generated for your SSO connection.
• SSO_SAML_INVALID_RECIPIENT: There was an error in the Recipient URL in the SAML response. Please verify whether the correct value is set in your identity provider. This is expected to match the Assertion Consumer Service Location provided in the Service Provider metadata file generated for your SSO connection.
• SSO_SAML_VALIDATION_ERROR: There was an error while validating the SAML response. Please verify the settings in your identity provider and in your Qualtrics SSO connection configuration and try again.