Single Sign-On into WHMCS

WHMCS Single Sign-on allows trusted applications and third parties to authenticate users into a WHMCS installation automatically, without requiring that the user reauthenticate. Instead, users go to a specific WHMCS Client Area destination using a single-use access token from your system.

  • Single sign-on into WHMCS uses the OAuth 2.0 authorization framework to ensure security throughout the process.
  • Users can disable single sign-on into the Client Area at any time by going to Account > Security Settings.
The information below is for developers and system administrators who want to set up their websites or applications to use WHMCS single sign-on.

Supported Methods

You can sign users in to WHMCS using single sign-on using the following methods:

Single Sign-On via Supported Applications

Supported applications like cPanel & WHM can perform single sign-on into WHMCS using the existing trust relationship.

For more information, see Application Links.

Single Sign-On via API

Due to the use of admin-level API credentials, this method of integration is only appropriate when the remote system is not accessible at the user level.

The CreateSsoToken API function allows you to script your own token generation on demand. For most uses, this is the simplest way to perform single sign-on into WHMCS.

To use this, call the API function in your custom code and redirect your user to the returned redirect_url URL.

Single Sign-on via OAuth Token

Single sign-on using an OAuth Token API Endpoint uses the following process:

  1. The application requests an access token by sending its credentials to the OAuth Token API Endpoint.
  2. If the system successfully verifies the application credentials, the WHMCS authentication server will return an access token to the application.
  3. The application redirects the user to the Single Sign-On API Endpoint, passing in the token and desired destination (scope).
  4. The user is authenticated and goes to the requested destination.

Performing single sign-on into WHMCS requires an OAuth Credential Set with the single sign-on grant type.

This method of integration is appropriate when the remote system provides limited user-level access to input. The system limits trust credentials to the individual user, removing the risk of generating tokens to resources or destinations beyond their ownership.

Supported Destinations

You can use single sign-on to access the following locations (scopes) in WHMCS:

Scope NameDestinationsVariable Input
clientarea:profileMy Details
clientarea:billing_infoManage Billing Information/Credit Card
clientarea:emailsMy Emails
clientarea:announcementsAnnouncements
clientarea:downloadsDownloads
clientarea:knowledgebaseKnowledgebase
clientarea:network_statusNetwork Status
clientarea:servicesMy Products/Services
clientarea:product_detailsProduct Details/Informationservice_id
clientarea:domainsMy Domains
clientarea:domain_detailsDomain Details/Informationdomain_id
clientarea:invoicesMy Invoices
clientarea:ticketsMy Support Tickets
clientarea:submit_ticketOpen New Ticket
clientarea:shopping_cartShopping Cart Default Product Group
clientarea:shopping_cart_domain_registerShopping Cart Register Domain
clientarea:shopping_cart_domain_transferShopping Cart Transfer Domain
clientarea:upgradesShopping Cart Addonsservice_id
sso:custom_redirect (API only)Custom path of the WHMCS deploymentsso_redirect_path

Errors

You may see the following errors while working with single sign-on into WHMCS:

ErrorDescription
Single Sign-On authentication denied for "Closed" User ID: xxTo perform single sign-on into WHMCS, the client status must be Active or Inactive.
Single Sign-On authentication denied per configuration for User ID: xxNo user or admin can use single sign-on to access an account if it is disabled at Account > Security Settings.
Unable to authenticate with Single Sign-On token for User ID: xxThe token failed for an unspecified reason.
OAuth authorization request denied due to unexpected active login session for "Closed" User ID: xxThere is already an active session for an account that is in the Closed status.

Last modified: June 11, 2024