WHMCS Single Sign-On Developer Guide

From WHMCS Documentation

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.

Single Sign-on Workflow

Here's how the process works.

  1. The application requests an access token by sending its credentials to the OAuth Token API Endpoint
  2. If the application credentials check out, the WHMCS auth server will return an access token to the application
  3. The application then redirects the user to the Single Sign-On API Endpoint passing in the token and desired destination (scope)
  4. 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.

Supported Destinations

Scope NameDestination
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/Information
clientarea:domainsMy Domains
clientarea:domain_detailsDomain Details/Information
clientarea:invoicesMy Invoices
clientarea:ticketsMy Support Tickets
clientarea:submit_ticketOpen New Ticket
clientarea:shopping_cartShopping Cart Default Product Group
clientarea:shopping_cart_addonsShopping Cart Addons
clientarea:shopping_cart_domain_registerShopping Cart Register Domain
clientarea:shopping_cart_domain_transferShopping Cart Transfer Domain

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.