Single Sign-On with SAML

For SAML SSO with Azure Active Directory (AAD) see this page. Please see additional documentation for OKTA, OneLogin, and Token Based SSO.

Microsoft teams, please defer to your process.

Prerequisites

  • A SAML enabled IdP, such as ADFS or an In-House Solution
  • A plan that includes SAML Single Sign-On
  • A UserVoice account and admin login

1. Configure your Identity Provider(IdP)

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. You will need to get the UserVoice meta data and enter that as specified by IdP.
    1. The service provider metadata for your UserVoice subdomain can be found here https://<subdomain>.uservoice.com/saml/metadata.xml - The most important information there is the UserVoice Assertion Consumer Service (ACS) URL that responds to POST requests: https://<subdomain>.uservoice.com/saml/consume. This could be labeled as the Reply URL, or Third-Party Relay URL.
  2. Map your user data: UserVoice requires that Users have an email.
  3. (Optional) You can also send a display_name and a guid. The GUID can help to match the user to your system if the email should ever change.

2. Retrieve setup information from your IdP

To setup SAML SSO with UserVoice you will need the following information from your IdP:

  • SSO Remote Sign-In URL
  • SSO Remote Sign-Out URL (optional)
  • Token Signing Certificate

3. Configure UserVoice for SAML SSO

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 set up UserVoice as a SAML Service Provider, you need to upload your Identity Provider’s SAML token signing certificate via UserVoice Admin Console

Note: This must be done by one of your UserVoice admins. UserVoice support cannot do this for you.

  1. Go to Admin Console → Settings → Web portal → User authentication → Edit…
  2. Select the option Single Sign-On (SSO).
  3. Input the SSO Remote Sign-In URL of your Identity Provider (required).
  4. (Optional) Input your SSO Remote Sign-Out URL so that your IdP knows when users log out.
  5. Upload your Identity Provider’s Token Signing Certificate file.
  6. Click Save.

4. Test

To test your UserVoice SSO implementation, you must first have users assigned to the UserVoice application/service. Once the above is done, follow these steps for testing your SSO implementation:

  1. Open an Incognito Browser Window (or sign out of UserVoice and your IdP and open a new window).
  2. Go to your UserVoice Forum Portal (e.g. https://<subdomain>.uservoice.com).
  3. If you are not immediately presented with a login page, click Sign in (top-right corner). A popup window should appear. Enter the email address and password of a user that has been assigned to the UserVoice Application. Click Sign In.
  4. If successful, you should be granted access, and taken to the home page. You have successfully setup SAML Single Sign-On for UserVoice.

If you are unsuccessful, reread this guide, verify your configuration and test again. If you are still unsuccessful, see Troubleshooting.

Troubleshooting

  • Check your SSO logs in the UserVoice Admin Portal.
    • Navigate to https://<subdomain>.uservoice.com/admin/settings/portal/logs/failures. Here you will see logs with error information.
    • For more info, click Details…
    • You can find some common errors and their resolutions here.
  • Your Token Signing Certificate must be DER or PEM encoded. This encoding usually produces a certificate file with .DER, .CRT, or .CER extension attached. If you have a .KEY certificate, this will not work and you will need to convert it.
  • If errors persist you can contact the UserVoice Support Team with the following:
    • Your UserVoice account URL i.e. xxx.uservoice.com.
    • The error you are seeing
    • Things you have already tried to resolve the issue.
  • Note: you may need to connect the UserVoice support agent with your IdP Admin to help you resolve the issue, but the support agent will let you know if that’s required.

Common errors

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