Difference between revisions of "LoginShare"
(Created page with '==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 wit…') |
|||
| Line 9: | Line 9: | ||
The hook point name for a LoginShare Module is: | The hook point name for a LoginShare Module is: | ||
| − | + | <div class="docs-alert-info"> | |
| + | |||
| + | '''ClientLoginShare''' | ||
| + | </div> | ||
| + | |||
| + | The hook point is run when the client does not exist in the WHMCS database. | ||
The variables passed into this hook are: | The variables passed into this hook are: | ||
| − | + | <div class="docs-alert-info"> | |
| − | + | '''username''' - the username the user entered into the login form (normally an email address)<br/> | |
| + | '''password''' - the password the user entered into the login form | ||
| + | </div> | ||
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. | 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. | ||
| Line 22: | Line 29: | ||
For a '''failed authentication''' you should return a false or empty result from the hook. For example: | For a '''failed authentication''' you should return a false or empty result from the hook. For example: | ||
| − | + | <source lang="php"> | |
| + | return false; | ||
| + | </source> | ||
===Successful Authentication=== | ===Successful Authentication=== | ||
| Line 28: | Line 37: | ||
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: | 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: | ||
| − | + | <source lang="php"> | |
| + | return array('id'=>'123'); | ||
| + | </source> | ||
or | or | ||
| − | + | <source lang="php"> | |
| + | return array('email'=>'user@domain.com'); | ||
| + | </source> | ||
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: | 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: | ||
| − | + | <source lang="php"> | |
| + | return array( | ||
'email' => 'user@domain.com', | 'email' => 'user@domain.com', | ||
'create' => true, | 'create' => true, | ||
| Line 50: | Line 64: | ||
'phonenumber' => '123456789', | 'phonenumber' => '123456789', | ||
'password' => 'abc123', | 'password' => 'abc123', | ||
| − | + | ); | |
| + | </source> | ||
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. | 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. | ||
| Line 60: | Line 75: | ||
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. | 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. | ||
| − | + | <source lang="php"> | |
| − | + | <?php | |
| − | + | ||
| + | function loginshare_hook_test($vars) { | ||
$username = $vars['username']; | $username = $vars['username']; | ||
| Line 70: | Line 86: | ||
return false; | return false; | ||
| − | + | ||
| − | + | } | |
| − | + | ||
| − | + | add_hook("ClientLoginShare",1,"loginshare_hook_test"); | |
| − | + | ||
| − | + | ?> | |
| + | </source> | ||
Revision as of 13:40, 11 December 2014
Contents
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.
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@domain.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@domain.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");
?>