Single Sign-On

Note: If your infrastructure requires using SAML for SSO see this document

1. Create a JSON object of a user’s information

The first step is to take your user information that you want sent over to UserVoice and put into a JSON object.

Field Value Required? Default Options Notes
guid String yes - A unique identifier for the user (ex: the user_id in your system).
expires Timestamp never Expiry time of the token in format YYYY-MM-DD HH:MM:SS and is in GMT. Defaults to never expiring.
email String - If not set the user will not get any activity or update emails. (strongly recommended).
display_name String anonymous If not set the user will be shown as ‘anonymous’.
locale String The account’s or forum’s default locale ar, bg, cn, cz, da, de, en, es, et, fi, fr, fr-CA, he, hr, it, ja, lv, nl, no_NB, pl, pt, pt_BR, ro, ru, sk, sl, sr, sr-Latn, sv-SE, tr, zh-TW Set this users locale (language).
trusted Boolean false true, false Defaults to false. True indicates that the email you’re using is trusted, which lets you SSO into admin users and revoke adminship of users. trusted=false can’t log you into an admin unless you pass admin:accept
owner String - accept, deny Make this user an owner of your UserVoice account giving them access to adding admins, changing plans and billing info.
admin String - accept, deny Grant the user account admin access. NOTE: admin:deny requires trusted:true
allow_forums Array - Exclusive list of Forum ids user has access to (doesn’t restrict admins).
deny_forums Array - List of Forum ids user does not have access to (doesn’t restrict admins).
url URL - Sets all user profile links to this URL. Only set if you don’t want people to see each other’s UserVoice profiles and use your own URL.
avatar_url URL [Gravatar URL] Dimensions are 50px by 50px. If left blank an avatar will be pulled from Gravatar
updates Boolean true Whether the user will receive updates on suggestions (on create only)
comment_updates Boolean false Whether the user will receive updates on suggestion comments (on create only)

You should end up with something that looks like this (for .NET see the example code):

Example JSON
1
  {"guid":1309454729,"display_name":"Example User","email":"example@test.com"}

2. Create a Single Sign-On Token

Next, we’ll turn that JSON object into a token that grants the user access to UserVoice.

  • Encrypt the JSON object with AES using your uservoice_subdomain (If you’re acme.uservoice.com then this value would be ‘acme’) as the password and your sso_key as the salt to generate an SSO token. You can get your sso_key from the ‘User Authentication’ portion of General Settings.
  • Base64 encode the encrypted output to generate the token.
  • Escape the token to make it web-safe.
  • If you are using multibyte strings in PHP, use mb_internal_encoding(‘ASCII’); & mb_internal_encoding(); around the SSO generation code

We’ve created code snippets for most major languages. Remember to set your uservoice_subdomain and sso_key (both case sensitive) in them.

Alternatively, all our SDKs include the SSO token generation code (in addition to our API clients). Find links to the SDKs here.

3. Passing the Single Sign-On Token to UserVoice

The next step is to forward the token on to UserVoice by including it as a URL parameter named sso. You have a couple options in how you do this:

  • You can append the token onto a link to your UserVoice forum (ex: https://feedback.uservoice.com?sso=TOKEN)
  • You can create a link to https://yourdomain.com/feedback and then have that URL generate a token and redirect to https://feedback.uservoice.com?sso=TOKEN

  • If you’re using our Feedback Tab widget you can include the SSO token in the widget configuration (this is required if you want to have your feedback tab work on a private forum with SSO).

The latter method is recommended and all you need to do is add the below line to your widget embed code:

1
UserVoice.push(["setSSO", 'XXXXXXXXXXXX']);

So the complete embed code might look something like this:

Feedback Tab with Single Sign-On Token
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
<!-- UserVoice JavaScript SDK (only needed once on a page) -->
<script>(function(){var uv=document.createElement('script');uv.type='text/javascript';uv.async=true;uv.src='//widget.uservoice.com/lEATYjKAsDH60WYSuR0Zw.js';var s=document.getElementsByTagName('script')[0];s.parentNode.insertBefore(uv,s); })()</script>

<!-- A tab to launch the Classic Widget -->
<script>
UserVoice = window.UserVoice || [];
UserVoice.push(['setSSO', 'XXXXXXXXXXXX']);
UserVoice.push(['showTab', 'classic_widget', {
  mode: 'full',
  primary_color: '#cc6d00',
  link_color: '#007dbf',
  default_mode: 'support',
  forum_id: 121373,
  tab_label: 'Feedback & Support',
  tab_color: '#cc6d00',
  tab_position: 'middle-right',
  tab_inverted: false
}]);
</script>

4. Login Redirection

What we’ve described so far allows you to allow take a user who’s logged into your system and send them to your UserVoice forum. But, what if they go directly to your UserVoice forum before logging into your system? You can handle this by setting a remote login URL where your users will be sent when they arrive at UserVoice not logged in.

Let’s say your customer portal (acme.uservoice.com) is set up to only allow SSO users and your default forum (https://acme.uservoice.com/forums/123-general-feedback) is publicly accessible.

  1. Go to the “Site” tab of Settings and add your SSO Remote Sign-in URL, https://acme.com/login (for example)
  2. A user goes to acme.uservoice.com
  3. They can browse the forum but when they go to vote (or, if the forum is private) then they’re prompted to sign in.
  4. User clicks the sign-in button and is forwarded to https//acme.com/login?return=%2Flogin_success&amp;uv_login=1&amp;uv_size=window
  5. We store the page that the user was on in a session cookie on our server.
  6. Either your users will be redirected to your site or your login page will appear in a popup window. This is not something that can be controlled. If your site content is private (e.g. the user is trying to get to a private Forum), then he/she will be redirected to a full login window. If the content is public (e.g. the user is logging in from the widget or a public Forum) then the login window will appear as a pop-up. The uv_size parameter will either be ‘window’ when it’s a redirect and ‘popup’ when your login is inside a popup window.
  7. User logs in to your Login page and signs in.
  8. Your system then forwards them back to the page they came from.
  9. You construct the return URL based on the ‘return’ value that we provided in step 3, and then add the SSO token (e.g. https://acme.uservoice.com/login_success?sso=XXXXXXXXX)
    • PHP example code that does this: header(‘Location: https://acme.uservoice.com/login_success?sso=XXXXXXXXX’)
    • Ruby on Rails example code that does this: redirect_to “https://acme.uservoice.com/login_success?sso=XXXXXXXXX”
    • If the user is directed back to UserVoice but still in a pop-up window, then likely you are not being consistent with your use of HTTP and HTTPS - if the URL of your customer portal is HTTP, then the redirect must be as well (and likewise with HTTPS).

This would work the exact same way if the forum was private. The only difference would be that after step 2 the user would be immediately sent do https://acme.com/login?return=%2Flogin_success&amp;uv_login=1 to gain access to the forum.

5. Logging Out (optional)

There are two scenarios you want to cover. When an SSO user logs out of your system and when an SSO user logs out from UserVoice.

Logging out of your site from UserVoice

By default, if a user logs out from UserVoice they are simply logged out from UserVoice. Because of the seamless nature of the SSO system from your site to UserVoice user’s may believe logging them out of UserVoice would log them out of your system. This is especially important if your users are often on public computers. Fortunately there’s an easy way to log users out of your system when they log out of UserVoice.

Go to the “Site” tab of Settings and enter your logout url (ex: https://acme.com/logout) in as the SSO Remote Sign-out URL. Once that’s set any time a user logs out they’ll be forwarded to the URL you’ve entered.

Logging out of UserVoice from your site

If you’d like to make sure your users are logged out of UserVoice when they sign out of your service (especially if your users are often using public, shared computers) drop the following <script> tag onto the page after sign out:

Logout Script
1
  <script src="https://feedback.uservoice.com/logout.js"></script>

6. Granting Permissions

Access to Forums

If you have a private forum there are two ways to give an SSO user access:

  • Add the allow_forums parameter to your JSON object with an array of UserVoice Forum IDs you want that user to be able to access. You can find the IDs in the URLs of your forum. For example for https://acme.uservoice.com/forums/3-general-feedback the Forum ID is ‘3’.
Example JSON
1
  {"guid":1309454729,"display_name":"Example User","email":"example@test.com","allow_forums":[1,2,3]}
  • Don’t add the allow_forums to your JSON and just make sure that all your private forums have the ‘Authorize all Single Sign-On (SSO) users’ box checked.

You can also use the deny_forums to do the inverse: grant everyone access with the ‘Authorize all Single Sign-On (SSO) users’ option but then just deny specific users from some forums.

Granting Admin Privileges

By adding the owner and admin parameters to your JSON object you can add (‘accept’) or remove (‘deny’) these privileges from an SSO user:

Example JSON
1
  {"guid":1309454729,"display_name":"Example User","email":"example@test.com","admin":"accept"}

A couple important things to note:

  • For each admin who would like to sign in via SSO, you must do one of the following: (1) add “admin”:”accept” to the JSON object; or (2) if this user is already an admin of your account with a standard username and password, add “trusted”:”true” to the JSON object, thus indicating that you trust the identity of the person using the email address.
  • In order to revoke admin rights, pass trusted:true AND admin:deny. You cannot revoke admin rights without a trusted token.
  • You can have as many owners/admins as your plan allows (most plans allow unlimited admins).
  • An owner is automatically an admin.
  • You can have multiple owners.
  • If you add owners/admins and are on a per admin plan then this will increase the monthly cost of your subscription and may incur some immediate pro-rated upgrade charges.

7. Error Logging

Every Single Sign-On Token that’s passed to UserVoice is logged along with whether the token was accepted or not. We’ve made this log available to you via our debug console (this can also be accessed by going to Settings -> Logs in your Admin Console). Please check there for any errors.

8. Common Issues

  • If the token is consistently expiring, the ‘expires’ parameter in the JSON object may not be in the correct syntax, or in the correct timezone (this should be in UTC/GMT). Also note that the expiration date/time must be in the future.
  • If the user is redirected to your website login in a pop-up window, and then is directed back to UserVoice after sign-on but still in a pop-up window, then the URLs in your code might be mismatched. Please make sure to use HTTP and HTTPS consistently, and, if you are using a domain alias, to make sure that the URLs are the same throughout (i.e. don’t use both a CNAME and standard UserVoice address)

Need Help?

If you have any questions please contact support@uservoice.com.

  • Please include your code and a log output (including all the warnings PHP interpreter prints).
  • Print the original user data in JSON, the encrypted data, the URL-escaped data, and finally how you are using it (the entire URL which you are using).