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:

The application requests an access token by sending its credentials to the OAuth Token API Endpoint.
If the system successfully verifies the application credentials, the WHMCS authentication server will return an access token to the application.
The application redirects the user to the Single Sign-On API Endpoint, passing in the token and desired destination (scope).
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 Name	Destinations	Variable Input
`clientarea:profile`	My Details
`clientarea:billing_info`	Manage Billing Information/Credit Card
`clientarea:emails`	My Emails
`clientarea:announcements`	Announcements
`clientarea:downloads`	Downloads
`clientarea:knowledgebase`	Knowledgebase
`clientarea:network_status`	Network Status
`clientarea:services`	My Products/Services
`clientarea:product_details`	Product Details/Information	`service_id`
`clientarea:domains`	My Domains
`clientarea:domain_details`	Domain Details/Information	`domain_id`
`clientarea:invoices`	My Invoices
`clientarea:tickets`	My Support Tickets
`clientarea:submit_ticket`	Open New Ticket
`clientarea:shopping_cart`	Shopping Cart Default Product Group
`clientarea:shopping_cart_domain_register`	Shopping Cart Register Domain
`clientarea:shopping_cart_domain_transfer`	Shopping Cart Transfer Domain
`clientarea:upgrades`	Shopping Cart Addons	`service_id`
`sso:custom_redirect` (API only)	Custom path of the WHMCS deployment	`sso_redirect_path`

Errors

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

Error	Description
`Single Sign-On authentication denied for "Closed" User ID: xx`	To perform single sign-on into WHMCS, the client status must be Active or Inactive.
`Single Sign-On authentication denied per configuration for User ID: xx`	No 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: xx`	The token failed for an unspecified reason.
`OAuth authorization request denied due to unexpected active login session for "Closed" User ID: xx`	There is already an active session for an account that is in the Closed status.

Last modified: June 14, 2024