Software Development Kit

cPanel & WHM's API [+] cPanel & WHM's API [-]


Modules and Plugins [+] Modules and Plugins [-]


cPanel & WHM Hooks [+] cPanel & WHM Hooks [-]


cPAddons (Site Software) [+] cPAddons (Site Software) [-]


System Administration [+] System Administration [-]


Developer Software [+] Developer Software [-]


Back to All Documentation

Authentication Function Call Methods

Overview

This document describes various authentication methods for API function calls in cPanel and WHM.

Authentication function call methods

In order to perform function calls with the cPanel and WHM API, you will need to access your server with the correct permissions.

To perform function calls in a browser, you need to first log in to WHM or cPanel to authenticate your session. Then, you will be able to access the function call through a URL such as https://example.com:2087/SECURITYTOKEN/json-api/functionname, where:

  • example.com represents your server's hostname or IP address
  • SECURITYTOKEN represents the security token for the session (For example, cpsess1234567890).
  • functionname represents the function you wish to access.

This method allows you to test a function call and verify the data output. However, the most powerful application of our API functions occurs when they are incorporated into users' custom scripts. From within these scripts you can use hash authentication, or you can authenticate with a username and password. We recommend that you use hash authentication to improve the security of the script.

Access hash authentication

You can write your script so that it includes an access hash, or "key," in the HTTP header that it sends to the server when it calls the API function. This method is only available to WHM users.

You can create or view an access hash from the WHM Setup Remote Access Key feature. On your server, the hash resides in the .accesshash file within the user's home directory. For example, the hash for root is in /root/.accesshash.

Sample Perl script

Show Hide

In a Perl script, the authentication code would look similar to the following example.

note Note: This example script requires the LWP::Protocol:https module. To install this module, run the command /scripts/perlinstaller LWP::Protocol::https before you use the script. Also, be sure that the script has execute permissions (chmod +x scriptname).

note Note: Be sure to replace accesshashhere with the contents of /root/.accesshash

#!/usr/bin/perl
use strict;
use LWP::UserAgent;
use LWP::Protocol::https;
 
my $hash = "accesshashhere";
 
$hash =~ s/\n//g;
 
my $auth = "WHM root:" . $hash;
$ENV{PERL_LWP_SSL_VERIFY_HOSTNAME}=0;
 
my $ua = LWP::UserAgent->new;
my $request =
  HTTP::Request->new( GET => "https://127.0.0.1:2087/xml-api/listaccts" );
$request->header( Authorization => $auth );
my $response = $ua->request($request);
print $response->content;

note Note: The previous example script is for a service with a self-signed certificate. If your server uses a trusted certificate for that service, remove the line with $ENV{PERL_LWP_SSL_VERIFY_HOSTNAME}=0;

Sample PHP script

Show Hide

In a PHP script, the authentication code would look similar to the following example:

<?

$whmusername = "root";
$whmhash = "somelonghash";
# some hash value

$query = "https://127.0.0.1:2087/....";

$curl = curl_init();
# Create Curl Object
curl_setopt($curl, CURLOPT_SSL_VERIFYHOST,0);
# Allow certs that do not match the domain
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER,0);
# Allow self-signed certs
curl_setopt($curl, CURLOPT_RETURNTRANSFER,1);
# Return contents of transfer on curl_exec
$header[0] = "Authorization: WHM $whmusername:" . preg_replace("'(\r|\n)'","",$whmhash);
# Remove newlines from the hash
curl_setopt($curl,CURLOPT_HTTPHEADER,$header);
# Set curl header
curl_setopt($curl, CURLOPT_URL, $query);
# Set your URL
$result = curl_exec($curl);
# Execute Query, assign to $result
if ($result == false) {
    error_log("curl_exec threw error \"" . curl_error($curl) . "\" for $query");
}
curl_close($curl);

print $result;

?>

Basic user/password authentication

You can write your script so that it includes a username and password in the HTTP header that it sends to the server when it calls the API function.

ALERT! Warning: Do not perform authentication this way over an unsecured connection (with port 2086 or 2082). The use of this method over an unsecured connection can compromise your server. If you have an SSL certificate, use port 2087 for WHM or port 2083 for cPanel to establish a secure connection with the server.

Sample Perl script

Show Hide

In a Perl script, the authentication code would look similar to the following example.

note Note: This example script requires the LWP::Protocol:https module. To install this module, run the command /scripts/perlinstaller LWP::Protocol::https before you use the script.

#!/usr/bin/perl
use strict;
use LWP::UserAgent;
use MIME::Base64;

my $user = "root";
my $pass = "password";

my $auth = "Basic " . MIME::Base64::encode( $user . ":" . $pass );

print $auth;

my $ua = LWP::UserAgent->new;
my $request =
  HTTP::Request->new( GET => "https://127.0.0.1:2087/xml-api/listaccts" );
$request->header( Authorization => $auth );
my $response = $ua->request($request);
print $response->content;

Sample PHP script

Show Hide

In a PHP script, the authentication code would look similar to the following example:

<?

$whmusername = "username";
$whmpassword = "password";

$query = "https://127.0.0.1:2087/";

$curl = curl_init();		
# Create Curl Object
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER,0);	
# Allow self-signed certs
curl_setopt($curl, CURLOPT_SSL_VERIFYHOST,0); 	
# Allow certs that do not match the hostname
curl_setopt($curl, CURLOPT_HEADER,0);			
# Do not include header in output
curl_setopt($curl, CURLOPT_RETURNTRANSFER,1);	
# Return contents of transfer on curl_exec
$header[0] = "Authorization: Basic " . base64_encode($whmusername.":".$whmpassword) . "\n\r";
curl_setopt($curl, CURLOPT_HTTPHEADER, $header);  
# set the username and password
curl_setopt($curl, CURLOPT_URL, $query);			
# execute the query
$result = curl_exec($curl);
if ($result == false) {
	error_log("curl_exec threw error \"" . curl_error($curl) . "\" for $query");	
# log error if curl exec fails
}
curl_close($curl);

print $result;

?>

Internal Session Tool and Single Sign On

In cPanel & WHM version 11.40, when root and resellers in WHM access cPanel accounts through List Accounts or the create_user_session WHM API function call, the Internal Session Tool generates a temporary user. This allows third-party applications that have WHM access, through either access hash or password, to log in to cPanel accounts without the need to store the account password.

Third-party applications can access the following services:

  • Logaholic
  • PHPMyAdmin
  • PHPPgAdmin
  • Restoration of MySQL backups
  • Other areas of cPanel that previously required a password to operate.

Temporary users can access to the following services:

  • MySQL
  • Logaholic
  • PostgreSQL

The temporary users are automatically destroyed when the session logs out or the session expires.

note Note: A temporary user (cpses_RANDOMSTRING) is created upon login to cPanel with a temporary password.

Single Sign On session log

The session log contains two types of entries:

Type Description
NEW A new session had been added. This entry consists of a comma-separated concatenated list of key-value pairs:
Session ID: The session ID that was created
address: The IP Address from which the session was requested.
app: The application that created the session.
creator: The username that created the session.
method: The method used to create the session.
path: The path to the process which created the session.
possessed: Whether this session is being impersonated.
PURGE A session has been removed. This entry ends with a reason code.

127.0.0.1 [12/05/2013:06:36:09 -0000] PURGE fz49w:ym5mFKRIAChAQ_yHyn6i19p6DQupDepQN4I3HnH490AAWPFSP2ZipQ7YpE_uA_CG logout
127.0.0.1 [12/05/2013:06:36:12 -0000] NEW z2p:BADVVmryioLExTGvKITEbSuDFHztNAyEeetBPpUmA8sA8Iu_y4eofHZmbbzIG2UU address=127.0.0.1,app=cpaneld,creator=z2p,method=handle_form_login,path=form,possessed=0
127.0.0.1 [12/05/2013:06:36:13 -0000] PURGE z2p:BADVVmryioLExTGvKITEbSuDFHztNAyEeetBPpUmA8sA8Iu_y4eofHZmbbzIG2UU loginsucess
127.0.0.1 [12/05/2013:06:36:13 -0000] NEW z2p:qgBu2rqQh_9R4tDhD2qgqVx0Oy21Ezy6_E581eYvBv0AbuA5oMZAWw_l0vahOhiH address=127.0.0.1,app=cpaneld,creator=z2p,method=handle_form_login,path=form,possessed=0

PURGE entries end with a code that explains the reason why the session was purged:

Reason Code Description
badpass Authenticated failed in any way.
expired Session expired.
kill Session was killed by any system that did not provide a reason.
loadsession The user logged in with a session token (/login/?session=...) and it was destroyed when the new session was created.
loginsuccess The user was successfully logged in and a new session was created for them.
logout User logged out.
xfercpanel Session was transferred to cPanel from WHM.
xferwebmail Session was transferred to Webmail from cPanel.

Additional resources

These authentication functions are also implemented in the cPanel/WHM "Accounting" modules, which are installed on your server in the /usr/local/cpanel/Cpanel/Accounting/ directory.

You can review these modules for more insight into how to structure your scripts.

Topic revision: r13 - 13 Jan 2014 - 21:50:16 - Main.LaurenceSimon