SAML SSO with Azure Active Directory

Microsoft teams, please defer to your process.

Prerequisites

  • An Azure AD Subscription
  • A UserVoice plan that includes SAML Single Sign-On
  • A UserVoice account and admin login

1. Adding UserVoice from the Gallery

To configure the integration of UserVoice into Azure AD, you need to add UserVoice from the gallery to your list of managed SaaS Apps.

To add UserVoice from the gallery, follow these steps:

  1. In the Azure Portal, on the left navigation panel, click Azure Active Directory icon.
  2. Navigate to Enterprise applications, then click All applications.
  3. Click the + New application button, at the top of the dialog.
  4. Click on All to expand the search. In the Add from the gallery box, search for UserVoice.
  5. In the results panel, select UserVoice, and then click Add.

There will be a short wait, and then you will see a confirmation message that the application has been added.

2. Configure Azure AD Single sign-on

In this section, you will enable Azure AD single sign-on in the Azure Portal 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 Azure AD single sign-on with UserVoice, perform these steps:

  1. In the Azure Portal, on the UserVoice application integration page, click Single sign-on.
  2. On the Single sign-on dialog, select SAML as the Single Sign-On method.
  3. On the Set up Single Sign-On with SAML page, section Box 1: Basic SAML Configuration, click to Edit and perform the following steps:
    1. In the Identifier (Entity ID) textbox, type the value using the following pattern: https://<subdomain>.uservoice.com. In the Metadata.xml, this is the same value as the entityID.
    2. In the Reply URL textbox, type the value using the following pattern: https://<subdomain>.uservoice.com/saml/consume.
    3. In the Sign-on URL textbox, type the value using the following pattern: https://<subdomain>.uservoice.com (if you copy and paste the URL, remove the / from the end).
    4. Click Save.
  4. Box 2: User Attributes & Claims. UserVoice requires a number of attributes, outlined in the below steps:
    1. Set the Name identifier value to user.mail (email). This is usually already set by default.
    2. UserVoice requires an email. You can optionally send a display name and GUID. Complete the following steps to create a preferred configuration:
      1. Delete user.givenname by clicking the three dots … and click Delete.
      2. Delete user.userprincipalname (name) by clicking the three dots … and click Delete.
      3. Delete user.surname by clicking the three dots … and click Delete.
      4. Confirm user.mail = emailaddress by clicking the attribute (not the three dots …).
      5. + Add new claim, user.displayname = display_name.
  5. Box 3: SAML Signing Certificate. Download the certificate by clicking Certificate (Base64). You will need the UserVoice.cer file later on.
  6. Check the Status is Active.
  7. Box 4: Set up UserVoice. Copy the Login URL, and the Logout URL. You will need these later on.
  8. In a new browser tab/window, log in to your UserVoice Admin Portal.
  9. Once logged in, click the Settings Cog in the bottom-left corner.
  10. Click on the Web Portal tab, navigate to User authentication and click Edit…
  11. On the Edit User Authentication dialog page, perform the following steps:
    1. Check the Single Sign-On (SSO) radio box.
    2. Paste the Login URL value into the SSO REMOTE SIGN-IN URL textbox.
    3. (Optional) Paste the Logout URL value into the SSO REMOTE SIGN-OUT URL textbox.
    4. In the SAML SINGLE SIGN ON section, upload the token signing certificate file. Click Choose File. Navigate to the UserVoice.cer file you downloaded earlier, and select it. Click Save.

Test

To test Azure AD UserVoice SSO implementation, you must first have users assigned to the application. See HOW-TO Assign Users to UserVoice Application if you have not. Once the above steps have been completed, to begin testing your SSO implementation, follow these steps:

  1. Open an Incognito Browser Window (or sign out of UserVoice and your Azure Directory 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 an Azure 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 Azure AD 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.

How to Assign Users to UserVoice Application

  1. In the Azure Portal, open the applications view, and then navigate to the directory view and go to Enterprise applications then click All applications.
  2. In the applications list, select UserVoice.
  3. In the menu on the left, click Users and groups.
  4. Click Add button. Then select Users and groups on Add Assignment dialog.
  5. On Users and groups dialog, select the user(s) you would like to assign to UserVoice, and Click the Select button.
  6. Click Assign button on Add Assignment dialog.

Troubleshooting

  • 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 AAD UserVoice application Single sign-on → Basic SAML Configuration 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…
    • You can find some common errors and their resolutions below.
  • 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 AAD 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 Azure 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 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.
Invalid Signature on SAML Response The signature/entity ID does not match the expected value. Identifier value is incorrect. Remove https:// and save. If you receive an error when saving, the connected UserVoice Azure App is out of date. Remove the app and do a fresh install. If you still see the an SSO error message, there might be multiple instances of UserVoice App in your Azure Portal. You can only connect one. The second would cause a missmatching signature. Remove it before you continue.

Acknowledgements

Microsoft Azure Tutorial - A good starting point with well worded instructions.

Didn’t find what you’re looking for?

Check out the UserVoice knowledgebase for more documentation.

Explore the Knowledgebase