Difference between revisions of "AutoAuth"

From WHMCS Documentation

(Enabling AutoAuth)
 
(20 intermediate revisions by 7 users not shown)
Line 1: Line 1:
 +
<div class="docs-alert-info">
 +
AutoAuth was deprecated in WHMCS 7.10 and removed in WHMCS 8.1.
 +
* We recommend that you replace this with the [https://developers.whmcs.com/api-reference/createssotoken/ CreateSsoToken API] using [[WHMCS Single Sign-On]].
 +
* The information in this document only applies to WHMCS 7.9 and earlier.
 +
</div>
 +
 
==What is AutoAuth?==
 
==What is AutoAuth?==
 
+
AutoAuth stands for Automatic Authentication and is a method for you to be able to automatically log a user in from your own trusted third party code. For example you might use it if you have another software on your website which clients already log into, and once they have logged into that you don't want them to have to re-authenticate again seperately to access WHMCS.
+
AutoAuth stands for Automatic Authentication and is a method that lets you automatically log a user in from your own trusted third-party code. For example, you might use it if you have another software on your website that clients already log in to, and, once they have logged in to that, you don't want them to have to reauthenticate separately to access WHMCS.
 
+
 
==How does it work?==
 
==How does it work?==
 +
 +
AutoAuth works by constructing a special URL to redirect the user to WHMCS, which WHMCS then verifies. If it is valid, it activates the user's login session in WHMCS automatically before redirecting the user to the page you specified in the link.
 +
 +
This skips the need to know the user's password to access the user's account. Only use it when you have already authenticated the user in your own application.
 +
 +
The security comes from having a key that is shared only between your own WHMCS installation and the third-party code you're making the request from, and only knowing that key allows an AutoAuth request to be constructed for WHMCS.
 +
 +
==Enabling/Disabling AutoAuth==
 +
 
 +
AutoAuth is disabled by default.
  
The way it works is by constructing a special url to redirect the user to WHMCS, which WHMCS then verifies and if valid, activates the users login session in WHMCS automatically before redirecting the user on to the page you specified in the link.
+
To enable it:
 
 
This skips the need to know the users password to access the users account and so must only be used when you have already authenticated the user in your own application.
 
 
 
The security comes from having a key that is shared only between your own WHMCS installation and the third party code you're making the request from, and only knowing that key allows an autoauth request to be constructed for your WHMCS.
 
  
==Enabling AutoAuth==
+
# Add the following line to your WHMCS <tt>configuration.php</tt> file to define an AutoAuth key. The value needs to be a randomly-generated sequence of letters and numbers:<div class="source-cli">$autoauthkey = "abcXYZ123"</div>
 
+
# If you use WHMCS 7.10 or later, enable '''Allow AutoAuth''' in the '''[[Security Tab|Security]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''' (WHMCS 8.0) or, for WHMCS 7.10,  '''Setup > General Settings'''.
AutoAuth is disabled by default so to enable it for your WHMCS install, you will need to add the following line to your WHMCS configuration.php file to define an AutoAuth key. The value just needs to be a random sequence of letters and numbers:
 
 
 
$autoauthkey = "abcXYZ123";
 
  
 
==Using AutoAuth==
 
==Using AutoAuth==
 
+
To use AutoAuth, you simply need to formulate a request like the example below containing the users email address, timestamp of the time the request was generated, the AutoAuth hash and then optionally a "goto" parameter to specify where to send the user after successful authentication.
+
To use AutoAuth, formulate a request like the example below. This must contain the user's email address, the timestamp of the time the request was generated, the AutoAuth hash, and, optionally, a <tt>goto</tt> parameter to specify where to send the user after successful authentication.
 
+
dologin.php?email=demo@whmcs.com&timestamp=1290100706&
+
<div class="source-cli">
hash=0ec890a9a733d723eca637401ba2b7afb34cdf45&goto=index.php
+
dologin.php?email=demo@whmcs.com&timestamp=1290100706&hash=0ec890a9a733d723eca637401ba2b7afb34cdf45&goto=index.php
 
+
</div>
So in this example, it would login the client demo@whmcs.com and take them to the homepage after login.
+
 
+
In this example, it would <tt>demo@whmcs.com</tt> in as the client and take them to the homepage after login.
*The email variable needs to be the email address for the clients account you wish to login to
+
*The timestamp must be within 15 minutes of the server time for the autoauth to be accepted, otherwise the link is considered to be expired
+
*The email variable needs to be the email address for the client account you wish to log in to.
*The AutoAuth hash is generated by performing an sha1 hash of the email, timestamp and AuthAuth key you defined earlier in the WHMCS configuration.php file as follows:
+
*The timestamp must be within 15 minutes of the server time for AutoAuth to be accepted. Otherwise, the link is considered expired.
 
+
*The AutoAuth hash is generated by performing an SHA-1 hash of the email, timestamp, and AutoAuth key you defined earlier in the WHMCS <tt>configuration.php</tt> file. This should appear as follows:
  $hash = sha1($email.$timestamp.$autoauthkey)
+
 +
<div class="source-cli">
 +
$hash = sha1($email.$timestamp.$autoauthkey);
 +
</div>
 +
 +
==Sample Script==
 +
   
 +
The sample code below demonstrates how you can use AutoAuth in your external application to a log a user in to WHMCS:
 +
 +
<source lang="php">
 +
<?php
 +
/**
 +
* WHMCS AutoAuth Demo Script
 +
*  Docs: http://docs.whmcs.com/AutoAuth
 +
*/
 +
 +
// Define WHMCS URL & AutoAuth Key
 +
$whmcsurl = "https://www.example.com/whmcs/dologin.php";
 +
$autoauthkey = "strong_auto_auth_key_goes_here";
 +
 +
$timestamp = time(); // Get current timestamp
 +
$email = 'demo@whmcs.com'; // Clients Email Address to Login
 +
$goto = 'clientarea.php?action=products';
 +
 +
$hash = sha1($email . $timestamp . $autoauthkey); // Generate Hash
 +
 +
// Generate AutoAuth URL & Redirect
 +
$url = $whmcsurl . "?email=$email&timestamp=$timestamp&hash=$hash&goto=" . urlencode($goto);
 +
header("Location: $url");
 +
exit;
 +
</source>

Latest revision as of 19:42, 18 April 2022

AutoAuth was deprecated in WHMCS 7.10 and removed in WHMCS 8.1.

What is AutoAuth?

AutoAuth stands for Automatic Authentication and is a method that lets you automatically log a user in from your own trusted third-party code. For example, you might use it if you have another software on your website that clients already log in to, and, once they have logged in to that, you don't want them to have to reauthenticate separately to access WHMCS.

How does it work?

AutoAuth works by constructing a special URL to redirect the user to WHMCS, which WHMCS then verifies. If it is valid, it activates the user's login session in WHMCS automatically before redirecting the user to the page you specified in the link.

This skips the need to know the user's password to access the user's account. Only use it when you have already authenticated the user in your own application.

The security comes from having a key that is shared only between your own WHMCS installation and the third-party code you're making the request from, and only knowing that key allows an AutoAuth request to be constructed for WHMCS.

Enabling/Disabling AutoAuth

AutoAuth is disabled by default.

To enable it:

  1. Add the following line to your WHMCS configuration.php file to define an AutoAuth key. The value needs to be a randomly-generated sequence of letters and numbers:
    $autoauthkey = "abcXYZ123"
  2. If you use WHMCS 7.10 or later, enable Allow AutoAuth in the Security tab at Configuration () > System Settings > General Settings (WHMCS 8.0) or, for WHMCS 7.10, Setup > General Settings.

Using AutoAuth

To use AutoAuth, formulate a request like the example below. This must contain the user's email address, the timestamp of the time the request was generated, the AutoAuth hash, and, optionally, a goto parameter to specify where to send the user after successful authentication.

dologin.php?email=demo@whmcs.com&timestamp=1290100706&hash=0ec890a9a733d723eca637401ba2b7afb34cdf45&goto=index.php

In this example, it would demo@whmcs.com in as the client and take them to the homepage after login.

  • The email variable needs to be the email address for the client account you wish to log in to.
  • The timestamp must be within 15 minutes of the server time for AutoAuth to be accepted. Otherwise, the link is considered expired.
  • The AutoAuth hash is generated by performing an SHA-1 hash of the email, timestamp, and AutoAuth key you defined earlier in the WHMCS configuration.php file. This should appear as follows:

$hash = sha1($email.$timestamp.$autoauthkey);

Sample Script

The sample code below demonstrates how you can use AutoAuth in your external application to a log a user in to WHMCS:

<?php
/**
 * WHMCS AutoAuth Demo Script
 *  Docs: http://docs.whmcs.com/AutoAuth
 */
 
// Define WHMCS URL & AutoAuth Key
$whmcsurl = "https://www.example.com/whmcs/dologin.php";
$autoauthkey = "strong_auto_auth_key_goes_here";
 
$timestamp = time(); // Get current timestamp
$email = 'demo@whmcs.com'; // Clients Email Address to Login
$goto = 'clientarea.php?action=products';
 
$hash = sha1($email . $timestamp . $autoauthkey); // Generate Hash
 
// Generate AutoAuth URL & Redirect
$url = $whmcsurl . "?email=$email&timestamp=$timestamp&hash=$hash&goto=" . urlencode($goto);
header("Location: $url");
exit;