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.
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.
Single Sign-On via API
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: September 9, 2024