Difference between revisions of "WHMCS Single Sign-On Developer Guide"

From WHMCS Documentation

m (Single Sign-on Workflow)
 
Line 1: Line 1:
 
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.
 
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.
 
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 via API==
 +
The [https://developers.whmcs.com/api-reference/createssotoken/ 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==
 
==Single Sign-on Workflow==
 
+
Here's how the process works.
+
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
 
# 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
 
# 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 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.
 
# The user is authenticated and redirected to the requested destination.
 
+
 
Performing Single Sign-On requires an [https://developers.whmcs.com/api-reference/createoauthcredential/ OAuth Credential Set] with the single sign-on grant type.
 
Performing Single Sign-On requires an [https://developers.whmcs.com/api-reference/createoauthcredential/ 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 [https://developers.whmcs.com/api-reference/createoauthcredential/ 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==
 
==Supported Destinations==
 
+
 
<table class="table table-striped">
 
<table class="table table-striped">
<tr><td>'''Scope Name'''</td><td>'''Destination'''</td></tr>
+
<tr><td>'''Scope Name'''</td><td>'''Destination'''</td><td>'''Variable Input'''</td></tr>
<tr><td>clientarea:profile</td><td>My Details</td></tr>
+
<tr><td>clientarea:profile</td><td>My Details</td><td></td></tr>
<tr><td>clientarea:billing_info</td><td>Manage Billing Information/Credit Card</td></tr>
+
<tr><td>clientarea:billing_info</td><td>Manage Billing Information/Credit Card</td><td></td></tr>
<tr><td>clientarea:emails</td><td>My Emails</td></tr>
+
<tr><td>clientarea:emails</td><td>My Emails</td><td></td></tr>
<tr><td>clientarea:announcements</td><td>Announcements</td></tr>
+
<tr><td>clientarea:announcements</td><td>Announcements</td><td></td></tr>
<tr><td>clientarea:downloads</td><td>Downloads</td></tr>
+
<tr><td>clientarea:downloads</td><td>Downloads</td><td></td></tr>
<tr><td>clientarea:knowledgebase</td><td>Knowledgebase</td></tr>
+
<tr><td>clientarea:knowledgebase</td><td>Knowledgebase</td><td></td></tr>
<tr><td>clientarea:network_status</td><td>Network Status</td></tr>
+
<tr><td>clientarea:network_status</td><td>Network Status</td><td></td></tr>
<tr><td>clientarea:services</td><td>My Products/Services</td></tr>
+
<tr><td>clientarea:services</td><td>My Products/Services</td><td></td></tr>
<tr><td>clientarea:product_details</td><td>Product Details/Information</td></tr>
+
<tr><td>clientarea:product_details</td><td>Product Details/Information</td><td>service_id</td></tr>
<tr><td>clientarea:domains</td><td>My Domains</td></tr>
+
<tr><td>clientarea:domains</td><td>My Domains</td><td></td></tr>
<tr><td>clientarea:domain_details</td><td>Domain Details/Information</td></tr>
+
<tr><td>clientarea:domain_details</td><td>Domain Details/Information</td><td>domain_id</td></tr>
<tr><td>clientarea:invoices</td><td>My Invoices</td></tr>
+
<tr><td>clientarea:invoices</td><td>My Invoices</td><td></td></tr>
<tr><td>clientarea:tickets</td><td>My Support Tickets</td></tr>
+
<tr><td>clientarea:tickets</td><td>My Support Tickets</td><td></td></tr>
<tr><td>clientarea:submit_ticket</td><td>Open New Ticket</td></tr>
+
<tr><td>clientarea:submit_ticket</td><td>Open New Ticket</td><td></td></tr>
<tr><td>clientarea:shopping_cart</td><td>Shopping Cart Default Product Group</td></tr>
+
<tr><td>clientarea:shopping_cart</td><td>Shopping Cart Default Product Group</td><td></td></tr>
<tr><td>clientarea:shopping_cart_addons</td><td>Shopping Cart Addons</td></tr>
+
<tr><td>clientarea:shopping_cart_domain_register</td><td>Shopping Cart Register Domain</td><td></td></tr>
<tr><td>clientarea:shopping_cart_domain_register</td><td>Shopping Cart Register Domain</td></tr>
+
<tr><td>clientarea:shopping_cart_domain_transfer</td><td>Shopping Cart Transfer Domain</td><td></td></tr>
<tr><td>clientarea:shopping_cart_domain_transfer</td><td>Shopping Cart Transfer Domain</td></tr>
+
<tr><td>clientarea:upgrades</td><td>Shopping Cart Addons</td><td>service_id</td></tr>
 +
<tr><td>sso:custom_redirect (API only)</td><td>Custom path of the WHMCS deployment</td><td>sso_redirect_path</td></tr>
 
</table>
 
</table>
 
+
 
==Failure Definitions==
 
==Failure Definitions==
 
+
 
The following are the possible error messages you may receive in working with the Single Sign-On API:
 
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''<br />
 
''Single Sign-On authentication denied for "Closed" User ID: xx''<br />
 
Single Sign-On can only be performed for clients in Active or Inactive status.
 
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''<br />
 
''Single Sign-On authentication denied per configuration for User ID: xx''<br />
 
Single Sign-On will not be permitted if the client has disabled it via the Security Settings of their account.
 
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''<br />
 
''Unable to authenticate with Single Sign-On token for User ID: xx''<br />
 
If authentication with the given token fails for an unspecified reason.
 
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''<br />
 
''OAuth authorization request denied due to unexpected active login session for "Closed" User ID: xx''<br />
 
Indicates the user has an existing active session that they are not permitted to have due to the account status being Closed.
 
Indicates the user has an existing active session that they are not permitted to have due to the account status being Closed.

Latest revision as of 15:14, 24 March 2020

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 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.

  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.

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 NameDestinationVariable 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

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.