SAML SSO with ADFS 4.0

Microsoft teams, please defer to your process.

Prerequisites

  • ADFS 4.0 Windows Server 2016
  • A UserVoice plan that includes SAML Single Sign-On
  • A UserVoice account and admin login

1. Configure UserVoice as a Relying Party in ADFS 4.0

In this section, you will enable ADFS single sign-on in the ADFS Management Console and configure single sign-on in your UserVoice application. The UserVoice Metadata.xml for your instance may come in handy. Find it at https://<subdomain>.uservoice.com/saml/metadata.xml.

To configure ADFS single sign-on with UserVoice, perform these steps:

  1. Open the AD FS 2.0 Management Console and select Add Relying Party Trust to start the Add Relying Party Trust Wizard and then click ‘Start’.
  2. Make sure the Claims aware radio button is selected and then click the ‘Start’ button to continue.
  3. Select the Import data about the relying party published online or on a local network radio button and enter your UserVoice metadata URL: https://<subdomain>.uservoice.com/saml/metadata.xml.
    1. If you receive an error, select Enter data about the relying party manually.
  4. Choose and enter a Display Name (e.g. UserVoice) for this Relying Party and any additional notes you may want. Click ‘Next’ to continue.
  5. Choose the Permit everyone access control policy and then click ‘Next’ to continue. You may optionally select another access control policy to permit only a smaller subset of users and/or require multi-factor authenticator (MFA) if needed, but these other access control policies will not be covered in this article.
  6. On the ‘Ready to Add Trust’ page, review all of the tabs and make sure the information looks correct. It’s a good idea to visit the Encryption and Signing tabs, view each certificate, and make sure it is trusted. You may need to add the cert(s) to your Trusted Root Certification Authorities before ADFS will allow this Relying Party to be used. Once you are sure that everything looks good, click ‘Next’ to continue.
  7. On the ‘Finish’ page, make sure the Configure claims issuance policy for this application radio button is checked on and then click ‘Close’.

2. Configuring Claim Rules

In this section, you will tell ADFS which User attributes to send to UserVoice, in the SAML request.

  1. Click the Add Rule button.
  2. Select Send LDAP Attributes as Claims and click ‘Next’.
  3. Enter a name of your choice for the rule.
  4. UserVoice expects the following attributes. Map them as they appear in Active Directory to the value UserVoice is expecting:
    1. emailaddress (required)
    2. guid
    3. display_name
  5. Click ‘finish’ to save the rule, and ‘OK’ to save the settings.

3. Export the ADFS token signing certificate

  1. In the ADFS Management Console, click the Certificates folder and double-click on the Token Signing certificate.
  2. Click the Details tab and the Copy To File button.
  3. Export the certificate as Base-64 encoded X.509 (.CER).
  4. Name the certificate, e.g. ‘UserVoice.cer’.

4. Configure UserVoice

  1. In a new browser tab/window, log in to your UserVoice Admin Portal.
  2. Once logged in, click the Settings Cog in the bottom-left corner.
  3. Click on the Web Portal tab, navigate to User authentication and click ‘Edit…’
  4. On the Edit User Authentication dialog page, perform the following steps:
    1. Check the Single Sign-On (SSO) radio box.
    2. Paste the ADFS Single Sign-On Service URL value into the SSO REMOTE SIGN-IN URL text box.
    3. (Optional) Paste the ADFS Sign Out URL value into the SSO REMOTE SIGN-OUT URL text box.
    4. In the SAML SINGLE SIGN ON section, upload the ADFS token signing certificate:
      1. Click ‘Choose File’.
      2. Navigate to the ‘UserVoice.cer’ certificate you downloaded earlier, and select it.
      3. Click ‘Save’.

Testing

To begin testing your SSO implementation, follow these steps:

  1. Open an Incognito Browser Window (or sign out of UserVoice and your ADFS Directory and open a new window).
  2. Go to your UserVoice Forum Portal (e.g. https://.uservoice.com).
  3. If you are not immediately presented with an ADFS login page, click Sign in (top-right corner). A popup window should appear. Enter the email address and password of a user that has permission to access 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 ADFS 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 below.

Troubleshooting

  • We do not accept encrypted assertions.
  • If you get the following error when signing in: “Invalid resource. The client has requested access to a resource which is not listed in the requested permissions in the client’s application registration.” Remove trailing slashes (/) from URLs in your ADFS Relying Trust settings.
  • 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…’
  • 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 the ADFS team 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. If the error persists, create a new signing certificate in ADFS and try again.
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 4.

Didn’t find what you’re looking for?

Check out the UserVoice knowledgebase for more documentation.

Explore the Knowledgebase