Revision as of 18:47, 13 April 2021

The WHMCS licensing addon module allows you to license your own web applications for selling to end users. Supporting both local license keys and periodic remote checking, it offers a robust and secure way of licensing your scripts.

Installation

By purchasing the licensing addon, this will unlock access to the licensing addon module files which are now bundled with the default WHMCS install package. So after purchasing, there are no manual installation steps necessary any more - you just need to activate and configure the module in Configuration () > System Settings > Addon Modules or, prior to WHMCS 8.0, Setup > Addon Modules. The following options are available:

• Public License Verification Tool - Enable this option to make available a verification page which visitors can use to check whether a domain is licensed to be using your software. The appearance can be customised by editing the /modles/addons/licensing/licenseverify.tpl template file. It's accessed at http://www.yoursite.com/whmcs/index.php?m=licensing
• Maximum Allowed Reissues - Should you wish to limit how many times a client can reissue a licence, specify the maximum number of reissues here.
• Auto Logs Prune - To prevent the licence access logs from becoming too large you can specify for how long they should be kept.

Setting up a licensing product

1. Begin by creating a product under Configuration () > System Settings > Products/Services or, prior to WHMCS 8.0, Setup > Products/Services. More information on creating products is available at Products and Services
2. On the module settings tab, choose "License Software" in the Module dropdown
3. The options for a licensing product will then appear. These are explained in detail below:

• Key Length - this defines how long the randomly generated key will be - enter the numerical value you want
• Key Prefix - this defines the start of the license key and is how you can validate an applicable key for the product you're performing the checking in has been entered - eg. Monthly-, Owned-, Mobile-, etc...
• Allow Reissue - determines whether a client can reissue the license from the client area
• Allow Domain Conflict - When unticked WHMCS will make sure the location at which the licence is being used matches the 'Valid Domain' value in the service record. Tick the option if you want to allow a user to run the product on multiple domains.
• Allow IP Conflict - as above but for the IP address
• Allow Directory Conflict - as above but for the directory
• Support/Updates Addon - explained in detail below
• Free Trial - This option can be ticked to prevent clients from using more than one licence of this product on the same domain. If a client tries to order a second copy of this product and use it on the same domain as a previous service, it will be automatically suspended with the reason "Duplicate Free Trial Use". Useful for limiting free trials to one per domain.

Downloads

Downloads are how your client receives the software product after purchase. These are configured using the existing digital download product release mechanism. For more information on this, refer to Product Downloads Distribution

Addons

Each product can be assigned multiple addon products which can be added at the time of initial ordering or at a later date. Uses for addons include extra value added services such as installation, configuration, upgrades, etc... They allow you to charge additional fees for items which aren't required in order to utilise the actual product.

Support & Update Addons

If you enable these on your licensing product, then the client is required to have an active support & updates package in order to receive support & download the related product downloads. This means you can charge your users for the continued support and updates using any of the recurring terms available to you in WHMCS.

Setting up a Support & Updates Addon Package

The guide below explains how to create a support & updates package which is include free with the initial license purchase and then requires renewal once it expires.

1. Ensure your licensing product is created first
2. Then, go to Configuration () > System Settings > Product Addons or, prior to WHMCS 8.0, Setup > Products/Services > Product Addons.
3. Click Add New.
4. Enter the name, description, price and recurring cycle - leave the Show on Order setting unchecked
5. Now tick the licensing product(s) in the applicable products section for the addon
6. Now go back to the product configuration area and click the edit icon next to your licensing product
7. On the Module Settings tab, choose the addon you just created in the "Support/Updates Addon" field and save

And that's it! If you didn't want to include it free with the initial purchase, you would leave the setting on the Module Settings tab at None and tick the box for Show on Order in the addon configuration.

Module Commands

• Create - Used to generate the license key for the product with status Reissued
• Suspend - This will set the license status to Suspended
• Unsuspend - This will set the license status back to Active
• Terminate - This will set the license status to Expired
• Reissue - Sets the license status to Reissued so the domain, IP & directory is saved on the next check
• Revoke - This command will completely remove the license key and allow the number to be reused in future
• Manage - This button takes you to where you can view & edit the allowed domain, IP & directory for the license

Managing Licenses

To manage licenses, go to Addons > Licenses Manager. From here you can browse through all the license keys that have been issued, search for license keys and make changes to the allowed domains, ips and directory for a license.

Integrating the Check Code

The code used to integrate the license check is included with the addon in the /modules/servers/licensing/check_sample_code.php file. The idea here is that you would have your user enter the license key they get issued during an install process or by simply pasting it into a file, and then you load that in your file before calling the check_license function to validate where the file is being run. For each successful check, a local key is returned which you then also store in your DB or a file to verify against locally on subsequent page loads.

The steps to integrate are described in more detail below:

1. Copy & paste the code into the top of the file you want to protect
2. Enter the URL to your WHMCS system root directory in the $whmcsurl variable
3. Customise the $licensing_secret_key variable used to ensure your local keys are different from other licensing addon users
4. Optionally change the $localkeydays & $allowcheckfaildays variables if you want to change how often a remote check is made
5. Now retrieve the license key and local key from the database or file storage you have saved them in
6. Then call the check_license function
7. And then act on the result based on the sample code if statements
8. You then store the local key that gets returned

Using Product Addons

If the licensing product has any ordered addons, the results from the licensing addon will include a pipe separated string called "addons" with their details that can be processed and used for any number of purposes. For example: restricting access to certain features unless a particular addon has been ordered.

[addons] => name=Test Addon;nextduedate=2017-12-26;status=Active

This can be processed into a named array called $addons from the $results array returned by your check_license function. To do so, use the following code:

$tempresults = explode("|",$results["addons"]);
foreach ($tempresults AS $tempresult) {
  $tempresults2 = explode(";",$tempresult);
  $temparr = array();
 
  foreach ($tempresults2 AS $tempresult) {
  $tempresults3 = explode("=",$tempresult);
    $temparr[$tempresults3[0]] = $tempresults3[1];
  }
 
  $addons[] = $temparr;
}

Using Configurable Options

If the licensing product has any ordered configurable options, the results from the licensing addon will include a pipe separated string called "configoptions" with their details that can be processed and used for any number of purposes. For example: limiting usage of software to a particular number of clients or admin users.

[configoptions] => Test=0|Test 002=

This can be processed into a named array called $configoptions from the $results array returned by your check_license function. To do so, use the following code:

$tempresults = explode("|",$results["configoptions"]);
foreach ($tempresults AS $tempresult) {
  $tempresults2 = explode("=",$tempresult);
  $temparr = array();
 
  foreach ($tempresults2 AS $key => $value) {
    $temparr[$key] = $value;
  }
 
  $configoptions[] = $temparr;
}

Frequently Asked Questions

What is the local key?

The local key is the thing that stops the license checking code having to call your server on every page load. It's basically just an encrypted version of the license check data, so that when it's present and valid, the licensing addon doesn't have to make a remote call which would slow down your application/code, thus improving performance. The local key will always be empty on the first check your client makes, but then with every successful remote check, a local key value is returned (sample code provided) which you then just need to store and pass into any future license check calls. We recommend storing into a database for ease of updating and retrieval, but flat files can work just as well.

Common Issues

Invalid Key

This generally indicates that the licensing checking code is not passing a license key back to the licensing addon. The code being used will need to be corrected to ensure that it is returning the full license key to WHMCS.

Remote Check Failed

This suggests a connection problem between the user's server and the end client's server.

The first step will be to provide the user with a cURL test script that attempts to connect to your WHMCS installation and run it from their server, correcting any detected issues.

If that all appears clear, it could be due to a SSL configuration issue on the user's server. As a workaround, you can potentially add the following into your licence checking code:

curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);

A new local key is being generated on every request

This behaviour suggests that the local licence key returned by the license checking function after a successful check is not being stored. When no local licence key is stored and passed into the licensing checking function, a remote check has to be performed and a new local key is generated.

Storing the local license key returned by the license checking function and passing it back into the checking function should resolve this. We recommend storing it in a way most appropriate for your particular software, for example in a flat file or in a database.