WHMCS Single Sign-On Developer Guide
WHMCS Single Sign-on allows trusted applications and third parties to authenticate users into a WHMCS installation automatically, without the user having to re-authenticate.
Our Single Sign-On implementation is based on the popular and widely used OAuth 2.0 authorization framework which outlines a secure workflow for accessing user data while protecting their account credentials.
Contents
Single Sign-on via API
The CreateSsoToken API is the simplest way to generate SSO Tokens because the action of authenticating with authorized admin API credentials has implicit trust. IE, the API action replaces the first of a two-legged OAuth authentication workflow.
Simply perform the API call and redirect your user to the provided redirect_url.
This method of integration is only appropriate when the remote system is completely isolated from user-level access or modification due to the use of admin level API credentials.
Single Sign-on Workflow
When integrating an application, here's how the process works.
- The application requests an access token by sending its credentials to the OAuth Token API Endpoint
- If the application credentials check out, the WHMCS auth server will return an access token to the application
- The application then redirects the user to the Single Sign-On API Endpoint passing in the token and desired destination (scope)
- The user is authenticated and redirected to the requested destination.
Performing Single Sign-On 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 trust credentials used (see OAuth Credential Set) will be limited to the individual user so there is no risk of generating tokens to resources or destinations beyond their ownership.
Supported Destinations
| Scope Name | Destination | 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 |
Failure Definitions
The following are the possible error messages you may receive in working with the Single Sign-On API:
Single Sign-On authentication denied for "Closed" User ID: xx
Single Sign-On can only be performed for clients in Active or Inactive status.
Single Sign-On authentication denied per configuration for User ID: xx
Single Sign-On will not be permitted if the client has disabled it via the Security Settings of their account.
Unable to authenticate with Single Sign-On token for User ID: xx
If authentication with the given token fails for an unspecified reason.
OAuth authorization request denied due to unexpected active login session for "Closed" User ID: xx
Indicates the user has an existing active session that they are not permitted to have due to the account status being Closed.