Single Sign-On How-to

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				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				If not set the user will be shown as 'anonymous'.
locale	String			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).
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.
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 your own URL.
avatar_url	URL				Dimensions are 50px by 50px. If left blank an avatar will be pulled from Gravatar
updates	Boolean				Whether the user will receive updates on suggestions (on create only)
comment_updates	Boolean				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

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

1. 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.
2. Base64 encode the encrypted output to generate the token.
3. Escape the token to make it web-safe.

We've created code snippets for most major languages with your uservoice_subdomain and sso_key already set.

• ruby
• php
• perl
• java
• C#
• python

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:

1. You can append the token onto a link to your UserVoice forum (ex: http://feedback.uservoice.com?sso=TOKEN)
2. You can create a link to http://yourdomain.com/feedback and then have that URL generate a token and redirect to http://feedback.uservoice.com?sso=TOKEN
3. 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 SSO token to your uvOptions variable. Be sure to put uvOptions outside of the function() that creates the widget itself.

Feedback Tab with Single Sign-On Token

<script type="text/javascript"> var uvOptions = { sso: "XXXXXXXXXXXXXXXXXXXXXXX" }; (function() { var uv = document.createElement('script'); uv.type = 'text/javascript'; uv.async = true; uv.src = ('https:' == document.location.protocol ? 'https://' : 'http://') + 'widget.uservoice.com/xxxxxxx.js'; var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(uv, s); })(); </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 UserVoice site (acme.uservoice.com) is set up to only allow SSO users and your default forum (https://feedback.uservoice.com/forums/1-general-feedback) is publicly accessible.

1. Go to the "Site" tab of Settings and add your SSO Remote Sign-in URL, http://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 they're prompted to sign in.
4. User clicks the sign-in button and is forwarded to http://acme.com/login?return=%2Flogin_success&uv_login=1&uv_size=window
   • Note: (It's possible that users may be redirected to your site or your login page will appear in a popup window. The uv_size parameter will either be 'window' when it's a redirect and 'popup' when your login is inside a popup window.
5. User logs in to your Login page
6. Your system then forwards them back, based on the return value that was passed to the login page, and passes a valid SSO token: https://feedback.uservoice.com/login_success?sso=XXXXXXXXX
7. From that point, we'll redirect the user back to the forum or idea they were originally looking at, or trying to look at, when they got redirected.

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 http://acme.com/login?return=%2Flogin_success&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: http://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 you're users are often using public, shared computers) drop the following <script> tag onto the page after sign out:

Logout Script

<script type="text/javascript" src="http://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 http://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:

• 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
• For security reasons SSO user profiles aren't combined with "global" UserVoice user profiles like the profile you created when you signed up for your account (that has a password specific to UserVoice). This means that if .(JavaScript must be enabled to view this email address) signs up for a UserVoice account (acme.uservoice.com) he creates a password so he can login and administer it but if he uses SSO to create a user with the email .(JavaScript must be enabled to view this email address) who's an admin it will be a completely separate profile and the system will show that there are now 2 admins.

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. Please check there for any errors.

Need Help?

If you have any questions please contact .(JavaScript must be enabled to view this email address)