• Customer Experience
    Customer Experience
  • Employee Experience
    Employee Experience
  • Brand Experience
    Brand Experience
  • Product Experience
    Product Experience
  • Core XM
    Core XM

Configuring Organization SSO Settings

What's on This Page:

Was this helpful?


The feedback you submit here is used only to help improve this page.

That’s great! Thank you for your feedback!

Thank you for your feedback!

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:

In Admin page, in Organization Settings, SSO selected along left

  1. Go to the Admin page.
  2. Go to Organization Settings​.
  3. Select SSO.
Qtip: If you are setting up SAML SSO for the first time, you have the option of implementing through the self-serve portal on your own, or you can purchase the help of an experienced consultant. If you’re interested in working with an implementation consultant, contact your Account Executive or Customer Success Representative.
Qtip: In this case, Qualtrics acts as the SP, but you will need to configure your IdP with your IT team. IdP stands for “identity provider.” SP stands for “service provider.”

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.

Add a connection button

General Information

General Information settings, as outlined

  • 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

Qtip: The only protocol available through this self-serve portal is SAML. If you are interested in implementing other SSO protocols, please reach out to your Account Executive.

Under Protocol Information, select SAML.

Setting described

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.

The worst screenshot you've ever seen in your life

Qtip: If your Identity Provider requires you to fill in the Service Provider connection information first, you’ll be able to see our Entity ID and Assertion Consumer URL prior to being able to download the full metadata file.

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

Button described

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.

Qtip: Your IdP metadata will most likely be an .xml file that begins and ends with the <EntityDescriptor tags.
Qtip: For more information on IdP metadata, see this website. Please note that we do not own this PDF or the information within.

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.

Entity ID field

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.

Single sign-on service bindings options, as described below

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.

Warning: It is strongly recommended that you support SP initiated origins and upload a signing certificate. If you choose to support only IdP Initiated logins, you may experience issues logging into the Support Portal, Basecamp, and mobile applications via SSO. The built-in test feature will also not work.

Certificates section - signing appears as a block of text with random letters and characters

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.

Warning: 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 add a new certificate before the old certificate expires, and test the connection to ensure that the update goes through successfully.

Additional Options

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

Additional options, toggles for sign request, force authentication, and enable assertion replay prevention

  • 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.

Fields described below

  • 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.

Qtip: The attribute name can even appear as a URL. This occurs commonly with ADFS and Azure IdPs and can look like this:

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

Please make sure to check the SAML Response to confirm how the attribute is listed.

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.

Qtip: For a deeper dive, see Assigning User Permissions in our SSO documentation.

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.

User type mappings

Example: My IdP has an attribute, “Role,” which identifies whether a user is Staff or Student at my university. “Role” passes a value of “Student” when the Qualtrics User Type should be set to Participant. “Role” passes a value of “Staff” when the Qualtrics User Type should be set to Standard Account.

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.

Qtip: For a deeper dive, see Restricting User  Access in our SSO documentation.

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
Example: The organization ID for my Qualtrics license is “testbrand” and the Username field that I’ve specified is “Employee ID”. My “Employee ID” is “123456” so my username in Qualtrics must be “123456#testbrand”.
Qtip: The #OrganizationID does not need to be sent in the SAML assertion. This will only appear within the Qualtrics application.

User migration options include "merge with existing user on login" and "change existing usernames on login"

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.

Qtip: It is strongly recommended that you enable this option.

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.

A page that says "It looks like this is your first time logging in here. Do you have a preexisting Qualtrics account for the brand?" Then theres a button for yes or no

  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:
    Regular login screen, but at the top it says "Please enter the username and password for your preexisting Qualtrics account on this brand"
  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.
Warning: This method requires user input which may result in user error.

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.

Warning: If you do not update the existing users’ usernames, duplicate accounts may be created and/or users may lose access to the platform.

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.

The exact "capture additional" option just described. It's a toggle

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.

Dashboard attributes settings - you can type a name, then click the Add Attribute button to add it to the list. There's a special field for the Unique ID

Applying and Reverting Changes

Bottom-right of page, Revert button in white, then Apply button in blue

To save your changes, click Apply.

Qtip: This button may be grayed out if there are any errors with the fields you filled out. You will have to resolve these issues before you can apply changes.

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

Qtip: You will be able to add up to five connections at a time, but only one SSO connection can be enabled.

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.

Warning: Before you enable a connection, please ensure you have implemented the connection entirely and tested the login.

Both SSO connections listed are marked as "enabled"

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.

Qtip: If you are working with an external consultant who does not have SSO credentials at your organization, you will most likely need to enable this option.
Warning: Disabling a connection will disable the login for your entire user base. Once the SSO connection is disabled, users will need to login using a separate Qualtrics username and password. When disabling or enabling a connection, please keep in mind how it will impact your user base.

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.

Qtip: The user may see your SSO login page if they currently do not have an active SSO session. The user may be auto-logged into the platform if they currently do have an active SSO session.

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.

Select how you would like to login: Login with Qualtrics vs. Login with SSO

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.
    Editing page of the Qualtrics SSO connection. Option at the bottom with the name described

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:

Qtip: If you have a Vanity URL set up for your organization, the Vanity URL will replace your branded URL.

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.

For every connection listed, there's a status toggle to enable or disable, the name, a but to edit, a button to test, and a button to delete

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

Warning: When deleting a connection, please keep in mind how it will impact your user base. Once a connection is deleted, this cannot be undone.

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.

Qtip: You cannot delete a connection until its status has been switched to Disabled. Do not delete a connection until you’ve verified that your users will be unaffected by the change.

Delete button highlighted

Edit a Connection

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

Attention: When editing an enabled connection, be careful editing fields that may disrupt logins for your user base.

Edit button highlighted

Qtip: This option will be particularly useful for certificate rotations.

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.

Service provider, button that allows you to download those settings

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

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.

Test button

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.

Page shows "SSO test successful" and lists all the fields pulled

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

Qtip: You can test both enabled and disabled connections. We advise testing every connection before enabling it.

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.

Red text that says an error happened while testing the SSO connection

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.