Single Sign-On with JSON Web Tokens

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

Create a JWT to identify the user

UserVoice allows you to authenticate your users by passing a JSON Web Token (JWT). JWT is a standard for encoding an object that authenticates a user. There are JWT libraries that make this easy in many common languages. UserVoice requires HS256 for the signing algorithm.

You can find the SSO key for your account in the User Authentication area of the Web Portal settings. It is also shown in the Widget Settings under Advanced Setup.

Once you have generated a token for a user, you can include it as a query parameter when you redirect that user to your UserVoice portal.

JWT Example
1
2
3
require 'jwt'
token = JWT.encode({guid: user.id, email: user.email, display_name: user.name}, secret_key, 'HS256')
redirect_to "https://#{yoursite}.uservoice.com?sso=#{token}"

You can also use SSO with the UserVoice widget. This is required if you need to use the widget with private forums or have enabled site-wide privacy.

When configuring the widget, set your token as the sso option before launching the widget.

1
2
UserVoice.push(['set', {sso: "XXXXXXXX"}]);
UserVoice.push(['addTrigger', {}]);

Supported options

The only options required to identify your users are email and guid, but there are a number of other options you can include in an SSO token to control how your users experience UserVoice.

Field Value Required? Default Options Notes
guid String yes - A unique identifier for the user (ex: the user_id in your system).
expires Timestamp ‘yes’ when using Java SDK never Expiry time of the token in format YYYY-MM-DD HH:MM:SS and is in GMT. Defaults to never expiring.
email String yes - The email address used for notification emails.
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 Pass `trusted: true` if you have verified the user’s identity and it is ok if their email matches one of your UserVoice admins. If `trusted` is false or not passed, we won’t trust that the user’s identity is verified and we will not allow them to assume the account of an existing admin. (Note: `trusted: true` is not required if you are also passing `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. Passing admin:deny will remove Contributor sidebar access.
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)

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&uv_login=1&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&uv_login=1 to gain access to the forum.

Below you will find the descriptions of what each URL parameter represents:

  • return: The redirect URL.
  • uv_login: Informs the server that this is a login request for the UserVoice portal. It can be leveraged if the same sign-in URL is used for multiple services.
  • uv_size: Will either be window, when it’s a redirect (restricted site), or popup, when the login is inside a popup window.

Single log-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>

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

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.

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

Didn’t find what you’re looking for?

Check out the UserVoice knowledgebase for more documentation.

Explore the Knowledgebase