Single Sign-On with JSON Web Tokens (JWT)

Note: If your infrastructure requires using SAML or OIDC for SSO see this document for links to other material.

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

require 'jwt';
let 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 (restricted site).

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

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.

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. First, you need to add your SSO Remote Sign-in URL into your instance's settings. Go to Admin Console → Settings → General → User authentication. Click the + sign next to Single Sign On (SSO). In the edit field, 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 then they’re prompted to sign in.
4. User clicks the sign-in button and is forwarded to a pop-out where they can authorize their login 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 4, 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 and had only one SSO tenant. The only difference would be that after step 2 the user would be immediately sent to the SSO Remote Sign-In URL https://acme.com/login?return=%2Flogin_success&uv_login=1.

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. If you have a private (restricted) site, there’s an easy way to log users out of your system when they log out of UserVoice.

In your User Authentication settings, 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. If you have more than one SSO tenant configured, you must send the logout URL in the token payload. See remote_logout_url in the Supported Options table above.

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

<script src="https://<subdomain>.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
  

  {
    "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

{
  "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.

Troubleshooting

See this article for troubleshooting issues with JWT SSO.