Follow

Remote Login API

Zen Planner's Remote Login API lets you connect your Zen Planner database to other websites on the Internet.  You can set this up for your staff or members to log in to other websites that you control using their Zen Planner usernames.  

When members log in to your member website, they will see the remote login links on their personal profile.  

When staff members log in to your Zen Planner database, they will see the remote login links in a menu on the dashboard.

To get started log in to your Zen Planner database, and go to Setup > Remote Login.

The Basics

Remote Logins are based on a "shared secret" between Zen Planner and your external web application.  This secret is used to generate a secure hash (one way encryption) which helps you confirm that people using remote login are who they claim to be, and are already logged in to Zen Planner.

You will need a page on your web application (called the target address) dedicated to accepting the remote login from Zen Planner.  When a person clicks on a remote login link in your Zen Planner database, they will be forwarded to this target address along with a number of parameters that you can use to authenticate the person on your website.  These parameters are listed below.

The remote login setup menu (Under Setup > Remote Login) lets you add and manage the remote logins for your Zen Planner database. This is also where Zen Planner will generate the shared secret that makes the remote login secure.

The Details

When a staff person or a member clicks on one of the remote login links you've added to your Zen Planner database, they will be redirected to the target address that you entered when you set up the remote login connection.  In addition, some of their personal information (listed below) will be sent to the remote website as form POST data.  This personal data is what your remote website can use to validate that the person has successfully logged in to Zen Planner, and should be trusted on the remote website as well.

Parameter Description
firstName The first name of the person who is logged in to Zen Planner
middleName The middle name of the person who is logged in to Zen Planner
lastName The last name of the person who is logged in to Zen Planner
username The username (email address) of the person who is logged in to Zen Planner
timestamp The time when the remote authentication transaction was started.  This is used to prevent someone from "replaying" the remote login later.
signature The hash of the above data, which authenticates this transaction.  See below for details on validating the hash signature.

Validating the Timestamp

The timestamp is used to prevent someone from "replaying" the remote login later.  By including the timestamp, you can see when the authentication was created and deny remote logins that are too far in the past.

The timestamp is represented in the standard Unix time format, which is the number of seconds since epoch (in UTC).  Essentially, this means the total number of seconds since January 1st, 1970 at midnight (Greenwich Mean Time).  See http://en.wikipedia.org/wiki/Unix_time for more details.

When calculating the timestamp, it's important to remember to adjust for time zones.  Zen Planner will set the timestamp as of Greenwich Mean Time.  If you use a different time, it is likely that every remote login will look like an expired transaction.

Since the date and time of each web server may vary slightly, it's a good idea to allow timestamps with some buffer before and after.  We recommend that you allow ± 600 seconds (10 minutes) around each timestamp.  For instance, if Zen Planner sends you a timestamp of 1331063441 (March 6th, 2012 7:50:41 PM), then you should allow any timestamps between 1331062841 and 1331064041.

Calculating the Signature

The signature is used to validate that the account information provided is correct.  When your web service received the HTTP Post data from Zen Planner, you should calculate the signature using the data and the shared secret.  If your calculated signature matches the signature sent in the Post, then you can be certain that the post came from Zen Planner.

It is calculated using the SHA-512 algorithm.  It is calculated by like this:

// this is just pseudo-code
SHA512(sharedSecret + "|" + firstName + "|" + middleName + "|" + lastName + "|" + username + "|" + timestamp);

 

Remember that when you're generating the signature, the order of the information is important.  If you concatenate this data in the wrong order, the signature values will not match.

Testing the Remote Login

It can be difficult to test a remote API such as this.  To help you test and debug, you may consider using PostBin as an intermediary.  Setting PostBin as the target address for a remote login will help you to see the data that Zen Planner passes to your application each time a person clicks on one of the remote login links.

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

15 Comments

  • 0
    Avatar
    Dave Randolph

    This is probably going to be great as my members have a login for Zen and another for a wordpress/wishlist site and they can never keep them straight.

    I'll have to play around and see if I can get it to work with Wordpress/Wishlist Member

  • 0
    Avatar
    Matt Jubera

    So I got this working for my wordpress site, but I think this would make more sense if you could combine this functionality with embedding the member login page. Why would I want them going to myschoolsite.zenplanner.com to login to force them click a link to authenticate myschoolwebsite.com?

    I would want them to go to myschoolwebsite.com. If they are not logged in yet, login using the iframe, redirect them to the handshaking page to set their credentials and then send them to the myschoolwebsite.com with their credentials all set and now able to view the content. 

    I have attached the remotelogin.php so you should be able edit the file to paste in your secret key then upload it to your wordpress site. 

  • 0
    Avatar
    Matt Jubera

    I forgot to validate the timestamp in the attached file. use at your own risk.

  • 0
    Avatar
    Matt Jubera

    I am getting a bug in the timestamp. 

    I am getting from ZP:

    1334269390

    which translates to : Thu April 12 2012 22:23:10

    but the expected result is

    1334301790

    which translates to Fri April 13 2012 07:23:10 (and is the correct GMT)

    a difference of 9 hours.

  • 0
    Avatar
    Ben Pate

    Hi Matt,  It's great to see this working for you.  I'll follow up with you individually on the problems you're having.  If there's a problem with our date math then we'll correct it right away.

  • 0
    Avatar
    Uwem Ekpenyong

    Is there a way I/we can keep up with the development of the wordpress "plugin"? A solution of this sort would be of immense help.

  • 0
    Avatar
    Ben Pate

    Hi Uwem,

    We've actually posted the WordPress plugin to the WordPress plugin gallery.  From your WordPress blog, just go to the gallery and search for "Zen Planner".  You can install it right from there.  Awesome!

    Soon, we'll be adding more information about the WordPress plugin directly in your Zen Planner database.  Everything works great now -- you just happen to be asking in the period while we're getting all of the pieces staged for the big release.

  • 0
    Avatar
    Uwem Ekpenyong

    The plugin doesn't seem to provide the single sign-on that validates for the wordpress site and zen planner.

  • 0
    Avatar
    Ben Pate

    Hi Uwem,  You're correct.  Currently, the Plugin makes it easy to embed Zen Planner into your WordPress site, but it does not include the Remote Login API.  This is something that we'll plan to add in the future.

  • 0
    Avatar
    Chris Schear

    How about a Joomla! plugin?

  • 0
    Avatar
    Ben Pate

    Hi Chris,

    Right now, the Remote Login API itself is agnostic -- it can be used with any application.  Matt donated some PHP code to connect it to our WordPress plugin, and we'll be happy to do the same for any Joomla donations as well ;)

    I think we will likely include a lot of website content managers (like Joomla) in the future, but the rollout time lines will be a case-by-case basis.

  • 0
    Avatar
    Pranav sharma

    Hi , Is it possible to recieve and decrypt HTTP post data using javascript ?

    We can't use any server side language on our website and we don't have database access .

    We can only use javascript and we want to use remote login api . Please help

     

    Thanks

  • 0
    Avatar
    Ben Pate

    Hey Pranav,

    Yes, you should be able to implement the Remote Login API even through Javascript, although I'm a little confused about what you'd do with it there. I guess you've got a forum or chat room on your website that's implemented in Javascript?

    The actual work should not be too bad.  We're using a standard hash algorithm to "sign" the information that's posted to your website.  Depending on the Javascript library you're using, it shouldn't be tough to do.  We use Dojo Toolkit, and I know it has hashing algorithms in there.  JQuery is probably the most popular Javascript library right now, and I'd bet it has a similar ability too.  If you need more help with this, just send us a note at help@zenplanner.com

  • 0
    Avatar
    John Lin

    Matt, can you tell us where to put the remotelogin.php file on the wordpress site?

  • 0
    Avatar
    Matt Jubera

    Jon, 

    I just ftp'd it to www.mywebsite.com/remotelogin.php

Article is closed for comments.
Powered by Zendesk