Hosted Help Desk Authentication API

Configuring single sign-on with your existing Web-apps and websites
(aka "remote login")

If your infrastructure supports SAML single-sign-on protocol, please read this article, otherwise, continue reading

Our Hosted helpdesk supports the "autologin" feature just like the downloadable version of the helpdesk. This feature allows users to be pre-authenticated automatically (by your parent website for example) without entering their username and password. The "autologin" feature is targeted at developers and administrators, who integrate the Hosted HelpDesk software into their existing websites and applications. If the user is already authenticated on your parent website (for instance) here's how you redirect him to the helpdesk application:

• No matter if a user is already present in the helpdesk database or not, use this link format: http://Helpdesk_Url/User/AutoLogin?username=xxx&email=yyy&userHash=HASH. The helpdesk will either create a new user account or use the existing one.
• In the URL above:
  • Helpdesk_Url is the full helpdesk URL (for example "foo.jitbit.com/helpdesk/" if you're using the hosted version)
  • username is the user's username
  • email is the email
  • HASH is calculated as follows: SHA256(name + email + shared-secret + day + month), truncated to the first 28 characters. The "shared secret" is specified in the helpdesk's admin panel. Remember to specify a strong secret, at least 10 characters (the longer the better). The day and month values should be the current day of the month and current month formatted as TWO DIGITS, so "January 1st" should become "0101".

Note: The previous MD5-based method has been deprecated and replaced with SHA256 for improved security.

You can optionally add FirstName=xxx and LastName=xxx parameters to the URL, so the newly-created helpdesk user will have the First/Last names pre-set. You can also pass CompanyName=xxx so the auto-created user will have a company assigned.

Examples:

// Python
import hashlib
from datetime import datetime

name = "John"
email = "john@example.com"
secret = "mysharedsecret"
now = datetime.now()
day_month = now.strftime("%d%m")
raw = name + email + secret + day_month
hash = hashlib.sha256(raw.encode()).hexdigest()[:28]
print(hash)

// JavaScript (Node.js)
const crypto = require('crypto');

const name = "John";
const email = "john@example.com";
const secret = "mysharedsecret";
const now = new Date();
const day = String(now.getDate()).padStart(2, '0');
const month = String(now.getMonth() + 1).padStart(2, '0');
const raw = name + email + secret + day + month;
const hash = crypto.createHash('sha256').update(raw).digest('hex').slice(0, 28);
console.log(hash);

// C# (.NET)
using System;
using System.Security.Cryptography;
using System.Text;

string name = "John";
string email = "john@example.com";
string secret = "mysharedsecret";
string dayMonth = DateTime.Now.ToString("ddMM");
string raw = name + email + secret + dayMonth;

using (SHA256 sha = SHA256.Create())
{
    byte[] hashBytes = sha.ComputeHash(Encoding.UTF8.GetBytes(raw));
    string hash = BitConverter.ToString(hashBytes)
                    .Replace("-", "")
                    .ToLower()
                    .Substring(0, 28);
    Console.WriteLine(hash);
}

When using the "autologin" feature you can optionally redirect users to the "new ticket" page. Just add &new_ticket=1 to the link above. You can also add a "ReturnUrl" parameter and send the user to whatever page you need, a ticket, a report, search page or anything. Just add &ReturnUrl=%2fhelpdesk%2fUser%2fProfile (for example). The URL can be relative or absolute.