How to Authenticate WHMCS Admin Users with PHP

Over the past few days I've been working on a project that involved building an authentication mechanism for a new website which checks user logins against a WHMCS admin database. There are a variety of options for authenticating normal, non-admin WHMCS users: on the easy side of things, you can simply use the WHMCS API's validatelogin() call, or for a more advanced project its possible to implement OAuth within your WHMCS instance. For my project, neither LDAP nor Active Directory were options.

I was surprised to find that the WHMCS API did not contain a mechanism for authenticating admin users. I'm somewhat sympathetic given the security implications: WHMCS is a billing application and it should not be used to provide a sortof infrastructure authentication backbone, particularly given the many much more mature options available for this sort of thing. With that said, this project wasn't about looking to turn WHMCS into LDAP ... it was about allowing WHMCS admin to authenticate into a custom application that was directly and inextricably linked to WHMCS functionality.

When I came up empty on the API front I started Googling for a reasonable alternative, and I found a small number of other options. I became interested in the idea of building my own WHMCS API function to take care of this, but I still needed to take care of the authentication mechanism itself. WHMCS has a page in its documentation that describes in general terms how Admin passwords are hashed, and this page even contains PHP code samples that purport to allow you to auth admin user:password combinations. There are two samples; the first sample demonstrates how to use the WHMCS\Auth namespace and the comparePasswords() function, like so:

use WHMCS\Auth;
 
$authAdmin = new Auth;
 
if ($authAdmin->getInfobyUsername($username) && $authAdmin->comparePassword($password)) {
    $isValid = true;
} else {
    $isValid = false;
}

Pretty straightforward; and this sample works as far as it goes. However, WHMCS provides a second, more thorough example demonstrating how to use the function within a form. You can download a ZIP fie containing this sample here. Unfortunately, this second snippet is broken in a number of places. This second example provides a single file that contains an HTML form with some javascript to display a popup notification when an authentication failure occurs, and a PHP script that takes care of the password comparison. It is the PHP that has problems. I found a variety of fatal errors which made the example unusual: the WHMCS\Auth namespace was called in the wrong scope, the include for the WHMCS init Autoloader is called within a function in such a way that it remains unavailable for other functions, the example uses a class - WHMCS_Auth - which does not exist ... it took a little while for me to sort them out.

Anyway, I found the experience irksome enough that I posted a corrected version of the WHMCS Admin authentication script in a Github repo so that no one else will have to deal with this in the future. I've tested my new version in WHMCS 6.3.1; no guarantees for the latest version 7 at this time, but I can guarantee that WHMCS' example won't work in 7.

I hope it helps!