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.
15 Comments