cPanel® Blog

Using WHM remote authentication

One thing that I have noticed while working with other people developing software that interacts with WHM’s XML API is that they always use basic HTTP authentication. It is okay to use basic authentication, but it is held to the same security restrictions in place for people using browsers. When working with cPanel in a remote fashion, having to work around these restrictions is unnecessary. Inside of our DNS clustering system, we developed a solution for just this problem called WHM Remote Access Keys or “WHM auth”.

The way that WHM auth works is by passing a key inside of the HTTP headers to cpsrvd (cPanel’s HTTP daemon). Your access key can be accessed and regenerated via Setup Remote Access Keys in WHM, or viewed via the file system at ~/.accesshash. These work both for root and resellers with support for cPanel users coming in the future.

When sending a WHM auth header to WHM, you’ll need to add the following as an HTTP header:
Authorization: WHM $user:$hash

where $hash is your access hash, stripped of all new lines.

When working with this functionality inside of scripts, it’s generally easiest to use an HTTP library for adding these headers. For example, if you wanted to use WHM auth inside of PHP & curl, you would simply add the following to the curl object before query:
$hash = “81a ….. 0af”; # Set up the Hash
$hash = preg_replace(‘(/r|/n)’, “”, $hash); # Strip newlines from the hash
$auth_header[0] = “Authorization: WHM $username:$hash”; # set up the Header Array
$curl_setopt($curl, CURLOPT_HTTPHEADER, $auth_header); # tell curl to use the header array

Of course, not everyone wants to use PHP for handling remote interactions, and I personally would not feel proper discussing how to authenticate to WHM without talking about Perl and LWP.

As always with Perl, there is more than one way to do it, so we will simply discuss the most simple. When calling LWP’s get function, you simply make the second argument a hash named “Authorization” with a value of something similar to
WHM $user:$hash. my $access_hash = “81a … 0af”; # set up the accesshash $access_hash =~ s/(n|r)//g; # Remove newlines from the accesshash my $auth_string = “WHM $user:$access_hash”; # create the authentication string $response = $lwp->get( $url, Authorization => $auth_string ); # send auth header with req

At this point, you can treat $response like a normal HTTP::Response object.

cPanel

The web hosting industry’s most reliable, intuitive control panel since 1997. With our first-class support and rich feature set, it’s easy to see why our customers and partners make cPanel & WHM their hosting platform of choice. For more information, visit cPanel.com.