Single Sign-On with SAML

1. Configure UserVoice to work as a SAML Service Provider (SP)

The SAML integration is available on the Enhanced and Pro plans.

SAML requires all logins to be checked against a token signing certificate that an Identity Provider (IdP) uses to sign the SAML assertions sent to the Service Provider (SP). To setup UserVoice as a SAML Service Provider, you need to upload your Identity Provider’s SAML token signing certificate via UserVoice Admin Console.

  1. Go to Admin Console → Settings → Web portal → User authentication.
  2. Select the option Single Sign-On (SSO).
  3. SSO KEY is not used in SAML, so ignore it.
  4. Input the SSO Remote Sign-In URL of your Identity Provider (required).
  5. If you need to, also input your SSO Remote Sign-Out URL so that your IdP knows when users log out.
  6. Finally, upload your Identity Provider’s token signing certificate file in either PEM (ascii) or DER (binary) format. The SHA1 fingerprint of the certificate will be stored.
  7. Then, press Save authentication settings.

2. Configure your Identity Provider (IdP)

The Service Provider metadata for your subdomain can be gotten from:

https://your-subdomain-name.uservoice.com/saml/metadata.xml

The most important information there is the UserVoice Assertion Consumer Service (ACS) URL that responds to POST requests:

https://your-subdomain-name.uservoice.com/saml/consume

To identify UserVoice users, the UserVoice ACS SAML consumer endpoint requires three custom attributes to be included in the SAML assertion:

  • email - The email address of the user.
  • guid - Global user identifier. This identifies the user in case e.g. the email address changes.
  • display_name - The first and last name of a user.

To ensure that the custom attributes are coming through, you can have a look at the SSO logs in Admin Console → Settings → Web portal → SSO logs. Every login attempt should generate a new line in these logs. These logs also help you to investigate any problems that might occur during consuming the SAML assertion. Some of the most errors with explanations are listed below.

Error message Explanation Action
Fingerprint mismatch The certificate used to sign a SAML assertion didn’t match with the uploaded certificate Make sure you uploaded the correct certificate
Current time is on or after NotOnOrAfter condition The SAML assertion has a NotOnOrAfter timestamp that is earlier than the clock of the SP (UserVoice). Ensure the time and timezone settings are accurate in your Identity Provider. Also, make sure the SAML assertion is fresh and that the NotOnOrAfter timestamp is not set to be too early in the future.
Current time is earlier than NotBefore condition The SAML assertion has a NotBefore timestamp that is later than the clock of the SP (UserVoice). Ensure the time and timezone settings are accurate in your Identity Provider and also make sure the NotBefore timestamp is not set in the future.
SAML Remote endpoint not set The SSO Remote Sign-In URL is not configured Set the SAML sign-in URL of your Identity Provider as explained in step 1.
SAML certificate fingerprint not set The SAML token signing certificate fingerprint is not set Upload the token signing certificate of your Identity Provider as explained in step 1.

3. Restrict access from unwanted visitors (optional)

To have your login prompt presented when anonymous users try to access UserVoice, do the following:

  • Go to Admin Console → Settings → Web portal → User Authentication → Single Sign-On (SSO) (make sure SSO is selected)
  • Make sure to have your Sign-In and Sign-Out URLs set properly.

    • The Sign-In URL should present a login screen for a user who is not logged in. If Restricted Access is not on, it opens in a login popup.
      • Entering correct credentials should lead to POSTing a SAML assertion to UserVoice ACS, if that user is authorized to access UserVoice.
    • The Sign-Out URL should never redirect user to UserVoice as that poses a risk of a redirection loop. If you want to lock anonymous users from your feedback site, you can do so in Admin Console:
  • Go to Admin Console → Settings → Web portal → Restrict access to your site

  • Check “Restrict access” and click Save site-wide access settings.

In this setup you will have a fullscreen login page. After login, you can control where your users land right after their login by passing the RelayState GET parameter as part of the ACS URL.

Example: If you POST the SAML assertion to

https://your-subdomain-name.uservoice.com/saml/consume?RelayState=/knowledgebase,

the user will be landed to:

https://your-subdomain-name.uservoice.com/knowledgebase. Be sure to check that this URL exists.