Reliable and secure authentication is an important part of many third-party integrations with WHMCS. For example, if an application like a website already requires clients to log in to that system, you might want to make sure those clients don't have to log in again just to access the portions of the application that interact with WHMCS. Recently, we've made some changes to how you can handle that authentication, making it not only simpler to implement but also more secure.
Since WHMCS 7.10, we have recommended using the CreateSsoToken API to direct users from an authenticated system to a mapped WHMCS client account. It's a robust and simpler mechanism for directing users from one authenticated system to a mapped client account within your WHMCS installation, generating Single Sign-On tokens for users and accounts through the API. As we move from our older, deprecated method, AutoAuth, to this new system, third-party developers will need to update their integrations in order to keep working with WHMCS. In WHMCS 8.1, we complete the transition with the removal of AutoAuth.
AutoAuth
For many WHMCS versions, Automatic Authentication, or AutoAuth, was the only available method of transparently authenticating a user from a trusted system into WHMCS. It required crafting a special redirection URL that WHMCS would then verify. If it was valid, WHMCS would create a login session and redirect the user to the page you indicated. As technology has evolved, single sign-on tokens, as produced by the new
CreateSsoToken API, have become ubiquitous and offer more robust security than was possible with AutoAuth. They also involve fewer technological limitations and are simpler to implement since it's the same as making any other WHMCS API call. You can also use this in conjunction with the users and accounts system we introduced in WHMCS 8.0, authenticating using either a client ID or user ID. Better Security
In the past, AutoAuth required a secret to generate the authentication hash, with only one secret available for any given WHMCS user. This required that multiple systems use the same secret when they established a session, which is not optimal for best security practices. Now, however, systems can use their own sets of API credentials to generate single sign-on tokens to authenticate users. Each system queries the API for credentials, compartmentalizing trust and security considerations and allowing one admin account to use many sets of credentials. There's no coupling between the security ciphers and your custom code, making your integration simple and forward-compatible.
Each set of credentials is both easy to create and easy to discard when a given remote system should no longer have the authority to issue single sign-on tokens. While the previous AutoAuth system generated links that were valid for 15 minutes, the single sign-on tokens generated through
CreateSsoToken are limited to one minute. It's important to note that you should only use this authentication method in systems that are fully trusted and in appropriate use cases. For security, you should already have validated the user's identity before reaching this point in your code, since this method bypasses user authentication and two-factor authentication.
Updating for Single Sign-On Tokens
If you're a developer, moving from AutoAuth to single sign-on tokens is as easy as implementing an API call. You just need to make the call and then redirect the user to the returned URL. WHMCS will transparently authenticate the user and direct them to your destination. You can check our CreateSsoToken API Developer Documentation for specific details and additional code samples. When you make your API call, you will need to include the client ID or user ID. If you have the email address, as was used for AutoAuth, you can look for the matching client ID by calling the GetClients API, using the search parameter to search for the correct email address. Single sign-on tokens that you generate with a client ID will authenticate as the user who is the account owner for that client account. In WHMCS 8.1 and later, to create a single sign-on token that authenticates based on the user ID, you can also use the
GetUsers API to find users by email address. Example
The PHP code below uses the CURL method to log in a client with an ID of 1 and take them to the Client Area product details page for a service with an ID of 1: <?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://www.example.com/includes/api.php');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS,
http_build_query(
array(
'action' => 'CreateSsoToken',
// See https://developers.whmcs.com/api/authentication
'username' => 'IDENTIFIER_OR_ADMIN_USERNAME',
'password' => 'SECRET_OR_HASHED_PASSWORD',
'client_id' => '1',
'destination' => 'clientarea:product_details',
'service_id' => '1',
'responsetype' => 'json',
)
)
);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
$response = curl_exec($ch);
curl_close($ch);
if (!$response) {
// manage cURL or other errors
throw new \RuntimeException('Unexpected Response');
}
$responseData = json_decode($response, true);
if (!is_array($responseData)
|| !isset($responseData['result'])
|| $responseData['result'] !== 'success'
) {
// manage failed API call
throw new \RuntimeException('Failed API Response');
}
// The API response will contain a full URL, similar to the following, that you can use in a redirect header:
// https://example.test/oauth/singlesignon.php?access_token=afaed4482ad1e6b75492cdd421cc458b1991a97c
$redirectURL = $responseData['redirect_url'] ?? '';
if (!$redirectURL) {
// manage missing API response data
throw new \RuntimeException('Unexpected API Data');
}
header('Location: ' . $redirectURL);
exit;
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://www.example.com/includes/api.php');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS,
http_build_query(
array(
'action' => 'CreateSsoToken',
// See https://developers.whmcs.com/api/authentication
'username' => 'IDENTIFIER_OR_ADMIN_USERNAME',
'password' => 'SECRET_OR_HASHED_PASSWORD',
'client_id' => '1',
'destination' => 'clientarea:product_details',
'service_id' => '1',
'responsetype' => 'json',
)
)
);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
$response = curl_exec($ch);
curl_close($ch);
if (!$response) {
// manage cURL or other errors
throw new \RuntimeException('Unexpected Response');
}
$responseData = json_decode($response, true);
if (!is_array($responseData)
|| !isset($responseData['result'])
|| $responseData['result'] !== 'success'
) {
// manage failed API call
throw new \RuntimeException('Failed API Response');
}
// The API response will contain a full URL, similar to the following, that you can use in a redirect header:
// https://example.test/oauth/singlesignon.php?access_token=afaed4482ad1e6b75492cdd421cc458b1991a97c
$redirectURL = $responseData['redirect_url'] ?? '';
if (!$redirectURL) {
// manage missing API response data
throw new \RuntimeException('Unexpected API Data');
}
header('Location: ' . $redirectURL);
exit;
Need more information? You can find out more in our Developer Documentation on the CreateSsoToken API.
