LoginShare

What is LoginShare?

LoginShare is the name of the API in WHMCS that can be used to authenticate users against a separate system. With LoginShare you can integrate WHMCS with any other third party applications, allowing you to create a single sign solution using any other existing user databases you have.

Creating a LoginShare Module

LoginShare modules in WHMCS use the flexible Hooks system as with most development in WHMCS. This means loginshare modules can be both standalone items, or part of modules in the system. If you aren't familiar with hooks, please refer to the Hooks section of our documentation.

The hook point name for a LoginShare Module is:

ClientLoginShare

The hook point is run when the client does not exist in the WHMCS database.

The variables passed into this hook are:

username - the username the user entered into the login form (normally an email address)
password - the password the user entered into the login form

Your custom hook function should take the username & password variables supplied, validate them against the remote system's database or API, and then return a response based on that.

Failed Authentication

For a failed authentication you should return a false or empty result from the hook. For example:

return false;

Successful Authentication

For a successful authentication you are expected to return either the WHMCS User ID or Email Address of the client to authenticate as. For example:

return array('id'=>'123');

or

return array('email'=>'user@example.com');

The above assumes the user already has a corresponding client account in WHMCS. If they do not, or if you are unsure if they do or not, then you can also return a true response to the create parameter, which when found will mean if WHMCS cannot find an existing match for the given email address, a client account will be automatically created. For this you must return a minimum of a name, email address & password. For example:

return array(
    'email' => 'user@example.com',
    'create' => true,
    'firstname' => 'Demo',
    'lastname' => 'User',
    'companyname' => 'Demo Company',
    'address1' => '123 Demo Street',
    'address2' => 'Sample',
    'city' => 'Sample',
    'state' => 'Sample',
    'postcode' => 'XYZ123',
    'country' => 'US',
    'phonenumber' => '123456789',
    'password' => 'abc123',
);

To clarify, returning the create=true parameter will only create a new client account if no existing match is found for the supplied email address. If an existing client account is found for the email address then the user will simply be authenticated into that account.

No signup welcome email is sent to the user when an account is setup for them in this way.

Sample Code

Here is a basic example that checks for a specific username & password combination, and if matching, logs the user into the existing client account ID 1.

<?php

function loginshare_hook_test($vars) {
 
     $username = $vars['username'];
     $password = $vars['password'];
 
     if ($username=="demo" && $password=="abc123") return array('id'=>'1');
 
     return false;

}

add_hook("ClientLoginShare",1,"loginshare_hook_test");

?>

Documentation