Introduction
This guide explains the basics of how to test your custom code's authentication with the cPanel & WHM server. This document lists appropriate test steps for most custom code, and helpful information to troubleshoot common problems. Make certain that you evaluate the testing requirements of your own code, and allow its functionality to determine the appropriate steps.
Warning:
cPanel Technical Support cannot always assist third-party developers with problems that relate to custom code. For this reason, always test your projects thoroughly before you attempt to use them on production servers.
Testing steps
Note:
Because the testing requirements of custom code differ, this document begins with the assumption that you already discovered problems.
Check to ensure that you authenticated as the correct user.
Many authentication issues occur because the custom code does not authenticate as a user who has the correct permissions.
Important:
- cPanel users can only call cPanel API 1, cPanel API 2, and UAPI functions, and in many casesmust have access to the correct features for those functions.
- WHM users can call cPanel API 1, cPanel API 2, and UAPI functions, but you must specify a cPanel user to call those functions as.
Access Hash Authentication: Check to ensure that you formatted the access hash correctly.
When you use an access hash to authenticate as the root user, you must supply the hash as a single, unbroken line.
- Line breaks will cause authentication errors.
- To retrieve the server's access hash, use WHM's Remote Access Key interface (Home >> Clusters >> Remote Access Key).
Single Sign-On: Check to ensure that you retrieved the required cookie.
When you use Single Sign-On to authenticate, you must perform a GET request to the URL that the function returns as the url value.
- This request returns a cookie that must exist for subsequent API calls to authenticate successfully.
Troubleshoot common issues
FAILED LOGIN cpaneld: invalid cpanel user root
Problem:
You receive the following error:
FAILED LOGIN cpaneld: invalid cpanel user root
Solution:
This error occurs when you attempt to supply the root user as a cPanel user, generally in order to call a cPanel API 1, cPanel API 2, or UAPI function. The root user can only call WHM API functions, not cPanel functions. You may see similar errors if you attempt to authenticate as a reseller-level account, or as an account that does not exist on the server.
To resolve this issue, you must authenticate as a valid cPanel account.
Single Sign-On Request Failed with a Fatal Error: Client
Problem:
You receive the following error:
Single Sign-On Request Failed with a Fatal Error: Client
Solution:
This error occurs when custom code that uses the Single Sign-On method to authenticate receives an invalid user (for example, if you attempt to use Single Sign-On to authenticate as a reseller in order to run a cPanel function).
To resolve this issue, you must authenticate as a user with the correct permissions.
Missing Switch Account or Current User menu on reseller login via Single Sign-On method
Problem:
A reseller account authenticated successfully through the Single Sign-On method, but the Switch Account menu (cPanel & WHM version 56 and earlier) or Current User menu (cPanel & WHM version 58 and later) does not display as expected in the cPanel Home interface.
Solution:
Due to the way in which WHM API 1's create_user_session function creates a user session, this is intended behavior. The reseller authenticated successfully.