Single Sign-on (SSO) via SAML 2.0

In this article

Introduction

You can use Single Sign-on (SSO) to restrict access to your feedback board so that only authenticated members of your organisation can view and add suggestions.

Feature Upvote uses the widely-supported SAML 2.0 standard for SSO.

SAML 2.0 is supported by many services, including Microsoft’s  Azure Active Directory and Google’s Google Workspace (previously known as G Suite). You should be able to use any SAML 2.0 service. The main challenge is that each SAML 2.0 service seems to use different terminology for the same concepts.

Configuring SAML 2.0 for Feature Upvote requires technical knowledge. It should be performed by someone with experience in SAML 2.0 configuration or administration.

Configuring Single sign-on (SAML 2.0 SSO) Integration

You’ll need to switch backwards and forwards between configuring Feature Upvote and configuring your SAML 2.0 service. Start by configuring Feature Upvote.

The process is as follows:

  1. From your Feature Upvote dashboard, go to Feedback Boards > Settings > Access, select Single sign-on (SAML 2.0 SSO) and click Save changes
  2. Start to enable the SAML 2.0 SSO integration on Feature Upvote. You won’t yet be able to save the configuration form that you see, but you’ll be able to see the info needed by your SAML 2.0 service.
  3. Take note of the Reply URL and Entity ID supplied by Feature Upvote
  4. In your SAML 2.0 service create an app using the Reply URL and Entity ID supplied by Feature Upvote. Note that Reply URL might be called “ACS URL” or “Assertion Consumer URL”. Entity ID might be called “Relying Party Identifier”.
  5. Take note of the Identity Provider URL and X509 Certificate supplied by your SAML 2.0 service for the Feature Upvote app. Identity Provider URL might be called “SSO URL”.
  6. Return to Feature Upvote’s SAML 2.0 SSO integration configuration screen and add the Identity Provider URL and X509 Certificate info, then click the Save button. If your certificate begins with ----------BEGIN CERTIFICATE---------- and ends with ----------END CERTIFICATE---------- it is okay to include these text fragments.
  7. Important: Return to your SAML 2.0 service and grant access to users, roles, or groups from your organisation to the app you created in your SAML 2.0 service. This is an easily overlooked step but is essential. If you don’t do this, your users will most likely be presented with an error message from your SAML 2.0 service after they’ve been authenticated.

Once you save Feature Upvote’s SAML 2.0 integration, you’ll now see a link to test your SSO configuration. The link is shown immediately after successfully saving your SAML 2.0 settings, and can be found at any time by going to Feedback Boards > Settings > Access.

The test link is in the format of  https://yourfeedbackboard.featureupvote.com/saml/test. This test page is invaluable for checking your SAML 2.0 SSO configuration.

Optional configuration of display name and email attributes

Your SAML 2.0 service optionally sends user attributes to Feature Upvote on successful sign-in. You should be able to configure the names and values of these attributes using your SAML 2.0 service.

If these attributes include the user’s email address and/or display name, you can configure Feature Upvote to use these to auto-fill forms where appropriate.

Each text field can accept two attributes, separated by a space. So, for example, display name might be:

firstNameAttribute lastNameAttribute

  1. In Feature Upvote, go to Feedback Boards > Settings > Integrations > Single sign-on (SAML 2.0 SSO) > Configure
  2. Add the attribute names to the Display Name attribute and Email attribute fields
  3. Click the Save button

Determining the correct values to use for the  Display Name attribute and Email attribute fields can be tricky. The correct values are determined by the configuration of your SAML 2.0 SSO service provider and can’t be automatically determined by Feature Upvote.

Typical values for Azure Active Directory are:

For Google Workspace, follow the instructions here.

Helpful terminology

In SAML 2.0 terminology:

  • Feature Upvote is the service provider or sp
  • Your SAML 2.0 SSO service is the Identity provider or IdP
  • Your Feature Upvote feedback board has a unique SAML identifier known as entity ID, relying party identifier, or application id
  • Your identity provider has an “entity ID”, which is not used by Feature Upvote. Be careful not to confuse this with your Feature Upvote feedback board’s entity id.
  • Your identity provider has an identity provider URL, also known as the SSO URL. This is where Feature Upvote redirects unauthenticated users to that they can sign in.
  • Your Feature Upvote feedback board has a Reply URL, which is where your identity provider redirects users upon successful authentication. This is also known as Assertion Consumer Service URL or ACS URL.
  • Your identity provider has a public credential, usually in the form of an X509 certificate, sometimes known simply as a certificate. This is a long amount of text which, when correctly processed, is used to check the validity of user authentication responses sent by your identity provider.

Troubleshooting tips

Signature Algorithm

If your identity provider (IdP) allows you to set a  Signature Algorithm, please select RSA-SHA256

‘Invalid status code’ error message

Are you seeing this cryptic message?  Error handling SAML response: com.coveo.saml.SamlException: Invalid status code: urn:oasis:names:tc:SAML:2.0:status:Requester

This is how an SAML identity provider (IdP) informs you that your settings in Feature Upvote don’t match your settings in the IdP. Please carefully double-check all settings in your IdP, especially the  Reply URL.

Azure Active Directory tips

Use these settings for display name and email:

Google Workspace (aka G Suite) tips

How to get Display Name and Email address working

There are two steps to get this working.
Step 1: First you have to add some attributes in your Google Workspace admin
Step 2: You then need to add the same attributes to Feature Upvote's SSO settings.
Here's a screenshot of the attributes you should add to your own Google Workspace admin site. I've added a red box showing the three attributes you need to add: email, firstName, and lastName.
After having done this, you'll need to add these same attributes to Feature Upvote's SSO settings. Note that there is a space between firstName and lastName.

Once you've made these changes, I recommend clicking on the "Test SAML 2.0 SSO integration" button to check the settings worked. You might need to use the "Sign out" button on the SAML test page, and then sign in again, for the changes to take effect.

Need help with your SAML 2.0 SSO integration?

Let us know at [email protected]. We’ve been through this process with several SAML 2.0 SSO services and can help.

Related Articles