The Video Curation, Publishing, & Monetization Platform

Developer Center

SSO API Implementation Guide

Magnify's SSO API enables you to implement single-sign-on using your existing user database and web login forms, by defining a secure mechanism for sharing information between your web server and Magnify.

This API enables Magnify's servers to check with your server to confirm whether a visitor has already authenticated themselves. (It's important to note that the direction of the API calls used here are from Magnify's servers to yours, the reverse of the the Channel Access API, which allows your servers to make calls in to Magnify.)

Requirements

The following general requirements describe the circumstances intended for use of the SSO API.

You must have an existing main web site with login pages and a user account database.
You must have the access privileges and technical knowledge required to install scripts on your main site and integrate them with your existing web application.
You must have set up (or been given administrator privileges to) one or more Magnify.net channels.

Single Sign-On Concepts

Use of the SSO API involves passing some type of token between your main web site and your Magnify site, whether by cookie or by redirect. The token is treated as an opaque value, so you can use any format you'd like, including a random number, a session ID, a short text string, or any similar value, as long as you can later use that value to determine whether the user has identified themselves.

After the token has been exchanged, the Magnify server then makes a server-to-server request, passing the token back to your validation script, and receiving the corresponding user information. That user information is then added to the user database on your Magnify site, and associated with the current visitor's session.

Setup Process

Activation of the SSO mechanism consists of the following steps:

Determine which mechanism you will use to pass authentication tokens to the Magnify site.
Configure the required scripts on your site, following the specifications below.
Ensure that your login form supports a post-authentication redirect argument.
Use the admin interface to enter the required configuration parameters.
If your identity within the SSO system has a different email address than the one you use to administer your Magnify channel, create a new account with that address and issue administrative privileges it, so that you are not locked out of the administration console after SSO is activated.
Use the SSO Validation screen to confirm that the single sign-on functionality is working correctly, then click the activation link to begin using it.

Choosing an Authentication Mode

The Magnify SSO API supports two different ways of obtaining an authentication token for users:

You can share session or authentication cookies between the two sites. (This approach requires that the Magnify site uses the same domain name as your main site.)
You can have users from the Magnify site redirected to a special URL on your main site, which generates a unique token and includes it in the URL when redirecting the user back to the Magnify site.

Each of these approaches is described further below.

Using Shared Cookies

This diagram shows some of the typical interaction flows in the cookie mode:

These additional technical requirements must be addressed to implement the Cookie authentication mode.

Your application must use an HTTP cookie to identify or authenticate users.
Your main web site and your Magnify channel must both use web addresses within your own Internet domain name.
Your authentication cookie must be set to be domain-wide, so that it is sent to both your main web site and your Magnify channel.

This system should work with any type of cookie lifecycle, including the following:

permanent cookies (cookie value never changes),
session cookies (value persists throughout the lifetime of a user's visit), and
authentication cookies (value changes when a user signs in and when they sign out).

To configure your Magnify site to retrieve these cookies, you will need to enter the following parameters:

The name of the session or authorization cookie you will use.

Using Redirect Tokens

This diagram shows some of the typical interaction flows in the redirect token mode:

To configure the Redirect Token mode you will need to configure an additional script on your server that will generate authentication tokens and include them in a redirect URL.

To configure your Magnify site to call your token-generation script, you will need to enter the following parameters:

The URL for a token-generation script on your server that can be invoked by a user's web browser, and which will then redirect them to a designated URL.

If your token generation service will only be used by Magnify, you can enhance its security by refusing requests if the redirect target URL does not correspond to your channel's web address.

To avoid replay attacks that might allow a malicious visitor to gain access to other user accounts, we recommend enabling digital signature validation for these redirects.

It is required that your login and logout scripts redirect to /login/sso on your Magnify site.

Sending Timestamp and Digital Signature

Timestamps are simply the number of seconds since 1/1/1970. If you are using a Unix-based machine, this is what the time function returns natively.

Digital signatures are created with the md5 hashing function. Take the query string that has been created up to that point, append your secret key, determine the md5 hash signature of that entire string, then append that signature to the query string and return it.

Example:

Let us suppose that: the secret key is MYSECRETHASHKEY, the current timestamp is 1256910448, and you want to redirect the browser to http://www.yourmagnifysite.com/login/sso and tell us that your user_id is 100.

Configure the External Token Source section of the SSO Configuration page as follows:

Validation type: External Redirect
Already Logged In Test Page URL:

https://www.yoursecuresite.com/ssoscripts/checkIdentity?method=verify&key=yesitreallyisme&want_signature=true&redirect=$SITE?user_id=${response/user_id}

Signature and timestamp values:

signature MYSECRETHASHKEY ts

Additionally, the first part of the Parameter Name entry, below in the Token Validation section, would be user_id.

Based on the configuration above, you would get the request to verify the currently logged in user. For your response, you would start by creating your query string with the user id to be returned and the timestamp:

user_id=100&ts=1256910447

Create your signing string by adding your secret key onto the end:

user_id=100&ts=1256910447MYSECRETHASHKEY

Take the md5 hash of that signing string, ff00d451cf8616ae7d7e964ba9cc3816, and use it to sign the query string:

user_id=100&ts=1256910447&signature=ff00d451cf8616ae7d7e964ba9cc3816

With that query string, redirect the browser to the following based on the redirect in the test page URL:

http://www.yourmagnifysite.com/login/sso?user_id=100&ts=1256910447&signature=ff00d451cf8616ae7d7e964ba9cc3816

Validation Script

Regardless of whether you're using cookies or redirects, both approaches require a script or web-accessible function on your server to be able to validate the cookie or token value. It is important to note that even if you are using redirects, this call is made directly to your server from the Magnify servers and no redirect is used.

When your Magnify channel site receives a web request with a new value for the authentication cookie or token, it sends that value to your validation script.

If the authentication cookie or token is invalid, or it isn't associated with an active user, your script should return an empty response.

If the authentication cookie is valid and corresponds to an active user in your system your script should respond with information about that user.

To configure your Magnify site to call your validation script, you will need to enter the following parameters:

The URL for a cookie- or token-validation script on your server that can be called by our server.
The type of call (POST/GET)
The parameter names (default is "cookie")
The return value mapping of our variable names to your variable names

Your script is expected to return the variables that you have specified above.

Example:

If the fields in the Token Validation section of the SSO Configuration page are populated as follows: Validation API URL:

https://secure.yoursite.com/sso/validate

Validation Call Style

POST - Form Parameter - Raw Form

Parameter Name

user_id&method=getUserInfo&key=yesitreallyisme&login=mylogin&password=mypassword

Return Value Mapping:

external_nid,id,email,email,handle,name/first name/last,thumbnail_url,photo

The magnify server would send the request to your script with your ID that we need information about as the value for the first key in the Parameter Name field (user_id in this case) and the rest of the pairs exactly as entered. If, as above, you have requested a POST, the key/value pairs are sent as POST data, not as a query string.

The user data can be returned in one of two different formats:

An XML document containing named elements.
A query-string encoded sequence containing named key-value pairs.

In either format, the following fields can be provided:

external_nid (required)
handle (required)
email (required)
name
thumbnail_url

An example XML return value for the above Return Value Mapping is shown below. An xml header line of some sort must be included to tell our system that you are returning xml. Note the use of / and space to combine return xml fields.

<?xml version="1.0" encoding="UTF-8"?>
<userinfo>
	<id>123</id>
	<handle>JDoe</handle>
	<email>j.doe@gmail.com</email>
	<name>
		<first>John</first>
		<last>Doe</last>
	</name>
	<photo>http://myserver.com/photos/jdoe.jpeg</photo>
</userinfo>

An example query-string (not exactly for this example) encoded return value is shown below:

id=123&handle=JDoe&email=j.doe@gmail.com&name=John%20Doe&photo=http://myserver.com/photos/jdoe.jpeg

The Return Value Mapping for this query string would be:

external_nid,id,email,email,handle,name,thumbnail_url,photo

If your validation service will only be used by Magnify, you can enhance its security by refusing requests unless they originate from IP addresses associated with Magnify's servers, currently located at 208.70.246.82, 208.70.246.58, 208.70.246.67, 208.70.246.167 and 208.70.246.187. If you are using redirects, this restriction must only be for the vaidation service and not for the redirect calls, as they will come from the user's browser.

Magnify's servers may cache validation results for a moderate amount of time, such as fifteen minutes. However, if we receive a request that requires authentication, and the previous validation result was not authenticated, we will re-check the validation before sending the user to your login page.

When incorporating the results of the validation call into our user database, if there isn't a user entry with the given external nid, we check to see if there's a user with no ID and the provided email address, so user accounts created before the SSO feature was enabled will be automatically merged with the new SSO information.

Other Pages on Your Server

The following configuration parameters are required:

The URL for a login/registration script on your server that will be visited by users' web browser and will redirect back to a specified URL upon completion.

The following configuration parameters are optional:

Additional URLs for pages on your server that allow a registered user to update their account's email address, password, handle, full name, picture and similar information.

More information on these parameters is available on the configuration reference page.