AutoAuth

From WHMCS Documentation

What is AutoAuth?

AutoAuth stands for Automatic Authentication and is a method for you to be able to automatically log a user in from your own trusted third party code. For example you might use it if you have another software on your website which clients already log into, and once they have logged into that you don't want them to have to re-authenticate again separately to access WHMCS.

How does it work?

The way it works is by constructing a special url to redirect the user to WHMCS, which WHMCS then verifies and if valid, activates the users login session in WHMCS automatically before redirecting the user on to the page you specified in the link.

This skips the need to know the users password to access the users account and so must only be used when you have already authenticated the user in your own application.

The security comes from having a key that is shared only between your own WHMCS installation and the third party code you're making the request from, and only knowing that key allows an autoauth request to be constructed for your WHMCS.

Enabling AutoAuth

AutoAuth is disabled by default so to enable it for your WHMCS install, you will need to add the following line to your WHMCS configuration.php file to define an AutoAuth key. The value just needs to be a random sequence of letters and numbers:

$autoauthkey = "abcXYZ123";

Using AutoAuth

To use AutoAuth, you simply need to formulate a request like the example below containing the users email address, timestamp of the time the request was generated, the AutoAuth hash and then optionally a "goto" parameter to specify where to send the user after successful authentication.

dologin.php?email=demo@whmcs.com&timestamp=1290100706&
hash=0ec890a9a733d723eca637401ba2b7afb34cdf45&goto=index.php

So in this example, it would login the client demo@whmcs.com and take them to the homepage after login.

  • The email variable needs to be the email address for the clients account you wish to login to
  • The timestamp must be within 15 minutes of the server time for the autoauth to be accepted, otherwise the link is considered to be expired
  • The AutoAuth hash is generated by performing an sha1 hash of the email, timestamp and AutoAuth key you defined earlier in the WHMCS configuration.php file as follows:
$hash = sha1($email.$timestamp.$autoauthkey);

Sample Script

The sample code below demonstrates how you can use AutoAuth in your external app to a log a user into WHMCS:

<?php
/**
 * WHMCS AutoAuth Demo Script
 *  Docs: http://docs.whmcs.com/AutoAuth
 */

// Define WHMCS URL & AutoAuth Key
$whmcsurl = "https://www.example.com/whmcs/dologin.php";
$autoauthkey = "strong_auto_auth_key_goes_here";

$timestamp = time(); // Get current timestamp
$email = 'demo@whmcs.com'; // Clients Email Address to Login
$goto = 'clientarea.php?action=products';

$hash = sha1($email . $timestamp . $autoauthkey); // Generate Hash

// Generate AutoAuth URL & Redirect
$url = $whmcsurl . "?email=$email&timestamp=$timestamp&hash=$hash&goto=" . urlencode($goto);
header("Location: $url");
exit;