Single Sign-On for SurveyTown White-Label Partners

Do you want all the functionality of SurveyTown inside your own application, but don’t want to write an survey component complete with question creation, multiple pages, logic and actions, webhooks and so many other features? We don’t blame you. We’ve spent a lot of time working those amazing features into our application - and now, we’re going to make it easy for you to bring all of those SurveyTown into your application with just a few lines of code!

The example we’ll be looking at today will be a fictional client called AmazingCo. AmazingCo teams up with SurveyTown as a reseller partner, and adds a new tab to their amazing application called “Surveys”. AmazingCo is a white label reseller with us, so their customers won’t see “SurveyTown” anywhere within the application. Inside this tab, AmazingCo will add an IFrame that points to a subdomain of their choice (ie surveys.amazingcompany.com)**. The DNS record of that subdomain will then be pointed to our servers: myfeedback.io.

Now the magic happens. We’re going to pretend that the AmazingCo app is written in PHP and they have downloaded the SurveyTown API wrapper. (The app could easily be written in any language - even languages we do not currently have a wrapper for - but the wrapper does make it easier.)

We have 2 pages to consider:

The login page (survey_login.php)

The app page (survey_app.php)

The “Surveys” tab will point to the login page, which will redirect to the app page, which will display the IFrame of surveys.amazingcompany.com**.

AmazingCo will now need to find their sub-accounts’ Client IDs and usernames. (To find an already created client’s Client ID and Username, you’ll need to login directly to the admin interface at https://admin.surveytown.com.) With this information on hand, AmazingCo can now use the simplified code below for the two pages. Note: the code below assumes that AmazingCo will populate the $clientId and $userName variables.

survey_login.php

<?php
// Fetch your $clientId and $userName information here
require( "class.SurveyTown.php" );

$c = new SurveyTown( "AMAZINGCOMPANY_API_KEY" );
$cookie = $c->Integration_Get_Cookie( $clientId, $userName, 1800 );

setcookie( "CAMPAIGNS_SSO_COOKIE", $cookie, time()+1800, "/", ".amazingcompany.com" );

header( "Location: survey_app.php" );

survey_app.php

<html>
<head><title>AmazingCo App</title></head>
<body>
<?php include "nav.php" ?>
<iframe src="https://surveys.amazingcompany.com/Dashboard.php" width="100%" height="800"/>
<script src="jquery.js"></script>
<script>
(function(){
setInterval( function() {
$.ajax( "survey_login.php" );
}, 60*20*1000 );
})();
</script>
</body>
</html>

That’s a lot of power added to AmazingCo’s app without a lot of code!

To make it all tie together seamlessly, we will use the API call: Integration_Get_Cookie. This call allows you to fetch an authentication cookie from our servers so that you can set it for users of your webapp. This authentication cookie must go in the cookie CAMPAIGNS_SSO_COOKIE set at the root of your webapp’s domain - the domain of the subdomain you’re pointing to SurveyTown (in this example it’s amazingcompany.com).

After the cookie is set, you will redirect the customer to the page with the IFrame pointing to the subdomain that loads pages from our server (the app page). Your customer will never see a login screen, unless the SSO cookie expires. This is why we added a setInterval function on the page to call the survey_login.php page every 20 minutes. (We gave our cookie a timeout of 30 minutes.)

Why not just set your cookie timeout to 10 years? Because this could leave you vulnerable to session hijacking. These cookies can be stolen by someone on the same network, so you don’t want to give them too long a timeout. We’ve found that 30 minutes is just about right.

That’s it! Let’s run through the steps one more time:

Set up a subdomain** that points to our webapp: myfeedback.io
Set up your customer accounts using the SurveyTown admin webapp, or the Admin functions in the SurveyTown API
Use the Integration_Get_Cookie API function to fetch an SSO cookie for a specific clientId and userName. Don’t make the timeout too long.
Set a cookie called CAMPAIGNS_SSO_COOKIE in the root of your webapp’s domain with the value you got from Integration_Get_Cookie.
Redirect your SSO user to your integration page - a page with an IFrame pointing to your new subdomain.
Enjoy! Your customers can now use our Surveys software within your own product!

Please contact SurveyTown sales or support to start putting together your integration today!

**When naming your new subdomain, please avoid using any of these words:

s.
survey.
sharing.
server1.
clicks.
click.
links.
link.
tracker.
^action.
dl.
emtracker.
clicksrs.
server1.
clicksgr.
clickslw.
ferclicks.
images.
image.
emimages.
imagesrs.
imagesgr.
imageslw.
ferimages.
img.
api.
admin.
olourl.